Credentials and Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Cloud Custodian manages cloud resources through provider-specific authentication mechanisms and structured YAML configuration files. The system supports multi-cloud environments including AWS, Azure, GCP, and OCI by leveraging native SDK credentials and environment-specific variable interpolation.
Organizations use configuration files to define policies, target accounts, and operational parameters. Authentication typically occurs via environment variables, service principals, or application default credentials depending on the cloud provider and execution environment.
Sources: README.md , tools/c7n_org/README.md
Provider Authentication
Each cloud provider requires specific credentials to allow Cloud Custodian to interact with its APIs.
Amazon Web Services (AWS)
Cloud Custodian uses standard AWS credential resolution. If you run Custodian via Docker, you must mount the .aws/credentials and .aws/config directories to the container. Alternatively, you pass environment variables for AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN.
Sources: README.md:162-176
Google Cloud Platform (GCP)
The system recommends Application Default Credentials (ADC) for local development. You authenticate by running gcloud auth application-default login. This command creates a JSON credential file in the user's config directory. You point the GOOGLE_APPLICATION_CREDENTIALS environment variable to this file. For testing, you must also set GOOGLE_CLOUD_PROJECT.
Sources: tools/c7n_gcp/development.md:27-28, tools/c7n_gcp/development.md:93-118
Microsoft Azure
Azure execution requires a Service Principal with access to target subscriptions. You manage these via Service Connections in environments like Azure DevOps.
Sources: tools/c7n_org/README.md:237-241, tools/ops/azure/container-host/devops-flow/README.md:47-49
Oracle Cloud Infrastructure (OCI)
OCI authentication uses profiles defined in the OCI configuration file. Each tenancy entry in a multi-account configuration specifies the profile and associated regions.
Sources: tools/c7n_org/README.md:73-78
Multi-Account Configuration (c7n-org)
The c7n-org tool manages parallel execution across multiple accounts, projects, or subscriptions. It requires a central configuration file that lists the target environments and their specific metadata.
Configuration Schema
The configuration structure varies by cloud provider but maintains consistent metadata fields.
| Provider | Key Metadata Fields | Source |
|---|---|---|
| AWS | account_id, name, regions, role, vars, tags | tools/c7n_org/README.md:33-47 |
| Azure | name, subscription_id | tools/c7n_org/README.md:52-56 |
| GCP | name, project_id, tags | tools/c7n_org/README.md:61-68 |
| OCI | name, profile, regions, vars, tags | tools/c7n_org/README.md:73-78 |
Config Logic Flow
The following diagram represents how c7n-org resolves environment settings for execution.
The diagram shows the sequence from loading the configuration file to provider-specific environment setup.
Sources: tools/c7n_org/README.md:88-142
Variable Interpolation
Cloud Custodian supports dynamic variables within policy definitions. You define these variables in the vars section of an account configuration file.
Usage in Policies
Variables use curly brace syntax {variable_name}. The system interpolates these values at runtime. You must quote the variable in YAML strings to prevent parsing errors.
# c7n-org config
accounts:
- account_id: '123123123123'
vars:
charge_code: xyz
# Policy file
policies:
- name: ec2-check-tag
resource: aws.ec2
filters:
- "tag:CostCenter": "{charge_code}"
Sources: tools/c7n_org/README.md:144-166
Built-in Variables
The system provides default runtime variables automatically:
account_idnowregion
Sources: tools/c7n_org/README.md:144-149
Automated Documentation Configuration
The c7n-autodoc utility uses a dedicated configuration file to generate HTML policy documentation. It validates inputs against a JSON schema to ensure all required paths and regex patterns exist.
Required Configuration Inputs
| Parameter | Description |
|---|---|
c7n_policy_directory | The local directory containing policy YAML files. |
file_regex | Pattern to identify policy files (e.g., custodian.*yml$). |
category_regex | Pattern to group policies into 'Security & Governance' vs 'Cost Controls'. |
jinja2_template_filename | The template used for HTML rendering. |
Sources: tools/sandbox/c7n_autodoc/c7n-autodoc.py:91-118, tools/sandbox/c7n_autodoc/example_config_file.yml:8-21
Execution Environment Configuration
Docker Execution
When running via Docker, authentication relies on passing environment variables or mounting host volumes.
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:151-159
CI/CD Pipeline Configuration (Azure)
Pipelines require specific variables to manage policy deployment to storage accounts.
AZURE_SERVICE_CONNECTION: Service connection name.STORAGE_ACCOUNT_NAME: Target storage account for policy files.POLICY_FILE_PATH: Local path to the policy directory.
Sources: tools/ops/azure/container-host/devops-flow/README.md:73-77
Cloud Custodian provides a flexible configuration framework that decouples policy logic from environment-specific credentials. By utilizing c7n-org for multi-account management and standard cloud provider authentication mechanisms, the system enables scalable governance across diverse infrastructure landscapes.
Sources: README.md, tools/c7n_org/README.md