Announcing Terrateam Stacks - Layered and nested infrastructure orchestration

Managing infrastructure across multiple environments with hundreds of Terraform modules creates orchestration challenges. When you modify a database in development, you need precise control over how changes cascade to production. When networking changes affect dependent services, you need explicit ordering that respects real-world sequences.

Teams solve this with custom CI scripts or manual coordination. These approaches create fragility: dependencies become implicit, promotion workflows break when new modules are added, and drift occurs when changes bypass intended sequences.

Terraform Stacks provide a better solution. By defining explicit relationships between infrastructure groups, stacks eliminate the ambiguity causing deployment failures. This post explains what Terraform Stacks are, why they matter, and how to use Terrateam Stacks to orchestrate infrastructure safely and efficiently.

What are Terraform Stacks?

Terraform Stacks group related infrastructure components and define orchestration rules between those groups. A stack represents a collection of Terraform workspaces or directories (matched using a tag_query to match workspaces by directory or label) treated as a unit during deployment.

Traditional Terraform workflows operate on individual directories. You run terraform plan in networking, then database, then application directories separately. Coordinating these operations falls to CI/CD pipelines or manual processes.

Stacks elevate orchestration to configuration. Instead of scripting sequences, you define them as stack relationships. When networking changes, dependent stacks trigger automatically. When development completes, staging becomes eligible to deploy. These relationships live in version-controlled configuration.

The concept addresses a fundamental Terraform limitation: no native cross-workspace dependency management. Terraform manages resources within a single state file excellently but provides no mechanism to coordinate across multiple state files.

Consider infrastructure across three environments: development, staging, and production. Each environment contains networking, database, and application layers. Without stacks, coordinating changes requires manual sequencing:

# Traditional approach - manual or scripted
cd environments/dev
terraform apply
cd ../staging
terraform apply  # Hope dev succeeded
cd ../production
terraform apply  # Hope staging succeeded

Stacks replace this with declarative configuration:

stacks:
  names:
    dev:
      tag_query: 'dir:environments/dev/*'
      rules:
        auto_apply: true

    staging:
      tag_query: 'dir:environments/staging/*'
      rules:
        apply_after:
          - dev

    production:
      tag_query: 'dir:environments/production/*'
      rules:
        apply_after:
          - staging

This configuration creates a promotion pipeline where production can't deploy until staging succeeds, and staging waits for development. The orchestration logic becomes infrastructure code you can review and version.

What are the benefits of Terraform Stacks?

Terraform doesn't natively solve cross-workspace dependency orchestration. Teams work around this with custom scripts or manual coordination. These approaches break down as infrastructure scales.

Manual coordination becomes a bottleneck when teams grow beyond five engineers. A bash script that sequences three environments seems simple initially. Six months later, after adding regional deployments and rollback logic, nobody wants to modify the script. Engineers copy and adapt rather than maintain shared logic, creating divergent behaviors.

These workarounds create specific problems:

• Unclear dependencies — Partial deployments occur when engineers apply changes without understanding dependent component impact
• Broken promotions — Environment differences cause staging failures for code that worked in development
• Configuration drift — Urgent production fixes bypass proper sequences, creating divergence
• Security vulnerabilities — Permission changes skip review when proper gates don't exist

Stacks address these through explicit configuration. The benefits:

• Speed — Parallel execution within dependency constraints cuts deployment time by 50-80%
• Safety — Smaller blast radius through explicit boundaries that contain failures
• Control — Dependency enforcement across workspaces and teams via configuration
• Visibility — Stack modifications show exactly what deploys and in what sequence

Terrateam Stacks turn orchestration from tribal knowledge into declarative infrastructure logic.

What makes Terrateam Stacks different?

When stacks were initially designed, we explicitly excluded nesting and layering. The reasoning seemed sound: users could achieve sequential operations through tag queries, and nested stacks appeared to add complexity without clear use cases.

Real-world usage proved these assumptions wrong. In real-world usage of stacks, nested stacks are both desirable and necessary for useful workflows. After trying to use stacks in real-world situations, being able to nest stacks and layer them turns out to be useful functionality.

Let's look at how Terrateam takes this idea further.

Terrateam Stacks introduce two core capabilities:

Layered stacks enforce sequential execution. A layered stack runs only after its prerequisite stack finishes applying. This creates dependency trees matching real infrastructure requirements — networking completes before databases begin.

Nested stacks create hierarchical groupings. Instead of using tag_query, nested stacks contain lists of other stacks. This enables grouping by logical boundaries — all production infrastructure, all resources for an application, all components in a region.

The implementation overhauls how stack relationships are defined through new rules configuration:

• plan_after — Stacks that must apply before this stack can plan
• apply_after — Stacks that must apply before this stack can apply
• modified_by — Stacks which, when modified, force this stack to become modified
• auto_apply — Boolean defining whether the stack applies automatically after passing requirements

Variable handling also changed for clarity. Previously, stack variables used STACK_VAR_$name. Now variables are accessed directly by name (e.g., ${environment}), simplifying configuration but requiring careful naming to avoid collisions.

Compared to alternatives, Terrateam Stacks integrate deeply with GitOps workflows. Configuration lives in your repository. Stack orchestration uses the same pull request workflow as regular Terraform changes. The terraform stacks open source implementation means you can audit orchestration logic and deploy to self-hosted infrastructure.

Why use Terrateam Stacks?

Infrastructure orchestration requirements grow with organizational complexity. Terrateam Stacks address this by moving orchestration logic into declarative configuration. When you add infrastructure, you define its place in the dependency graph rather than modifying scripts.

