Getting Started & Installation
Relevant source files
The following files were used as context for generating this wiki page:
Cloud Custodian (c7n) is a rules engine that manages public cloud accounts and resources through YAML policies. It supports AWS, Azure, and GCP environments to ensure security compliance, tag enforcement, and cost management. The project provides multiple installation methods including standard Python packages, Docker images, and development environments using uv.
Sources: README.md:16-24, README.md:38-40
Core Installation Methods
Standard Installation
The primary method for installing Cloud Custodian involves using a Python virtual environment and pip. This installs the core c7n package from PyPI.
- Create a Python virtual environment:
python3 -m venv custodian - Activate the environment:
source custodian/bin/activate - Install the core package:
pip install c7n
Sources: README.md:103-108
Docker Installation
Cloud Custodian is available as a Docker image for environments where a local Python installation is not preferred.
- Download the image:
docker pull cloudcustodian/c7n - Execute a policy by mounting the local policy file and output directory:
docker run -it \ -v $(pwd)/output:/home/custodian/output \ -v $(pwd)/policy.yml:/home/custodian/policy.yml \ --env-file <(env | grep "^AWS\|^AZURE\|^GOOGLE") \ cloudcustodian/c7n run -v -s /home/custodian/output /home/custodian/policy.yml
Sources: README.md:139-152
Architecture and Components
The following diagram illustrates the relationship between the core c7n package and its provider-specific tools.
This diagram shows the modular structure of Cloud Custodian, where the core engine interacts with various cloud providers and specialized tools.
Sources: README.md:255-285, pyproject.toml:94-107
System Requirements
The project requires specific Python versions and sets of dependencies depending on the desired functionality.
| Component | Python Version | Primary Dependencies |
|---|---|---|
| c7n Core | < 4.0.0, >= 3.10.2 | boto3, jsonschema, pyyaml, argcomplete |
| c7n_gcp | >= 3.9.2 | google-api-python-client, google-auth, pyrate-limiter |
| c7n_sphinxext | >= 3.9.2 | Sphinx, myst-parser, pygments |
| c7n_autodoc | Python 3 | pyyaml, boto3, jinja2, jsonschema |
Sources: pyproject.toml:7-16, tools/c7n_gcp/pyproject.toml:7-16, tools/c7n_sphinxext/pyproject.toml:7-17, tools/sandbox/c7n_autodoc/README.md:33-35
Developer Setup
For developers contributing to the project, Cloud Custodian uses the uv workspace manager for environment synchronization and dependency management.
Installation from Root
Developers must install dependencies from the repository root to ensure all workspace members are correctly linked in editable mode.
- Run the install command:
make install- This executes
uv sync --all-packages --locked --group dev --group addons --group lint --extra gcp --extra azure.
- This executes
- Activate the environment:
source .venv/bin/activate
Sources: tools/c7n_gcp/development.md:27-51
Authentication Configuration
Proper authentication is required to execute policies or run tests against real cloud providers.
- AWS: Credentials should be mounted from
.aws/credentialsand.aws/configwhen using Docker, or provided via standard environment variables. - GCP: The recommended approach is Application Default Credentials (ADC):
- Run
gcloud auth application-default login. - Set the project:
gcloud auth application-default set-quota-project <PROJECT_ID>.
- Run
- Azure: Infrastructure management may require service connections to specific resource groups and storage accounts.
Sources: README.md:158-163, tools/c7n_gcp/development.md:88-92, tools/c7n_gcp/development.md:139-142, tools/ops/azure/container-host/devops-flow/README.md:61-63
Initial Usage and Validation
Once installed, the custodian CLI allows users to interact with policies through three primary commands.
The sequence demonstrates the standard workflow for validating, testing via dry run, and finally executing a policy.
Sources: README.md:128-137
Basic Policy Structure
Policies are defined in YAML and consist of the following keys:
name: Unique identifier for the policy.resource: The cloud resource type (e.g.,aws.s3,gcp.instance).filters: Criteria to match specific resources.actions: Operations to perform on matched resources.mode: Execution method (e.g., periodic, cloudtrail, event-grid).
Sources: README.md:60-65, tools/ops/azure/container-host/devops-flow/README.md:21-22
Summary
Getting started with Cloud Custodian requires setting up a Python 3.10+ environment or utilizing the official Docker image. Users must configure provider-specific authentication (AWS CLI, GCP ADC, or Azure Service Connections) before executing YAML-based policies. The custodian validate and run --dryrun commands serve as critical first steps for policy development before deployment into production environments.