Developer Setup & Testing
Relevant source files
The following files were used as context for generating this wiki page:
Developer setup and testing provides the framework for contributing to Cloud Custodian across multiple cloud providers. It ensures code quality through standardized environment configuration, automated testing patterns, and infrastructure-as-code (IaC) validation.
The system relies on the uv workspace manager for dependency handling and pytest for execution. It utilizes a "Flight Data" recording pattern to simulate cloud provider responses, enabling tests to run without active cloud credentials.
Local Environment Configuration
Developers manage the project using uv from the repository root. This installs all workspace members in editable mode and sets up the necessary virtual environment.
Dependency Installation
The installation process synchronizes development, linting, and provider-specific extras. Use the following command to initialize the environment:
make install
This command executes uv sync with the dev, addons, and lint groups while enabling cloud-specific extras like gcp or azure.
Sources: tools/c7n_gcp/development.md:25-39, pyproject.toml:50-80
Environment Variables
Testing requires specific environment variables defined in a test.env file at the repository root. The project uses these variables for authentication and project identification during functional testing.
| Variable | Description |
|---|---|
GOOGLE_CLOUD_PROJECT | Target GCP Project ID |
GOOGLE_APPLICATION_CREDENTIALS | Path to service account credentials JSON |
AWS_PROFILE | Unset by default to prevent accidental production impact |
Sources: tools/c7n_gcp/development.md:47-55, pyproject.toml:135-139
Testing Architecture
Cloud Custodian employs a multi-tiered testing strategy involving unit tests, functional tests with recording, and IaC validation.
Flight Data Recording
The project uses a recording pattern to capture real API responses and replay them during subsequent test runs. This enables CI/CD pipelines to verify provider logic without live cloud access.
Flight data files are stored in tools/c7n_gcp/tests/data/flights/<test-case-name>/ as JSON objects containing HTTP headers and bodies.
Sources: tools/c7n_gcp/development.md:120-145
Infrastructure Provisioning with Terraform
For complex functional tests, developers use the @terraform decorator. This integrates Terraform to deploy real resources during the recording phase.
- Recording Mode: Deploys resources via
main.tf, generatestf_resources.json, and records API traffic. - Playback Mode: Skips deployment and uses the recorded JSON data to mock resource presence.
Sources: tools/c7n_gcp/development.md:167-185, tools/c7n_gcp/tests/terraform/vertexai_batch_prediction_job/vertex_batch.md:90-105
Shift Left & IaC Validation
The c7n-left tool enables testing policies against Infrastructure as Code assets like Terraform templates before deployment.
Output Reporters
The testing framework supports multiple output formats for integration with developer workflows and CI systems.
| Reporter | Purpose | Source File |
|---|---|---|
cli | Human-readable terminal output with code snippets | tools/c7n_left/c7n_left/output.py:463 |
github | Line annotations for GitHub Action workflows | tools/c7n_left/c7n_left/output.py:470 |
junit | XML reports for Jenkins or Azure DevOps | tools/c7n_left/c7n_left/output.py:596 |
gitlab_sast | JSON format for GitLab Security Dashboards | tools/c7n_left/c7n_left/output.py:608 |
Sources: tools/c7n_left/c7n_left/output.py:460-630
Execution Flow for IaC Testing
CI/CD Pipeline Integration
The repository includes pipeline definitions for Azure DevOps to automate policy validation and deployment.
Validation Pipeline
This pipeline executes custodian validate on changed files within a Pull Request. It prevents merging policies with syntax errors or schema violations.
- Retrieves a list of files modified between the source and target branches.
- Filters files based on the
POLICY_FILE_PATH. - Runs validation for each identified file.
Sources: tools/ops/azure/container-host/devops-flow/README.md:46-60
Container Host Deployment
Policies for container-based execution (modes container-periodic or container-event) are synchronized to cloud storage.
- SAS Token Generation: The pipeline generates a short-lived SAS token for secure storage access.
- Synchronization: The pipeline uses the Azure CLI to sync local policy directories with a blob storage container.
Sources: tools/ops/azure/container-host/devops-flow/README.md:65-85
Summary
Developer Setup & Testing centers on a uv-based workspace that standardizes multi-cloud development. By leveraging Flight Data Recording and Terraform integration, the project ensures that cloud policies are verifiable in isolated environments. The inclusion of c7n-left and dedicated CI/CD templates extends this verification to the earliest stages of the development lifecycle.
Sources: tools/c7n_gcp/development.md:1-20, README.md:150-180