Getting Started

See also the readme in the GitHub repository.

Install Cloud Custodian

Cloud Custodian is a Python application and supports Python 2 and 3 on Linux and Windows.

We recommend using Python 3.6 or higher.

Linux and Mac OS

To install Cloud Custodian, just run:

$ python3 -m venv custodian
$ source custodian/bin/activate
(custodian) $ pip install c7n       #Install AWS package
(custodian) $ pip install c7n_azure #Install Azure package
(custodian) $ pip install c7n_gcp   #Install GCP Package

Windows (CMD/PowerShell)

To install Cloud Custodian, just run:

$ python3 -m venv custodian
$ ./custodian/Scripts/activate
(custodian) $ pip install c7n       #Install AWS package
(custodian) $ pip install c7n_azure #Install Azure package
(custodian) $ pip install c7n_gcp   #Install GCP Package

Explore Cloud Custodian

Run custodian -h to see a list of available commands.

Run custodian schema to see the complete list of cloud resources against which you can run policies. To invoke command-line help with more information about policy schema details, run custodian schema -h.

Run custodian schema <cloud-provider> to see the available resources for a specific cloud provider: custodian schema aws

Run custodian schema <cloud-provider>.<resource> to see the available filters and actions for each resource.

Drill down to get more information about available policy settings for each resource, where the model for the command is:

$ custodian schema <cloud>.<resource>.<category>.<item>

For example:

$ custodian schema

provides the following information:


Filter and return buckets are log destinations.

Not suitable for use in lambda on large accounts, This is a api
heavy process to detect scan all possible log sources.

  - elb (Access Log)
  - s3 (Access Log)
  - cfn (Template writes)
  - cloudtrail


    .. code-block: yaml

          - name: s3-log-bucket
            resource: s3
              - type: is-log-target


{   'additionalProperties': False,
    'properties': {   'type': {   'enum': ['is-log-target']},
                      'value': {   'type': 'boolean'}},
    'required': ['type'],
    'type': 'object'}

Additionally, you can use the schema command to view information on the different supported modes in Cloud Custodian:

$ custodian schema mode

Cloud Provider Specific Help

For specific setup isntructions for AWS, Azure, and GCP, visit the relevant getting started page.

Troubleshooting & Tinkering

The policy is validated automatically when you run it, but you can also validate it separately:

$ custodian validate custodian.yml

You can also check which resources are identified by the policy, without running any actions on the resources:

$ custodian run --dryrun -s . custodian.yml

Monitor resources

Additional commands let you monitor your services in detail.

You can generate metrics, log outputs, and output to blob storage in each of the different providers (AWS, Azure, Google Cloud Platform).

For detailed instructions on how to add metrics, logging, and blob storage output for the different clouds, check out the cloud provider specific pages:

For details, see Monitoring your environment.

Tab Completion

To enable command-line tab completion for custodian on bash do the following one-time steps:



Now launch a new shell (or refresh your bash environment by sourcing the appropriate file).


If you get an error about “complete -D” not being supported, you need to update bash. See the “Base Version Compatability” note in the argcomplete docs:

If you have other errors, or for tcsh support, see the argcomplete docs.

If you are invoking custodian via the python executable tab completion will not work. You must invoke custodian directly.