Getting Started

The GCP provider is an optional package which can be installed to enable writing policies which interact with GCP related resources.

Install GCP Plugin

First, ensure you have installed the base Cloud Custodian application. Cloud Custodian is a Python application and must run on an actively supported version.

Once the base install is complete, you are now ready to install the GCP provider package using one of the following options:

Option 1: Install released packages to local Python Environment

pip install c7n
pip install c7n-gcp

Option 2: Install latest from the repository

git clone https://github.com/cloud-custodian/cloud-custodian.git
pip install -e ./cloud-custodian
pip install -e ./cloud-custodian/tools/c7n_gcp

Connect Your Authentication Credentials

In order for Custodian to be able to interact with your GCP resources, you will need to configure your GCP authentication credentials on your system in a way in which the application is able to retrieve them.

Choose from one of the following methods to configure your credentials, depending on your use case. In either option, after the configuration is complete, Custodian will implicitly pick up your credentials when it runs.

GCP CLI

If you are a general user accessing a single account, then you can use the GCP CLI to configure your credentials.

First, install gcloud (the GCP Command Line Interface).

Then run the following command, substituting your username:

gcloud auth application-default login

Executing the command will open a browser window with prompts to finish configuring your credentials. For more information on this command, view its documentation.

Environment Variables

GOOGLE_CLOUD_PROJECT should be set to the target project to act on.

If you are planning to run Custodian using a service account, or workload identity federation then configure your credentials using environment variables.

GOOGLE_APPLICATION_CREDENTIALS should be set to a valid service account file or client config for workload federation.

For service account configuration see additional docs here

For workload configuration see additional docs

If you are planning to impersonate a service account, then you may configure the environment variable GOOGLE_IMPERSONATE_SERVICE_ACCOUNT with the service account email address, you can also pass this the service account email via –assume cli flag.

export GOOGLE_IMPERSONATE_SERVICE_ACCOUNT="impersonated-account@_project_.iam.gserviceaccount.com"

If running on gcp compute some of these values can be obtained automatically from metadata server, see https://cloud.google.com/python/docs/reference/google-cloud-core/latest/config for precedence and availability of different options.

Write Your First Policy

A policy is the primary way that Custodian is configured to manage cloud resources. It is a YAML file that follows a predetermined schema to describe what you want Custodian to do.

There are three main components to a policy:

Resource: the type of resource to run the policy against
Filters: criteria to produce a specific subset of resources
Actions: directives to take on the filtered set of resources

In the example below, we will write a policy that filters for compute engine resources, and then stops each resource.

Filename: custodian.yml

policies:
  - name: my-first-policy
    description: |
      Stops all compute instances that are named "test"
    resource: gcp.instance
    filters:
      - type: value
        key: name
        value: test
    actions:
      - type: stop

Run Your Policy

First, ensure you have configured one of the supported authentication mechanisms.

Next, run the following command to execute the policy with Custodian:

GOOGLE_CLOUD_PROJECT="project-id" custodian run --output-dir=. custodian.yml

If successful, you should see output similar to the following on the command line:

2016-12-20 08:35:06,133: custodian.policy:INFO Running policy my-first-policy resource: gcp.instance
2016-12-20 08:35:07,514: custodian.policy:INFO policy: my-first-policy resource: gcp.instance has count:3 time:1.38
2016-12-20 08:35:08,188: custodian.policy:INFO policy: my-first-policy action: stop: 3 execution_time: 0.67

You should also find a new my-first-policy directory with a log and other files (subsequent runs will append to the log by default, rather than overwriting it).

See Generic Filters for more information on the features of the Value filter used in this sample.