Notifications with c7n-mailer
Relevant source files
The following files were used as context for generating this wiki page:
Cloud Custodian utilizes c7n-mailer as a reference implementation for delivering human-readable notifications to users. The system decouples the identification of non-compliant resources from the complex task of message delivery, such as template rendering and transport management.
The notification process starts when a Cloud Custodian policy executes the notify action. This action serializes resource data and pushes it to a message queue. A standalone c7n-mailer process then consumes messages from this queue, applies Jinja2 templates, and delivers the alerts via email, Slack, or other supported endpoints.
Sources: README.md:255-257, c7n/actions/notify.py:167-173
Architecture and Data Flow
The notification system uses an asynchronous architecture to handle high volumes of resource matches without impacting policy execution time.
System Overview Diagram
This diagram illustrates the flow from resource identification to final delivery.
Notification Sequence
The following sequence describes the interactions between the policy engine and the mailer utility.
The Notify Action
The notify action is the primary entry point for the notification system. It manages variable expansion, resource scrubbing, and payload buffering.
Resource Preparation and Scrubbing
Before sending data to the transport layer, the action removes sensitive or redundant metadata from specific resource types to minimize payload size and security risks.
| Resource Type | Action Taken |
|---|---|
| EC2 | Removes c7n:user-data |
| ASG | Removes c7n:user-data |
| ECS Service | Removes events |
| IAM SAML Provider | Removes SAMLMetadataDocument and IDPSSODescriptor |
| Launch Config | Removes UserData |
Sources: c7n/actions/notify.py:302-337
Message Buffering
The ResourceMessageBuffer class ensures that payloads do not exceed the transport limits (typically 256KB for SQS). It uses an adaptive compression ratio to estimate if additional resources will fit in the current message.
- Default Size: 262,144 bytes.
- Compression: Data is encoded using
zlibcompression andbase64encoding. - Payload Format: Messages are tagged with an
mtypeattribute set tomaidmsg/1.0.
Sources: c7n/actions/notify.py:17-45, c7n/actions/notify.py:246, tests/test_notify.py:21-26
Queue Processing
The c7n-mailer tool runs a processor to handle messages generated by the notify action.
SQS Queue Iterator
The MailerSqsQueueIterator manages message retrieval from AWS SQS. It uses long polling (default 10 seconds) and fetches messages in batches of 3 to improve efficiency.
Sources: tools/c7n_mailer/c7n_mailer/sqs_queue_processor.py:23-45
Parallel Processing
On systems supporting shared memory, the MailerSqsQueueProcessor utilizes the Python multiprocessing module to process messages in parallel. The default maximum number of processes is 16.
Sources: tools/c7n_mailer/c7n_mailer/sqs_queue_processor.py:84-88
Message Unpacking
The processor performs the reverse operation of the notify action to retrieve the original resource list and policy context.
# Unpacking logic in sqs_queue_processor.py
def process_sqs_message(self, encoded_sqs_message):
body = encoded_sqs_message["Body"]
try:
body = json.dumps(json.loads(body)["Message"])
except ValueError:
pass
sqs_message = json.loads(zlib.decompress(base64.b64decode(body)))
Sources: tools/c7n_mailer/c7n_mailer/sqs_queue_processor.py:113-120
Delivery and Dependencies
The mailer supports multiple delivery targets and relies on several external libraries for formatting and transport.
Core Dependencies
| Library | Purpose |
|---|---|
| Jinja2 | Template engine for rendering HTML and text alerts. |
| boto3 | AWS SDK for SQS, SNS, and SES interactions. |
| sendgrid | Optional provider for email delivery. |
| ldap3 | Used for looking up user emails via LDAP UIDs. |
| redis | Used for caching and deduplication in some configurations. |
Sources: tools/c7n_mailer/pyproject.toml:9-22
Delivery Logic
The MessageTargetMixin handles the final dispatch to targets. Supported use cases include:
- Lookup of
CreatorNameor other resource tags via LDAP. - Direct delivery to emails specified in the policy
tofield. - Integration with SNS topics for downstream automation.
- Lambda-based event lookup to identify and notify the specific AWS user who triggered a policy.
Sources: tools/c7n_mailer/c7n_mailer/sqs_queue_processor.py:61-73
Summary
c7n-mailer provides a robust, scalable framework for notifying stakeholders of policy compliance issues. By separating the policy engine from the notification delivery logic, the system maintains high performance while offering flexible alerting options across multi-cloud environments. The tool integrates natively with cloud-native message queues and supports enterprise-standard delivery methods including SMTP, Slack, and SNS.
Sources: README.md:255-257, GOVERNANCE.md:14