Docker Deployment and Cask
Relevant source files
The following files were used as context for generating this wiki page:
Cloud Custodian provides official Docker images to facilitate policy execution in containerized environments. These images package the Cloud Custodian rules engine along with its dependencies, allowing users to run policies without managing local Python environments.
The project utilizes automated packaging tools to generate specialized images for different components, including the core CLI, multi-account management (c7n-org), and notification delivery (c7n-mailer). To simplify the interaction with these containers, the Cask tool acts as a transparent front-end that automates common tasks such as volume mounting and environment variable passing.
Sources: README.md:1-25, tools/dev/dockerpkg.py:12-25
Docker Packaging Architecture
The project generates Dockerfiles using a Python-based utility, dockerpkg.py. This tool implements a multi-stage build process to ensure minimal image sizes and secure deployments.
Multi-Stage Build Process
The build process involves two primary stages:
- Bootstrap/Build Stage: Sets up the build environment using a base image (e.g., Ubuntu 24.04), installs system dependencies like
build-essentialanduv, and synchronizes package dependencies. - Target Stage: Copies the compiled virtual environment and source code into a clean target image, configures a non-privileged
custodianuser, and sets the entrypoint for the specific tool.
This diagram illustrates the multi-stage build flow defined in the packaging tool.
Sources: tools/dev/dockerpkg.py:64-135
Supported Image Types
The packaging tool defines metadata for several functional images:
| Image Reference | Target Title | Description | Entrypoint |
|---|---|---|---|
docker/c7n | cli | Core Cloud Management Rules Engine | custodian |
docker/c7n-kube | kube | Kubernetes Hooks and Providers | c7n-kates |
docker/c7n-org | org | Multi-account/Subscription Runner | c7n-org |
docker/mailer | mailer | Notification Delivery Service | c7n-mailer |
docker/policystream | policystream | Git-streamed policy change handler | c7n-policystream |
Sources: tools/dev/dockerpkg.py:210-255
Image Metadata and Compliance
All generated images include standardized labels based on Open Containers Initiative (OCI) specifications. These labels ensure traceability and documentation for production deployments.
Required metadata fields verified in functional tests include:
org.opencontainers.image.titleorg.opencontainers.image.descriptionorg.opencontainers.image.documentationorg.opencontainers.image.revisionorg.opencontainers.image.version
Sources: tests/test_docker.py:125-145, tools/dev/dockerpkg.py:120-130
Cask Tool
Cask is a Go binary designed to provide a transparent interface to the Custodian Docker containers. It mirrors the regular CLI syntax while handling the complexities of container orchestration internally.
Key Functionalities
- Volume Mounting: Automatically mounts the current working directory or specific output directories into the container.
- Authentication: Maps local cloud credentials (e.g.,
~/.aws/credentials) to the container environment. - Environment Passthrough: Forwards relevant environment variables for AWS, Azure, and Google Cloud to the containerized process.
Sources: README.md:162-166
Containerized Deployment Scenarios
Azure Container Host Workflow
For Azure environments, policies can be managed via CI/CD pipelines that deploy to a container host. The workflow typically involves synchronizing policy files from a repository to a storage blob container.
This sequence shows how policies are validated and deployed to containerized hosts in Azure.
Sources: tools/ops/azure/container-host/devops-flow/README.md:1-40
Execution Modes for Containers
For a policy to execute correctly within a container instance, the policy mode must be specifically configured. Supported modes include:
container-periodic: Executes policies on a scheduled interval within the container.container-event: Triggers policy execution based on cloud events.
Sources: tools/ops/azure/container-host/devops-flow/README.md:25-28
Manual Docker Execution
While Cask is recommended, users can run images manually using the Docker CLI. This requires explicit mounting and environment configuration.
# Example: Running a policy using manual mounts and AWS STS credentials
docker run -it \
-v $(pwd)/output:/home/custodian/output \
-v $(pwd)/policy.yml:/home/custodian/policy.yml \
-v $(cd ~ && pwd)/.aws/credentials:/home/custodian/.aws/credentials \
-v $(cd ~ && pwd)/.aws/config:/home/custodian/.aws/config \
--env-file <(env | grep "^AWS") \
cloudcustodian/c7n run -v -s /home/custodian/output /home/custodian/policy.yml
Sources: README.md:148-160
Summary
Docker deployment provides a consistent environment for Cloud Custodian across developer workstations and CI/CD pipelines. By leveraging dockerpkg.py for standardized builds and Cask for simplified execution, the project ensures that the rules engine can be deployed reliably across various cloud providers and infrastructure configurations.
Sources: README.md:20-30, tools/dev/dockerpkg.py:10-20