Core Filters
Relevant source files
The following files were used as context for generating this wiki page:
Core Filters provide the primary mechanism for selecting specific cloud resources during policy execution. These filters evaluate resource attributes against defined criteria to determine which resources match the policy's intent. The filtering system supports basic attribute matching, boolean logic, metrics evaluation, and complex list processing.
Sources: c7n/filters/core.py:7-16, README.md:104-109
Filter Architecture and Lifecycle
The FilterRegistry manages the discovery and instantiation of filter classes. Each resource type maintains its own registry, though most inherit a set of standard filters. When a policy loads, the registry uses a factory method to create filter instances based on the YAML configuration.
Filter Processing Flow
The following diagram illustrates how the engine evaluates filters against a set of resources:
The engine invokes the process() method for bulk resource evaluation, returning only the subset that satisfies all conditions.
Sources: c7n/filters/core.py:126-163, c7n/filters/core.py:202-204
Base Filter Classes
| Class | Purpose | Key Method |
|---|---|---|
Filter | Abstract base for all filtering logic. | process(resources, event) |
ValueFilter | Evaluates resource keys using JMESPath. | match(resource) |
BooleanGroupFilter | Base for And, Or, and Not logical groups. | validate() |
BaseValueFilter | Provides attribute extraction via get_resource_value. | get_resource_value() |
Sources: c7n/filters/core.py:192-230, c7n/filters/core.py:382-442
Logical and Boolean Filters
Boolean filters allow users to combine multiple conditions. The system defaults to an implicit And relationship between filters listed in a policy.
- And: Returns resources that satisfy every nested filter. It uses an
AnnotationSweeperto clear metadata if any sub-filter fails. - Or: Returns resources that satisfy at least one nested filter. It performs a union of results from sub-filters.
- Not: Returns resources that do not satisfy the nested conditions. It calculates the set difference between the initial resource list and the matches.
Sources: c7n/filters/core.py:270-369
Attribute Filtering (Value Filter)
The ValueFilter is the most common filter type. It uses JMESPath expressions to extract data from resource JSON structures and compares them using various operators.
Value Types and Operators
The filter supports specialized data conversion through the value_type property:
| Value Type | Description |
|---|---|
age | Computes time difference from current time. |
size | Evaluates the length of a list or string. |
cidr | Performs network address range checks. |
expiration | Filters based on future-dated timestamps. |
version | Compares software version strings. |
Available operators include standard comparisons (eq, gt, le), membership checks (in, ni, contains), and pattern matching (glob, regex).
Sources: c7n/filters/core.py:84-123, c7n/filters/core.py:591-623
Tag Normalization
Value filters provide a tag_key_transforms option to handle inconsistent tagging. This allows for standardizing keys (e.g., strip, lower, title) before comparison.
Sources: c7n/filters/core.py:465-475
Advanced List and Metric Filtering
ListItem Filter
The ListItemFilter evaluates multiple attributes within a list of objects inside a resource. For example, it can check security group rules for specific port and CIDR combinations simultaneously. It returns the parent resource if the criteria match a specified count of items in the list.
Sources: c7n/filters/core.py:849-923
Metrics Filter
Provider-specific MetricsFilter implementations (e.g., for AWS, GCP, or Tencent Cloud) query monitoring services. These filters retrieve time-series data, aggregate it via statistics (Average, Sum, Maximum, Minimum), and compare the result against a threshold.
Schema Generation and Validation
The c7n/schema.py module generates JSON schemas for all registered filters. This ensures that policy files are syntactically correct before execution. The validate() method in the Filter class checks required keys and operator compatibility.
Sources: c7n/schema.py:276-325, c7n/filters/core.py:545-580
Core Filters enable granular control over resource management by providing a flexible, extensible framework for data evaluation and logical grouping. These components form the foundation of Cloud Custodian's resource selection engine.