Cloud Custodian is a rules engine for managing cloud environments as code. Each policy, written in YAML, names a resource type, filters resources by their properties, and applies actions to the ones that match: tag them, notify their owners, stop them, encrypt them or delete them. It addresses a problem every organisation with many cloud accounts faces: hundreds of teams create resources every day, and someone must make sure they are tagged, encrypted, not publicly exposed and not running up costs when idle. Kapil Thangavelu created Cloud Custodian at Capital One in 2016. It joined the CNCF sandbox in 2020 and was accepted as an incubating project in September 2022, the level the CNCF Landscape still lists.
CNCF daily · Sprint 2, day 7 · Automation & Configuration
At a glance
| Category | Provisioning › Automation & Configuration |
| CNCF status | Incubating. Accepted June 25, 2020; incubating September 14, 2022 |
| Written in | Python |
| License | Apache 2.0 |
| Providers | AWS (core c7n package), Azure (c7n_azure), Google Cloud (c7n_gcp), plus Kubernetes, OpenStack and others |
| Execution modes | Command-line runs (pull), scheduled serverless functions, and event-driven functions triggered by audit events |
| Companion tools | c7n-org (many accounts), c7n-mailer (notifications), c7n-left (policies against Terraform code) |
Architecture
flowchart TB
POL[Policy files<br/>YAML in Git] ==> CLI[custodian CLI<br/>or c7n-org across accounts]
CLI ==>|describe resources| API[Cloud provider APIs<br/>AWS, Azure, GCP]
CLI ==> FLT[Filters<br/>tags, config, metrics, age]
FLT ==> ACT[Actions<br/>tag, stop, encrypt, delete]
ACT ==>|change resources| API
CLI -.->|deploy| FN[Serverless function<br/>Lambda or Azure Function]
EVT[Audit events<br/>CloudTrail, Activity Log] -.->|trigger| FN
FN ==> FLT
ACT -.->|notify| MAIL[c7n-mailer<br/>email, Slack]
CLI -.->|results| OUT[Output and logs<br/>S3, CloudWatch, metrics]
classDef actor fill:#eceff1,stroke:#455a64,stroke-width:1.5px,color:#1d1c1a
classDef core fill:#0f766e,stroke:#064e4a,stroke-width:2px,color:#ffffff
classDef ctrl fill:#ede7f6,stroke:#5e35b1,stroke-width:1.5px,color:#1d1c1a
classDef data fill:#e3f2fd,stroke:#1565c0,stroke-width:1.5px,color:#1d1c1a
classDef sec fill:#fce4ec,stroke:#ad1457,stroke-width:1.5px,color:#1d1c1a
classDef obs fill:#e8f5e9,stroke:#2e7d32,stroke-width:1.5px,color:#1d1c1a
class POL sec
class CLI,FLT,ACT,FN,MAIL core
class API,EVT ctrl
class OUT obs
Key: teal blocks are the project itself, purple are cloud provider services, red is policy, green is output. Thick arrows show the main path, dashed arrows deployment, triggers and notifications.
| Component | Responsibility |
|---|---|
| Policy | YAML naming a resource (for example aws.ec2), a list of filters and a list of actions, plus an optional mode. |
| custodian CLI | Validates and runs policies, queries provider APIs, applies filters and actions, and writes results and logs. |
| Filters | Match resources on tags, configuration values, age, metrics (for example low CPU), relationships and more; filters can be combined with and, or and not. |
| Actions | Change matching resources: tag, mark for later action, stop, resize, encrypt, remove public access, delete, or notify. |
| Modes | pull runs on demand from the CLI; periodic deploys a scheduled function; cloudtrail and similar modes deploy a function triggered in near real time by audit events. |
| c7n-org, c7n-mailer, c7n-left | Run policies across many accounts, subscriptions and projects; send notifications to resource owners; and check infrastructure code before it is applied. |
Design principle. A policy is a query plus a response, written in a small vocabulary that security, operations and finance teams can all read. The same YAML can report problems, notify owners, or fix them automatically, so organisations can move from visibility to enforcement one policy at a time.
Production reference design
A typical setup governs an AWS Organization (the same pattern applies to Azure subscriptions and Google Cloud projects) from a central security or platform account.
- Install and validate the tooling, or use the official container image:
pip install c7n c7n-org c7n-mailer custodian validate policies/ custodian run --dryrun -s output/ policies/ec2-require-owner.yml - Write a policy. This one reacts within seconds when an EC2 instance is launched without an
Ownertag, stops it and tags it with the reason:policies: - name: ec2-require-owner-tag resource: aws.ec2 mode: type: cloudtrail role: arn:aws:iam::{account_id}:role/custodian-lambda events: - RunInstances filters: - "tag:Owner": absent actions: - stop - type: tag key: custodian-note value: missing-owner-tag - Roll out across accounts with
c7n-org, using an accounts file and a cross-account IAM role in each member account. - Start with report-only policies (no actions, or
notifyonly) and review the results before adding stop, delete or remediation actions. - Keep policies in Git with code review and CI that runs
custodian validate, and addc7n-leftto check Terraform plans against the same rules before deployment.
Typical uses include enforcing tagging standards, removing public access from storage buckets, enforcing encryption, stopping or deleting idle and untagged resources to save cost, and running off-hours schedules for development environments.
Operational considerations
- Blast radius. Actions such as
deleteandterminateact on every matching resource. Test with--dryrun, start in a single account, and usemark-for-opto schedule actions days ahead with a notification first. - IAM permissions. Custodian needs read access to describe resources and write access only for the actions you use. Scope the execution roles tightly and audit them.
- API rate limits. Large accounts with many policies can hit provider API limits. Prefer event-driven modes for real-time rules and stagger scheduled runs.
- Policy sprawl. Hundreds of policies across teams become hard to manage. Organise them by purpose (security, cost, operations), give each an owner, and track which ones remediate automatically.
- Event-driven deployment. Serverless modes deploy functions and event rules into every governed account. Manage them through
c7n-organd keep their versions consistent.
Adoption
- The CNCF announcement of Cloud Custodian’s move to incubation in September 2022 names Capital One, Code42, HBO Max, Intuit, JPMorgan Chase, Siemens, Premise Data and Zapier among its users.
- The same announcement reported more than 350 contributors from over 130 organisations.
- The project’s creator founded Stacklet, which offers a commercial governance platform built on Cloud Custodian.
Alternatives
| Solution | Model | Best suited to |
|---|---|---|
| AWS Config rules, Azure Policy, Google Cloud Organization Policy | Native, provider-specific policy and compliance services | Single-cloud organisations that prefer managed services |
| Open Policy Agent with Conftest | General-purpose Rego policies, often applied to configuration files and plans | Pre-deployment checks across many tools, beyond cloud resources |
| Checkov, tfsec | Static scanning of infrastructure-as-code | Catching misconfigurations in Terraform before apply |
| Commercial CSPM platforms | Managed cloud security posture with dashboards | Teams wanting vendor-run detection and reporting |
Strengths and limitations
| Strengths | Limitations |
|---|---|
| One readable YAML language across AWS, Azure, Google Cloud and Kubernetes | Python CLI and functions must be deployed and maintained by you |
| Can report, notify and remediate, from the same policy | Automatic actions can cause outages if policies are wrong |
| Real-time event-driven mode as well as scheduled scans | Large estates can hit API rate limits |
| Strong for cost control as well as security | Coverage and depth vary between providers; AWS is the most complete |
| Large production users and an independent security audit | Incubating, not yet graduated |
Recommendation
Trial. Cloud Custodian is a mature, widely used way to enforce tagging, security and cost policies across many cloud accounts with a single language, and it is especially valuable in multi-cloud or multi-account estates. Start with report-only policies in one account, add notifications, then enable automatic remediation for well-understood rules. Single-cloud teams should compare it with their provider’s native policy services before committing.
References: CNCF project page · Cloud Custodian documentation · Cloud Custodian repository · CNCF incubation announcement · CNCF Landscape