Running Terraform Operations Across Terramate Stacks in a Monorepo

The problem of coordinating Terraform at scale

When a Terraform monorepo grows to dozens of environments, running terraform plan or apply across them becomes a coordination bottleneck. Engineers often resort to shell loops, manual directory jumps, or fragile scripts that don't account for version mismatches or remote state drift.

Useful takeaway

With terramate run, you can apply the same Terraform CLI command across every stack matching a filter in one invocation, while the tool aligns the required Terraform binary version and handles per-stack remote state—reducing manual errors and freeing your CI pipeline.

Prerequisites

• Terramate CLI installed (version 0.15 or newer). Terramate adds stack-aware orchestration on top of Terraform.
• Terraform binary accessible on the execution agent, or aligned via per-stack version tags (Terramate ensures the correct version is used for each stack).
• Remote backend configured for each stack (e.g., S3, GCS, Azure Blob). Terramate does not provision backends automatically.
• Stack definitions organized in the monorepo with names or patterns you can target via glob.

Focused procedure

1. Discover your stacks. Run

   terramate list stacks

   and confirm the output matches your directory structure and naming conventions.
2. Dry‑run on a single stack first. Execute

   terramate run plan --dry-run --stack prod-us-east-1

   to verify command propagation and output before scaling up.
3. Run plan across matching stacks. Use a glob filter to target multiple environments at once:

   terramate run plan --stack 'prod-*'

   The command runs plan in parallel across all stacks whose names match the pattern.
4. Verify Terraform version alignment. Within the run logs, look for a line such as Terraform version 1.9.0 to confirm Terramate is using the version defined for each stack.
5. Proceed to apply if the plan is correct.

   terramate run apply --stack 'prod-*'

   This changes Terraform state, so recovery steps apply (see next section).

Expected checks

• After terramate run plan, confirm the logs contain the expected Terraform version line and that plan output reflects the intended stacks.
• Use

  terramate state list

  after the operation to inspect remote state per stack and ensure no unexpected resources were created.
• Re‑run

  terramate list stacks

  to verify that only the expected stacks were processed.

Recovery and rollback considerations

Because terramate run apply modifies Terraform state, a built‑in “rollback” flag does not exist. If an apply introduces unintended resources, you have two practical paths:

• Run terramate run destroy --stack 'prod-*' to teardown the applied resources across the same stacks.
• Use native Terraform recovery commands such as terraform state rm or terraform import for targeted remediation.

Always verify the state before and after any recovery operation with terramate state list.

Terramate run vs manual scripting

Aspect	Manual script	Terramate run
Version alignment	Manual PATH checks	Built-in per-stack version tags
State handling	Custom remote state logic	Per-stack remote backend awareness
Filter safety	Risk of off-target globs	Testable with --dry-run and list stacks

Limitations and practical verification

• Filter scope. Stack glob patterns (e.g., 'prod-*') must be tested with --dry-run first; a misplaced wildcard can target unintended directories or environments.
• Terraform version availability. Version alignment only works if the specified binary is installed and on the PATH of the agent where terramate run executes.
• Remote backend readiness. Each stack must have a configured remote backend; Terramate does not auto-provision backends.

Practical verification: after any terramate run command, run terramate list stacks and inspect the per-stack state with terramate state list to confirm the expected number of stacks were processed and no errors surfaced.