Policy Execution Modes

Relevant source files

The following files were used as context for generating this wiki page:

• c7n/policy.py
• c7n/schema.py
• c7n/commands.py
• README.md
• tools/c7n_sphinxext/c7n_sphinxext/docgen.py

Policy Execution Modes define the runtime environment and trigger mechanisms for Cloud Custodian policies. These modes determine how a policy discovers resources, whether it runs locally on a CLI or as a serverless function, and how it responds to cloud-native events.

Every policy includes a mode key in its YAML definition. If no mode is specified, the policy defaults to pull mode, which executes locally. Execution modes integrate with cloud-native serverless capabilities to provide real-time enforcement and automated provisioning of event sources.

Sources: c7n/policy.py:355-370, README.md:57-65, c7n/schema.py:339-341

Core Architecture

The execution mode system follows a provider-pluggable registry pattern. The base class PolicyExecutionMode defines the interface for running policies, provisioning infrastructure, and retrieving metrics or logs.

The diagram shows the inheritance hierarchy of policy execution modes, starting from the base interface to specialized serverless implementations.
Sources: c7n/policy.py:322-353, c7n/policy.py:373-375, c7n/policy.py:440-442

Pull Mode

Pull mode queries resources directly from the cloud provider via API calls. It is the default execution method when running custodian run from the command line.

• Discovery: Queries resources using the resource manager's poll mechanism.
• Execution: Filters matched resources and executes defined actions sequentially.
• Metrics: Captures ResourceCount, ResourceTime, and ActionTime.

Sources: c7n/policy.py:373-437

Serverless and Lambda Modes

LambdaMode serves as the foundation for all AWS-based serverless execution. It allows policies to run in response to events rather than active polling.

• Provisioning: The provision() method publishes the policy as a Lambda function and configures event sources like EventBridge or AWS Config.
• Event Resolution: The resolve_resources() method extracts resource identifiers from the incoming event (e.g., a CloudTrail log entry).
• IAM Interaction: Supports member-role to assume roles in member accounts when triggered from a master account.

Sources: c7n/policy.py:504-540, c7n/policy.py:643-670

Specialized Execution Modes

Cloud Custodian provides specialized modes to integrate with various cloud provider event streams and governance services.

Mode Type	Trigger Source	Description
periodic	EventBridge (Cron)	Runs a pull-style policy inside a Lambda function at defined intervals.
cloudtrail	CloudTrail	Responds to specific API calls (e.g., RunInstances) detected in CloudTrail.
config-rule	AWS Config	Executes as a Custom Config Rule, evaluating resources upon configuration changes.
schedule	EventBridge Scheduler	Similar to periodic but uses the specialized EventBridge Scheduler service.
guard-duty	GuardDuty	Triggers incident response policies based on GuardDuty security findings.
phd	Health Dashboard	Responds to AWS Personal Health Dashboard events regarding service health.

Sources: c7n/policy.py:673-685, c7n/policy.py:688-710, c7n/policy.py:749-780, c7n/policy.py:863-895

CloudTrail Mode Workflow

CloudTrail mode provides near real-time enforcement by reacting to API events.

The flowchart illustrates the data path from a user API call through CloudTrail to the eventual execution of a Custodian policy action.
Sources: c7n/policy.py:749-775, README.md:104-118

Configuration and Validation

Execution modes are configured via the mode block in the policy YAML. Each mode has a specific schema validated by Custodian before execution.

Example Configuration

policies:
  - name: ec2-auto-terminate
    resource: aws.ec2
    mode:
      type: cloudtrail
      role: CloudCustodian-ExecutionRole
      events:
        - RunInstances
    filters:
      - type: ebs
        key: Encrypted
        value: false
    actions:
      - terminate

Sources: README.md:104-118

Schema Validation

The c7n.schema module ensures that the mode block contains the required parameters for the chosen type. For instance, config-poll-rule requires a schedule, while cloudtrail requires events.

• Registry: The execution registry in c7n/policy.py tracks all available modes.
• Validator: The validate() method in each mode class checks for specific constraints, such as the 64-character limit for Lambda function names.

Sources: c7n/schema.py:339-341, c7n/policy.py:542-563, c7n/policy.py:910-928

Metrics and Logs

Execution modes handle the reporting of policy performance and matches to cloud-native monitoring tools.

• CloudWatch Metrics: Modes like PullMode and LambdaMode put metrics such as ResourceCount and ActionTime into the CloudCustodian namespace.
• Output Management: The ExecutionContext managed by the policy handles writing resources.json and action results to the configured output destination (e.g., S3 or local directory).

Sources: c7n/policy.py:397-425, c7n/policy.py:596-620, c7n/commands.py:277-290

Policy execution modes allow Cloud Custodian to scale from local testing and auditing to automated, real-time cloud governance. By abstracting the trigger mechanism, Custodian enables identical filter and action logic to be reused across periodic audits and event-driven enforcement.

Sources: c7n/policy.py:355-370, README.md:38-48