Stacks

The Problem

You have the same Terraform code across dev, staging, and production. Each environment needs different .tfvars values, but you want consistent configuration and a promotion path from dev → staging → prod.

Without stacks, you’d create three workspaces manually:

• Set up each one with the same repo, branch, and credentials
• Configure each with its own .tfvars file
• Manually remember to promote changes through environments
• Hope the state keys don’t collide

The Stack Solution

A stack is a multi-environment workspace template. One API call creates:

• A stack record
• One workspace per environment (named {stack}-{env})
• A promotion graph connecting them

Before vs After

Manual approach:

Create workspace "myapp-dev"     → configure repo, branch, credentials, state
Create workspace "myapp-staging" → configure repo, branch, credentials, state
Create workspace "myapp-prod"    → configure repo, branch, credentials, state
Manually add dependency edges for promotion

Stack approach:

POST /stacks {
  "name": "myapp",
  "environments": [
    { "name": "dev",     "var_files": ["env/dev.tfvars"],     "promote_to": ["staging"] },
    { "name": "staging", "var_files": ["env/staging.tfvars"], "promote_to": ["prod"] },
    { "name": "prod",    "var_files": ["env/prod.tfvars"] }
  ]
}
→ Creates 3 workspaces + promotion graph in one atomic operation

Naming Conventions

• Workspace names: {stack}-{env} (e.g., myapp-dev, myapp-staging, myapp-prod)
• State keys: {stack}/{env} (e.g., myapp/dev, myapp/staging, myapp/prod)

When to Use Stacks

Use stacks when:

• You have the same code across multiple environments
• Each environment has different .tfvars values
• You want a promotion path between environments

Use individual workspaces when:

• Environments have different code (different repos or branches)
• You don’t need promotion between environments
• Environments have completely different credential or state requirements

Next Steps

• Creating Stacks — Full API reference with examples
• Environments and Varfiles — Per-environment configuration
• Promotion Graph — How promotion between environments works