Controlling Terraform Execution Order with Terramate Stack Dependencies

Stop Manually Ordering Terraform Runs Across Stacks

When infrastructure is split into multiple Terramate stacks, running terraform apply in the wrong order can fail: an application stack may try to attach to a VPC subnet that does not exist yet. The useful takeaway is to declare stack dependencies in .terramate files and let terramate run sequence the commands automatically.

How Terramate Orders Stack Execution

Terramate reads .terramate files to discover stacks. A stack can list other stacks in a depends_on attribute. When you run terramate run, Terramate builds a dependency graph and executes the command in each stack directory in an order that respects those edges. It does not replace Terraform or manage state; it only orchestrates where and in what order the command runs.

Worked Example: Network Stack Before Application Stacks

This example assumes a project root containing Terramate stack definitions and the Terramate CLI installed in your shell.

# network/stack.terramate
stack "network" {
  description = "Shared VPC and subnets"
}

# apps/frontend/stack.terramate
stack "frontend" {
  description = "Frontend service"
  depends_on = ["network"]
}

# apps/backend/stack.terramate
stack "backend" {
  description = "Backend API service"
  depends_on = ["network"]
}

Run the orchestration from the project root:

# Requires read/write access to the stack directories and valid cloud credentials
# for any provider configured inside the stacks.
terramate run echo hello

Expected check: The CLI output should list the network stack before frontend and backend. If you replace echo hello with terraform apply -auto-approve, Terramate will apply network resources first, then the application stacks.

Risk: terramate run terraform apply changes state in every stack. A failure in a downstream stack leaves upstream resources already created, so review the plan output before using -auto-approve.

Limits and Common Mistakes

• Circular dependencies: If frontend depends on backend and backend depends on frontend, terramate run fails with a circular reference. Keep the graph acyclic.
• Not a state manager: Terramate does not store terraform.tfstate. Each stack still needs its own backend configuration, typically in a backend.tm template or static .tf file.
• Ordering applies to terramate run only: Running terraform apply directly inside a stack directory ignores depends_on.
• Do not edit generated files: If Terramate generates .tf files from templates, edit the .terramate or template files, then regenerate. Manual edits to generated files are overwritten.

Verification

From the project root, run a read-only command to confirm the sequence:

terramate run echo hello

Inspect the output order. If network appears first, the dependency graph is correct.

Rollback: This example uses echo, so it does not change infrastructure state. If you run terraform apply instead, roll back by reversing the Terraform changes with the previous configuration or state; Terramate file changes alone do not roll back remote resources.