Getting Started (Beta)¶
The GCP provider (Beta) is an optional package which can be installed to enable writing policies which interact with GCP related resources.
Install GCP Plugin¶
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.
If you are a general user accessing a single account, then you can use the GCP CLI to configure your credentials.
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.
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 <https://cloud.google.com/iam/docs/service-account-overview>
For workload configuration see additional docs here <https://cloud.google.com/iam/docs/workload-identity-federation-with-other-clouds>
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.
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.
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
See Generic Filters for more information on the features of the Value filter used in this sample.