Writing Policies
Relevant source files
The following files were used as context for generating this wiki page:
Cloud Custodian (c7n) uses a rules engine to manage public cloud accounts and resources through YAML configuration files. These policies define a specific vocabulary of filters and actions that enforce security, compliance, and cost optimization across AWS, Azure, GCP, and Infrastructure as Code (IaC) assets.
Sources: README.md:27-35, README.md:46-48
Policy Anatomy
Every Custodian policy follows a structured schema consisting of five primary top-level keys. This structure ensures the rules engine can identify the target resource, determine how to trigger the policy, and apply specific logic to matched assets.
The diagram above illustrates the hierarchy of core policy components required for a valid configuration.
Sources: README.md:104-108, c7n/commands.py:236-240
Core Components Summary
| Component | Description | Example |
|---|---|---|
| Name | A unique string identifying the policy. | s3-cross-account |
| Resource | The cloud resource type or provider-prefixed asset. | aws.s3, terraform.aws_lb |
| Mode | Defines how the policy is executed (e.g., cron, event-driven). | type: cloudtrail |
| Filters | Narrow down the set of resources from all available assets. | type: value, type: cross-account |
| Actions | The operations performed on resources that pass the filters. | type: terminate, type: tag |
Sources: README.md:112-140, tools/c7n_left/README.md:65-72
Policy Execution Workflow
When a user executes the custodian run or custodian validate command, the engine processes the YAML through several stages: loading, validation, variable expansion, and execution.
The sequence diagram details the internal lifecycle of a policy from file ingestion to action execution.
Sources: c7n/commands.py:44-95, c7n/commands.py:202-230
Variable Expansion
Policies support variable interpolation. Prior to execution, Custodian expands variables using environment variables or dedicated variable files. This allows for dynamic policy names or filter values (e.g., {env[REPO]}).
Sources: c7n/commands.py:112-120, tools/c7n_left/README.md:214-220
Validation and Schema
The custodian validate command uses a JSON schema to ensure policy integrity. It checks for:
- Duplicate policy names across multiple files.
- Invalid resource types or mismatched provider prefixes.
- Deprecated actions or filters.
Sources: c7n/commands.py:218-232, c7n/commands.py:255-270
Advanced Filtering
Beyond standard value filters, Custodian provides specialized filters for complex environments, particularly for Infrastructure as Code (IaC) and tagging compliance.
The Traverse Filter
Used primarily in c7n-left (IaC evaluation), the traverse filter allows multi-hop graph traversal. You can check relationships between resources, such as ensuring an EC2 instance is attached to a Security Group with specific ingress rules.
Sources: tools/c7n_left/README.md:175-185
Taggable and Resource Wildcards
In multi-cloud or IaC environments, you can use the taggable filter combined with resource wildcards (e.g., terraform.aws*) to enforce global tagging standards across all supported resource types simultaneously.
Sources: tools/c7n_left/README.md:158-168
Policy Metadata and Documentation
Policy files often include a metadata or description block. These are used by external tools for reporting and automated documentation.
- Severity: Categorizes policies (e.g.,
critical,high,medium,low) for prioritized reporting. - Category: Groups policies into functional areas like
Security & GovernanceorCost Controls. - Source Citation: Tools like
c7n-autodocuse regex to map local policy files to URLs in GitLab or GitHub.
Sources: tools/c7n_left/c7n_left/output.py:236-245, tools/sandbox/c7n_autodoc/c7n-autodoc.py:73-85
Modes of Execution
The mode determines the runtime environment and trigger for the policy.
- Pull Mode (Default): The policy runs against all existing resources when the CLI is executed manually or via cron.
- Event Mode: Triggered by cloud-native events (e.g., AWS CloudTrail, Azure EventGrid).
- Container Modes: Specifically for Azure,
container-periodicorcontainer-eventmodes are required for policies executed within a container host.
Sources: README.md:124-129, tools/ops/azure/container-host/devops-flow/README.md:24-25
Conclusion
Writing policies in Cloud Custodian requires adhering to a strict YAML schema that balances resource targeting, filtering logic, and action enforcement. By utilizing advanced filters like traverse and leveraging automated validation, developers can manage complex cloud infrastructures at scale while maintaining clear documentation and governance standards.