Multi-Account Management with c7n-org
Relevant source files
The following files were used as context for generating this wiki page:
c7n-org executes Cloud Custodian (c7n) policies against multiple cloud accounts, projects, or subscriptions in parallel. It supports AWS, Azure, GCP, and OCI environments, consolidating management of large cloud fleets into a single execution framework.
This tool functions as a multi-cloud management area within the Cloud Custodian project. It allows administrators to run policies, generate reports, and validate configurations across an entire organization using unified credentials and parallel processing.
Sources: tools/c7n_org/README.md:7-9, README.md:275-276, GOVERNANCE.md:14
System Architecture and Flow
c7n-org uses a central configuration file to define the target accounts and execution parameters. It invokes the core c7n library for each account identified in the configuration.
This diagram shows the flow from configuration and policy input to parallel execution across cloud providers and final output generation.
Execution Output Structure
When a policy runs, c7n-org creates a hierarchical directory structure to store results. The structure organizes files by account, region, and policy name.
This diagram illustrates the folder hierarchy created during execution to isolate results for each account and region.
Sources: tools/c7n_org/README.md:126-140
Configuration Management
c7n-org requires a configuration file containing account metadata. You can generate these files manually or via subcommands.
Configuration Fields
The following table summarizes common fields used in the account configuration files:
| Field | Description | Provider |
|---|---|---|
account_id | The unique numeric ID for the account. | AWS |
name | A friendly name for the account/subscription/project. | All |
regions | List of regions to target for execution. | AWS, OCI |
role | IAM Role ARN for cross-account access. | AWS |
vars | Key-value pairs for policy interpolation. | All |
tags | Labels for grouping accounts (e.g., type:prod). | All |
Sources: tools/c7n_org/README.md:30-80
Config Generation Commands
c7n-org provides specific commands and scripts to fetch account lists directly from cloud providers:
- AWS: Use
c7n-org aws-accounts -f accounts.ymlto query the AWS Organizations API. - Azure: Use
azuresubs.pyto query the Azure Resource Management API. - GCP: Use
gcpprojects.pyto query the GCP Resource Management API. - OCI: Use
ocitenancies.pyto query the OCI Organizations API.
Sources: tools/c7n_org/README.md:85-115
Command Reference
The c7n-org utility includes several commands for lifecycle management of multi-account policies.
| Command | Action |
|---|---|
run | Executes a policy across accounts in parallel. |
report | Aggregates results into a CSV report from the output directory. |
validate | Checks policy syntax without requiring cloud credentials. |
run-script | Runs an arbitrary shell script across accounts. |
aws-accounts | Generates a configuration file for AWS Organizations. |
Sources: tools/c7n_org/README.md:20-27
Policy Validation
The validate command supports a --per-account flag. This flag enables deeper validation by expanding account-specific variables defined in the vars section of the config file. This process catches missing variable definitions that would cause runtime failures.
Sources: tools/c7n_org/README.md:218-223
Filtering and Variable Interpolation
Execution Filters
You can limit the scope of execution using CLI flags:
- Account Filter (
-a): Select specific accounts by name or ID. - Tag Filter (
-t): Select groups of accounts based on tags in the config file (e.g.,-t scope:pci). - Policy Filter (
-p): Select specific policies by name. - Policy Tag Filter (
-l): Select policies by their metadata tags. - Region Filter (
-r): Specify regions; useallfor all available regions.
Sources: tools/c7n_org/README.md:144-162
Runtime Variables
Define variables in the vars section of the configuration file to customize policies for different accounts.
# 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}"
Note: Variable interpolation requires exact spacing. {charge_code} is valid, but { charge_code } is not.
Sources: tools/c7n_org/README.md:172-204
Summary of multi-account capabilities
c7n-org scales Cloud Custodian by managing parallel execution across heterogeneous cloud environments. It provides structured logging, aggregated reporting, and robust policy validation to maintain security and governance standards across thousands of accounts.