Cloud Custodian

0.9.50 · active · verified Fri Apr 10

Cloud Custodian (c7n) is an open-source, cloud-native rules engine for managing public cloud accounts and resources. It enables users to define policies in simple YAML files to ensure well-managed, secure, and cost-optimized cloud infrastructure. It supports major cloud providers like AWS, Azure, and GCP, and can execute policies in real-time (via serverless functions) or periodically (via scheduled jobs). The current version is 0.9.50, and it maintains an active release cadence with frequent updates and feature additions.

Warnings

gotcha Forgetting to install cloud-specific packages (e.g., `c7n_azure`, `c7n_gcp`) will lead to errors when trying to run policies for those providers, as the necessary resource modules will be missing.
Fix: Always install the base `c7n` package along with the specific package(s) for your target cloud(s), e.g., `pip install c7n c7n_azure`.
gotcha Always use the `--dryrun` flag when developing or testing new policies, especially those with `actions`. This prevents unintended modifications or deletions of cloud resources by showing what actions *would* be taken.
Fix: Execute `custodian run --dryrun -s . policy.yml` to review policy impact before running without `--dryrun`.
gotcha Cloud Custodian policies are written in YAML. Incorrect YAML syntax (e.g., indentation errors, missing `policies:` root key) is a common cause of `PolicyValidationError` or `YAMLError` during execution.
Fix: Use a YAML linter or editor with YAML validation. Ensure the policy file starts with `policies:` followed by a list of policy definitions.
breaking Cloud Custodian currently requires Python >=3.10.2 and <4.0.0. Using older Python versions will result in installation failures or runtime errors due to dropped support.
Fix: Upgrade your Python environment to a supported version (e.g., Python 3.10.x or 3.11.x).
gotcha Proper cloud provider credentials must be configured in the execution environment (e.g., AWS CLI configuration, environment variables like `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION` for AWS). Without them, policies cannot interact with cloud APIs.
Fix: Refer to your cloud provider's SDK/CLI documentation for credential configuration. For AWS, ensure `~/.aws/credentials` and `~/.aws/config` are set up, or relevant environment variables are exported.
gotcha For managing policies across multiple cloud accounts, subscriptions, or projects in parallel, the `c7n-org` tool is necessary. Running `custodian` directly will only target the configured account/region.
Fix: Install `c7n-org` (`pip install c7n_org`) and use its configuration and commands for multi-target execution.
gotcha When deploying real-time policies using 'mode' (e.g., `cloudtrail`, `periodic`), Cloud Custodian automatically provisions serverless functions (like AWS Lambda). Incorrect or insufficient IAM permissions for the Custodian execution role can lead to deployment failures or policy execution errors within the serverless environment.
Fix: Ensure the IAM role used by Cloud Custodian has the necessary permissions to provision cloud resources (e.g., Lambda functions, CloudWatch Events) and to perform the actions defined in your policies. Consult the Cloud Custodian documentation's 'IAM Setup' section for detailed requirements.

Install

pip install c7n Base (includes AWS support)
pip install c7n_azure Azure Support
pip install c7n_gcp GCP Support
pip install c7n_oci OCI Support

Imports

Policy
```
from c7n.policy import Policy
```
Cloud Custodian is primarily a CLI tool. Direct Python imports are mostly for advanced use cases like building custom extensions, testing, or programmatic policy loading, not typical end-user policy execution.

Quickstart

This quickstart demonstrates how to define a simple policy in a YAML file (`policy.yml`) to identify unencrypted S3 buckets in AWS and then execute it using the `custodian` CLI tool. The `--dryrun` flag allows you to preview actions without making actual changes. Ensure your AWS credentials are configured (e.g., via `~/.aws/credentials` or environment variables) for `custodian` to interact with your cloud environment.

# policy.yml
policies:
  - name: find-unencrypted-s3-buckets
    resource: aws.s3
    filters:
      - type: unencrypted
    actions:
      # Remove or comment out 'actions' for a pure dry-run without notification setup
      - type: notify
        violation_messages:
          - "S3 bucket {resource_id} in {account_id} is not encrypted!"
        to:
          - "{{ resource_owner_email | default(owner@example.com) }}"
        transport:
          type: sqs # Requires c7n-mailer and an SQS queue named 'cloud-custodian-notifications'
          queue: cloud-custodian-notifications

# To run the policy (ensure AWS credentials are configured):
custodian run --dryrun -s . policy.yml

view raw JSON →