Leverage Reference Architecture: OpenTofu/Terraform AWS Infrastructure

Overview

This repository contains all OpenTofu/Terraform configuration files used to create the Binbash Leverage Reference AWS Cloud Solutions Architecture.

Documentation

• Binbash Leverage Reference Architecture Official Documentation
• Leverage CLI (PyPI)
• Binbash Module Library

---

Getting Started

Prerequisites

• Leverage CLI (v2.2.0+)
• OpenTofu (>= 1.6)
• AWS SSO access configured for the target accounts
• uv (recommended for Python/Leverage CLI management)

Installation

Option A: Install via pip (stable)

pip install leverage

Option B: Install via uv (recommended for local development)

uv provides fast, reproducible Python environments without conflicting with system packages.

# Create a Python 3.12 virtual environment
uv venv --python 3.12 .venv

# Install the latest Leverage CLI release (or a specific version/pre-release)
uv pip install leverage
# For pre-release/release candidates:
# uv pip install --pre leverage==2.2.0rc5

# Activate the environment
source .venv/bin/activate

# Verify
leverage --version

Note: Leverage CLI v2.2.0+ runs OpenTofu natively (no Docker required). You need the tofu binary installed locally (e.g., brew install opentofu on macOS).

Setup and Workflow

1. Authenticate with AWS SSO:

   leverage aws sso login

2. Navigate to the layer you want to work with:

   cd {account}/{region}/{layer}  # e.g., security/global/base-identities

3. Follow the standard workflow:

   leverage tofu init
   leverage tofu plan
   leverage tofu apply

4. Repeat for any desired Reference Architecture layer.

How it works

The backend.tfvars injects the AWS profile name with the necessary permissions that OpenTofu uses to make changes on AWS. This profile relies on AWS SSO to assume a cross-account role for each corresponding account (AWS IAM: users, groups, roles & policies).

Configuration files are automatically loaded by the Leverage CLI:

• config/common.tfvars - Project-wide variables (project name, account IDs, SSO config)
• {account}/config/account.tfvars - Account-specific variables (environment, SSO role)
• {account}/config/backend.tfvars - Backend configuration (S3 bucket, profile, DynamoDB table)

For more details, see the configuration files documentation and the standard workflow.

AI Development Configs

This repository includes pre-configured settings for AI-powered development to enhance productivity and maintain consistency across the codebase. Claude Code is the team's standard AI development tool — it is the only AI tooling configuration maintained here.

Claude Code

• Claude Code - Anthropic's AI coding assistant
  • CLAUDE.md - Project instructions and context for Claude
  • .claude/agents/ - Specialized agent definitions (architect, security, terraform-layer, etc.)
  • .mcp.json - Root-level MCP server configurations (AWS API, AWS Documentation)

Usage

These configurations are discovered when you open the project in Claude Code. CLAUDE.md and .claude/agents/ load automatically, but the project-scoped MCP servers in .mcp.json require explicit approval before first use — until approved they show as pending in claude mcp list. The aws-api server additionally needs valid credentials for the bb-shared-devops profile (leverage aws sso login), and is restricted to read-only AWS operations via READ_OPERATIONS_ONLY.

They provide:

• Context-aware code suggestions aligned with Leverage best practices
• AWS- and OpenTofu/Terraform-specific assistance
• Consistent code formatting and structure guidelines
• Direct access to AWS documentation and the AWS API

Learn More

• Claude Code Documentation
• MCP Protocol Specification

AI-Driven SDLC

Every PR is reviewed by CodeRabbit AI and Gemini Code Assist (both auto-trigger on open / sync), gated by CI checks (Test and Lint, Infracost, GitGuardian), and can be inspected on demand by @claude — which routes through Amazon Bedrock (Anthropic Claude Sonnet 4.6) rather than the public Anthropic API, so prompts and code stay inside our apps-prd AWS account.

See docs/ai-sdlc/ for the full workflow, configuration knobs, and architecture diagrams.

Claude Code on AWS Bedrock (local sessions)

Local Claude Code sessions can also route through Amazon Bedrock in the data-science account on demand — via a claude-bedrock launcher that flips a single session to Bedrock while plain claude keeps using the native Anthropic API. Setup, model entitlements/quotas, and troubleshooting: docs/ai-sdlc/claude-code-bedrock.md.

Leverage CLI Reference

Project-wide commands

leverage --help               # Show all commands
leverage --version            # Show version
leverage aws sso login        # Authenticate with AWS SSO
leverage run <task>           # Run a build.py task (e.g., layer_dependency, decrypt, encrypt)

Layer commands (run from a layer directory)

leverage tofu init              # Initialize the layer
leverage tofu plan              # Preview changes
leverage tofu apply             # Apply changes
leverage tofu destroy           # Destroy infrastructure
leverage tofu format            # Format code (always recursive)
leverage tofu format -check     # Check formatting without rewriting
leverage tofu validate          # Validate configuration

leverage tf is a shorthand alias for leverage tofu. Both run OpenTofu.

The wrapper exposes only a curated subset of subcommands: apply, destroy, force-unlock, format, import, init, output, plan, refresh-credentials, validate, validate-layout, version. Note it is format, not fmt — and format is already recursive, being equivalent to tofu fmt -recursive. See the leverage tofu reference. That page does not currently cover force-unlock or refresh-credentials; the list above comes from leverage tofu --help on the pinned CLI, which is the authority.

For anything else — state, show, console, providers, workspace, graph, get, test — run the native tofu binary from the layer directory, loading the AWS profile from the layer's config/backend.tfvars:

tofu state list                 # List resources in state
tofu state show <res>           # Show a specific resource in state

Release Management

Reference Architecture | Releases