Customizing Filters and Actions
Relevant source files
The following files were used as context for generating this wiki page:
Customizing filters and actions allows developers to extend Cloud Custodian by adding specific logic for cloud resource management. The system employs a registry-based architecture where individual resource classes maintain their own collections of valid filters and actions. This modular approach ensures that policies can only use components relevant to the targeted resource type.
Filters evaluate resource state to determine policy applicability, while actions execute operations on matched resources. Both components require specific metadata, including JSON schemas for validation and IAM permission sets for execution.
Core Component Registration
Cloud Custodian resources utilize a registration pattern to associate filters and actions with specific resource types. Each resource class, such as ApacheAirflow or FSx, provides a filter_registry and action_registry to handle these associations.
The Registration Flow
The registration process involves decorating custom classes with the resource-specific registry. This process maps a string identifier (the type used in YAML policies) to a Python class implementation.
The diagram shows the relationship between resource registries and custom implementations during registration and policy loading.
Sources: c7n/resources/airflow.py:39-60, c7n/resources/fsx.py:91-118
Registration Example
In the following example, a custom action and filter are registered for the Apache Airflow resource:
@ApacheAirflow.filter_registry.register('kms-key')
class ApacheAirflowKmsFilter(KmsRelatedFilter):
RelatedIdsExpression = 'KmsKey'
@ApacheAirflow.action_registry.register('update-environment')
class UpdateApacheAirflowEnvironment(Action):
permissions = ('airflow:UpdateEnvironment',)
schema = type_schema(
'update-environment',
access_mode={'type': 'string', 'enum': ['PRIVATE_ONLY', 'PUBLIC_ONLY']},
required=['access_mode']
)
Sources: c7n/resources/airflow.py:39-42, c7n/resources/airflow.py:73-88
Implementing Custom Actions
Custom actions inherit from base classes like Action or BaseAction. They must define the operational logic, required permissions, and a validation schema.
Action Architecture
Actions primarily implement the process method, which receives a list of resources that matched the policy filters.
| Component | Purpose | Implementation Detail |
|---|---|---|
permissions | Defines IAM requirements | A tuple of strings, e.g., ('sagemaker:AddTags',) |
schema | Validates YAML configuration | Defined using type_schema helper |
process() | Executes the primary logic | Iterates over matched resources to perform API calls |
Sources: c7n/resources/sagemaker.py:530-550, c7n/resources/airflow.py:73-95
Processing Logic
Actions often include secondary methods like process_resource_set to handle batch operations or specialized resource updates.
def process(self, resources):
resources = self.filter_resources(resources, 'Status', self.valid_origin_states)
client = local_session(self.manager.session_factory).client('mwaa')
access_mode = self.data.get('access_mode')
for r in resources:
self.process_environment(r, client, access_mode)
Sources: c7n/resources/airflow.py:90-95
Implementing Custom Filters
Custom filters evaluate resources against specific criteria. While many filters use the standard ValueFilter, complex logic requires subclassing Filter, ListItemFilter, or KmsRelatedFilter.
Filter Types and Inheritance
This diagram illustrates the inheritance structure for custom filters used in resource management.
Sources: c7n/resources/fsx.py:102, tools/c7n_gcp/c7n_gcp/resources/resourcemanager.py:155
Specialized Filter Logic
Complex filters such as the ConsecutiveBackups filter for FSx perform supplemental API calls to evaluate historical data. These filters often annotate resources with found data using an annotation key to avoid redundant API calls.
Sources: c7n/resources/fsx.py:534-583
Schema and Permission Metadata
Metadata is critical for both runtime validation and automated documentation. The type_schema utility generates the standard JSON schema for component configuration.
Permission Resolution
The documentation generator (docgen.py) resolves permissions by simulating policy construction if they are not explicitly defined. It maps resources to provider-specific dummy types (e.g., kinesis for AWS, vm for Azure) to test permission generation.
Sources: tools/c7n_sphinxext/c7n_sphinxext/docgen.py:58-90
Dynamic CCAPI Integration
For AWS Cloud Control API (AWSCC) resources, filters and actions are initialized dynamically. The system loads properties from JSON metadata files, generating update schemas by filtering out createOnlyProperties and readOnlyProperties.
Sources: tools/c7n_awscc/c7n_awscc/manager.py:34-78, tools/c7n_awscc/c7n_awscc/manager.py:84-110
Summary of Extension Points
Customizing filters and actions requires adhering to the registry patterns established for each resource. Developers define class-level metadata for permissions and schemas, and implement logic within the process methods. This structure enables Cloud Custodian to validate policies before execution and automatically generate comprehensive documentation for the customized components.