The approach shines in specific scenarios:

Multi-environment deployment — Changes flow through dev → staging → prod with different approval requirements at each stage

Layered infrastructure dependencies — Networking completes before databases deploy, databases before applications deploy

Cross-team coordination — Platform teams manage shared infrastructure that application teams depend on without manual coordination

Multi-region deployments — Deploy to one region, verify, then proceed to additional regions with proper sequencing

Compliance requirements — Encode specific approval flows or deployment sequences in configuration rather than documentation

How to deploy, implement and configure Terraform stacks with Terrateam

Implementing Terraform Stacks with Terrateam starts with configuration in .terrateam/config.yml. This section walks through progressively complex scenarios.

Layered environment promotion

The simplest useful pattern: separate environments where changes must flow sequentially. This ensures you test in development before affecting production:

stacks:
  names:
    dev:
      tag_query: 'dir:environments/dev/*'
      variables:
        environment: development
        terraform_version: "1.6.0"
      rules:
        auto_apply: true

    staging:
      tag_query: 'dir:environments/staging/*'
      variables:
        environment: staging
        terraform_version: "1.6.0"
      rules:
        apply_after:
          - dev

    production:
      tag_query: 'dir:environments/production/*'
      variables:
        environment: production
        terraform_version: "1.6.0"
      rules:
        apply_after:
          - staging

The tag_query selects which Terraform directories belong to each stack. Stack variables define values accessible throughout the stack's workspaces. The auto_apply rule on development enables rapid iteration — successful plans apply automatically.

The apply_after rules create the promotion pipeline. Staging cannot apply until development applies successfully. Production waits for staging.

When you open a pull request modifying multiple environments, Terrateam plans all affected stacks simultaneously. Commenting terrateam apply triggers the cascade: development applies first, then staging, then production.

Real infrastructure has dependencies within environments. Networking must exist before databases. Express these through layered stacks with plan_after rules that prevent dependent stacks from planning until prerequisites apply.

Combining layered and nested stacks

The most sophisticated pattern combines nesting and layering to match complex organizational infrastructure:

stacks:
  names:
    # Development layers
    dev-network:
      tag_query: 'dir:dev/network'
      rules:
        auto_apply: true

    dev-data:
      tag_query: 'dir:dev/database'
      rules:
        plan_after:
          - dev-network
        auto_apply: true

    dev-app:
      tag_query: 'dir:dev/application'
      rules:
        plan_after:
          - dev-data
        auto_apply: true

    # Group development layers
    development:
      stacks:
        - dev-network
        - dev-data
        - dev-app

    # Staging layers
    staging-network:
      tag_query: 'dir:staging/network'
      rules:
        plan_after:
          - development

    staging-data:
      tag_query: 'dir:staging/database'
      rules:
        plan_after:
          - staging-network

    staging-app:
      tag_query: 'dir:staging/application'
      rules:
        plan_after:
          - staging-data

    # Group staging layers
    staging:
      stacks:
        - staging-network
        - staging-data
        - staging-app
      rules:
        apply_after:
          - development

    # Production regions with layers
    prod-us-east-network:
      tag_query: 'dir:prod/us-east-1/network'
      rules:
        plan_after:
          - staging

    prod-us-east-data:
      tag_query: 'dir:prod/us-east-1/database'
      rules:
        plan_after:
          - prod-us-east-network

    prod-us-east-app:
      tag_query: 'dir:prod/us-east-1/application'
      rules:
        plan_after:
          - prod-us-east-data

    prod-us-east:
      stacks:
        - prod-us-east-network
        - prod-us-east-data
        - prod-us-east-app

    prod-us-west-network:
      tag_query: 'dir:prod/us-west-2/network'
      rules:
        plan_after:
          - prod-us-east

    prod-us-west-data:
      tag_query: 'dir:prod/us-west-2/database'
      rules:
        plan_after:
          - prod-us-west-network

    prod-us-west-app:
      tag_query: 'dir:prod/us-west-2/application'
      rules:
        plan_after:
          - prod-us-west-data

    prod-us-west:
      stacks:
        - prod-us-west-network
        - prod-us-west-data
        - prod-us-west-app

    production:
      stacks:
        - prod-us-east
        - prod-us-west
      rules:
        apply_after:
          - staging

This creates layered infrastructure within each environment, environment-level grouping for clear boundaries, sequential promotion from dev to staging to production, multi-region production deployment with dependencies, and infrastructure layering within each region.

Changes to development networking flow through development layers, then trigger staging networking after development completes. After staging finishes, production US East begins, followed by US West.

Terrateam Stacks are available in all plans, including open source and self-hosted deployments.

Stack variables flow through to workflow execution, enabling environment-specific behavior without duplicating definitions. Production uses stable Terraform versions with conservative parallelism. Development uses latest versions with aggressive parallelism. A single workflow definition adapts based on which stack executes.

For more guidance on best practices for CI/CD pipelines, organizing Terraform code, and using the Terraform Null Resource effectively, explore our other guides.

Conclusion

Terraform Stacks transform infrastructure orchestration from custom scripts into declarative configuration. Terrateam Stacks provide the implementation with layered stacks for sequential dependencies, nested stacks for hierarchical grouping, and rules configuration for precise control.

Start with basic environment separation. Add infrastructure layers when dependencies cause coordination overhead. Introduce nesting when logical groupings emerge. The approach scales from simple three-environment setups to complex multi-region deployments across dozens of teams.

Start using Terrateam Stacks today — sign up for free or book a demo to see it in action.