CloudBender

About

CloudBender is an Infrastructure-as-Code orchestration tool for deploying and maintaining AWS infrastructure in an automated, traceable, and version-controlled manner.

It provides a unified CLI with first-class support for two IaC backends:

• Pulumi — Python-based IaC with S3-backed state (no Pulumi Cloud dependency)
• AWS CloudFormation — with Jinja2 template rendering

Key Features

• Dual IaC backend — mix Pulumi and CloudFormation stacks in the same project
• Hierarchical configuration — deep-merging config inheritance ideal for multi-account, multi-region AWS environments
• Self-hosted state — Pulumi state stored in S3 per-account/per-region; no data sent to external APIs
• Secrets management — Pulumi native encryption and SOPS for CloudFormation
• Dependency resolution — automatic stack ordering based on declared dependencies
• Lifecycle hooks — pre/post create and update hooks for custom automation
• Drift detection — refresh command for Pulumi stacks
• Auto-generated docs — markdown documentation from stack metadata and outputs

Requirements

• Python >= 3.12
• Pulumi >= 3.x
• podman or docker (for container-based tasks)
• AWS credentials configured via profiles (~/.aws/config)

Installation

Containerized (recommended)

The preferred way to run CloudBender is via the public container image. This ensures all tools and dependencies are in sync and tested.

Note: Requires Linux with kernel >= 5.12, Cgroups V2, and podman for rootless nested containers.

Verify your setup supports nested containers:

podman run --rm -v .:/workspace -v $HOME/.aws/config:/workspace/.aws/config \
  public.ecr.aws/zero-downtime/cloudbender:latest \
  podman run -q --rm docker.io/busybox:latest echo "Rootless container inception works!"

If successful, add an alias to your shell profile:

alias cloudbender="podman run --rm -v .:/workspace \
  -v $HOME/.aws/config:/home/cloudbender/.aws/config \
  public.ecr.aws/zero-downtime/cloudbender:latest cloudbender"

Local install

pip3 install -U cloudbender
curl -fsSL https://get.pulumi.com | sh

Verify installation

cloudbender version

Expected output:

CloudBender: 0.x.x
Pulumi: v3.228.0
Podman/Docker: podman version 5.x.x

Project Layout

A CloudBender project follows this directory structure:

my-project/
├── config/                        # Configuration tree
│   ├── config.yaml                # Global settings (profile, region, options)
│   ├── production/                # Stack group
│   │   ├── config.yaml            # Group-level overrides (deep-merged with parent)
│   │   ├── us-east-1/             # Nested stack group (e.g. per-region)
│   │   │   ├── config.yaml        # Region-level overrides
│   │   │   └── vpc.yaml           # Stack definition
│   │   └── networking.yaml        # Stack definition
│   └── staging/
│       ├── config.yaml
│       └── app.yaml
├── cloudformation/                # CloudFormation Jinja2 templates
│   └── vpc.yaml.jinja
└── artifacts/                     # Artifacts (Pulumi programs, scripts, etc.)
    └── pulumi/
        └── vpc.py                 # Pulumi Python program

Configuration Hierarchy

Configuration is hierarchically merged from parent to child. Lower-level config files override higher-level values, with deep merging for dictionaries and arrays. This enables DRY configuration across accounts, regions, and environments.

Stack Modes

Each stack operates in one of three modes:

Pulumi Libraries

Stack implementations — both Pulumi programs and CloudFormation Jinja templates — are distributed as versioned library archives rather than kept in the local project tree. Declare them per stack (or inherit from the stack group) via the top-level libraries key:

libraries:
  - url: "s3://my-bucket/libs/vpc-lib"
    version: "1.2.3"
  - url: "s3://my-bucket/libs/network-lib"      # version defaults to "latest"
  - url: "local://./libs/dev-lib"               # used in place, never fetched
  - url: "s3://my-bucket/libs/extras"
    optional: true                              # skipped if it cannot be fetched

Each entry supports:

For remote protocols the archive <url>-<version>.tar.gz is fetched and unpacked into a temporary workspace. local:// points directly at an existing directory (relative paths resolve against the CloudBender project root, i.e. --dir) and is neither fetched nor copied — useful for local development.

A library root may contain any of these top-level folders, and the stack's template is resolved from the first library that provides it:

• pulumi/ — Pulumi Python programs. The stack's template (e.g. vpc.py) is imported from here. pulumi/ and artifacts/ folders are added to the Pulumi program's search path so it can import modules and locate bundled files/scripts.
• cloudformation/ — CloudFormation Jinja templates. The stack's template (e.g. vpc.yaml.jinja) is rendered from here; cloudformation/ and artifacts/ folders form the Jinja loader path, so {% include %} and include_raw of scripts resolve against both.
• artifacts/ — bundled files and scripts shared by the above.
• policies/ — Pulumi policy packs referenced via pulumi.policies.

Both backends source their templates exclusively from libraries; a stack must declare at least one library providing its template. A local://. library exposing pulumi/ / cloudformation/ folders is the simplest way to keep templates alongside the project during development.

CLI Reference

Usage: cloudbender [OPTIONS] COMMAND [ARGS]...

Options:
  --profile TEXT  Use named AWS .config profile, overwrites any stack config
  --region TEXT   Use region, overwrites any stack config
  --dir TEXT      Specify cloudbender project directory.
  --debug         Turn on debug logging.
  --help          Show this message and exit.

Core Operations

CloudFormation Commands

Configuration & Secrets

Inspection & Documentation

Pulumi State Management

Utility

Architecture

State Management

Pulumi — State is stored in S3 within your own AWS account, in the same region as the deployed resources. No data is shared with Pulumi Cloud APIs. CloudBender creates temporary, isolated workspaces per stack operation and injects configuration (account ID, region, parameters) automatically.

CloudFormation — State is managed natively by the AWS CloudFormation service. Templates can optionally be stored in S3 via the template_bucket_url setting.

Secrets

Pulumi — Uses native Pulumi secret handling with passphrase-based or custom encryption keys. See Pulumi Secrets docs.

CloudFormation — Supports SOPS for encrypted config files. Encrypted files are automatically detected and decrypted at runtime. All required decryption metadata must be embedded in the SOPS config or set via environment variables. SOPS support can be disabled by setting the DISABLE_SOPS environment variable.

Hooks

Stacks support lifecycle hooks defined in artifact metadata:

• pre_create, post_create — before/after stack creation
• pre_update, post_update — before/after stack update

Built-in hook type:

• cmd — execute arbitrary shell commands via subprocess

Dependency Resolution

Stacks can declare dependencies on other stacks. CloudBender resolves these into a dependency graph and provisions stacks in the correct order, parallelizing independent stacks where possible (CloudFormation stacks run in parallel; Pulumi stacks run sequentially due to thread-safety constraints).

Environment Variables

Development

# Install dependencies
just prepare

# Format code
just fmt

# Lint
just lint

# Run tests
just test

# Build distribution
just build

License

AGPL-3.0-or-later

Links

• Homepage: https://git.zero-downtime.net/ZeroDownTime/CloudBender
• Container image: public.ecr.aws/zero-downtime/cloudbender:latest
• PyPI: pip install cloudbender