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:

Mode	Description
`CloudBender` (default)	CloudFormation with Jinja2 rendering
`pulumi`	Pulumi Python IaC
`Piped`	CloudFormation with inter-stack reference injection

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

Command	Description
`provision <stack\|group> [--multi]`	Create or update stacks/stack groups
`delete <stack\|group> [--multi]`	Delete stacks/stack groups (reverse dependency order)
`preview <stack>`	Preview Pulumi stack changes before applying
`refresh <stack>`	Drift detection — refreshes Pulumi stack state against actual cloud resources

CloudFormation Commands

Command	Description
`render <stack> [--multi]`	Render Jinja2 templates to CloudFormation YAML
`validate <stack> [--multi]`	Validate rendered templates using `cfn-lint`
`create-change-set <stack> <name>`	Create a CloudFormation change set
`sync <stack> [--multi]`	Render + provision in a single step

Configuration & Secrets

Command	Description
`get-config <stack> <key>`	Retrieve a config value (decrypted if secret)
`set-config <stack> <key> <value> [--secret]`	Store a config value (encrypted if `--secret`)

Inspection & Documentation

Command	Description
`outputs <stack> [--include regex] [--values]`	Print stack outputs, optionally filtered
`docs <stack> [--multi]`	Generate documentation for stacks
`list-stacks <group>`	List all Pulumi stacks in a group
`version`	Display CloudBender, Pulumi, and Podman/Docker versions

Pulumi State Management

Command	Description
`export <stack> [-r]`	Export Pulumi stack state (optionally remove pending operations)
`import <stack> <file>`	Import a Pulumi state file
`assimilate <stack>`	Import existing AWS resources into a Pulumi stack
`execute <stack> [function] [args]`	Run custom Python functions within a stack context

Utility

Command	Description
`wrap <group> <cmd>`	Execute an external program with stack group context
`clean`	Delete all previously rendered template files

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

Variable	Description
`CLOUDBENDER_PROJECT_ROOT`	Override the project root directory
`DISABLE_SOPS`	Disable SOPS decryption for config files
`PULUMI_SKIP_UPDATE_CHECK`	Set automatically in the container image

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cloudbender-0.25.1.tar.gz (134.7 kB view details)

Uploaded Jul 17, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

cloudbender-0.25.1-py3-none-any.whl (47.4 kB view details)

Uploaded Jul 17, 2026 Python 3

File details

Details for the file cloudbender-0.25.1.tar.gz.

File metadata

Download URL: cloudbender-0.25.1.tar.gz
Upload date: Jul 17, 2026
Size: 134.7 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Gentoo","version":"2.18","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for cloudbender-0.25.1.tar.gz
Algorithm	Hash digest
SHA256	`358501954f6d25a9452a41c1f53d6beeb6925cfa7afabf4f9a6cf78d8efd3dc9`
MD5	`72dfaaec95961609b2c89e260266e3c4`
BLAKE2b-256	`16de63a4457071e4106581819265750e13ed20b70d7a199cfd9bc2f5106b273c`

See more details on using hashes here.

File details

Details for the file cloudbender-0.25.1-py3-none-any.whl.

File metadata

Download URL: cloudbender-0.25.1-py3-none-any.whl
Upload date: Jul 17, 2026
Size: 47.4 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.11.21 {"installer":{"name":"uv","version":"0.11.21","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Gentoo","version":"2.18","id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

File hashes

Hashes for cloudbender-0.25.1-py3-none-any.whl
Algorithm	Hash digest
SHA256	`fbdfb66abfe270780f72d38d017d0f60f48af442942a0ca3f304e45613baa69b`
MD5	`547fd2036c7024f4f50f353c46c6c427`
BLAKE2b-256	`6829fb69cc53da36b1daed0b6ee8a743a3e0bad63ffbb8c1c56de87b7abf654c`