Reducing Terraform Boilerplate with Terramate Stack Abstractions

The Problem: The 'Copy-Paste' Infrastructure Trap

When scaling infrastructure across multiple AWS accounts or regions, most teams fall into a predictable pattern: they create a directory for prod-us-east-1, copy the entire module set, and then create another for prod-us-west-2. This results in massive HCL (HashiCorp Configuration Language) duplication. A simple change to a security group rule suddenly requires updates across twelve different directories, increasing the risk of configuration drift and manual error.

The core issue is that Terraform is designed to manage a single state file and a specific set of resources, but it lacks a native mechanism to orchestrate the repetition of those resources across different environments without duplicating the code.

The Thesis: Intent vs. Implementation

Terramate solves this by introducing an orchestration layer that separates your intent (the architecture you want) from the implementation (the actual .tf files Terraform reads). Instead of writing static HCL for every environment, you define a "Stack" abstraction. Terramate then generates the necessary Terraform files based on templates and variables, ensuring consistency while allowing for environment-specific overrides.

How Stack Abstractions Work

In Terramate, a Stack is essentially a logical grouping of Terraform modules. Rather than manually creating folders, you define the structure in .terramate files. These files act as the blueprint.

• Global Configuration: Define variables or provider settings that apply to every single environment.
• Stack Overrides: Specify only what changes (e.g., instance size or region) for a specific environment.
• Generation: Terramate expands these definitions into standard .tf files that Terraform can execute.

Worked Example: Multi-Region VPC Deployment

Imagine you need to deploy a standard VPC across us-east-1 and eu-west-1. Instead of two identical folders with different variables, you use Terramate to generate them.

1. Define the Stack Intent

Run this in your terminal to create a basic Terramate configuration (assuming Terramate CLI is installed):

# Create a directory for your infrastructure
mkdir my-infra && cd my-infra
# Initialize terramate
terramate init

2. Configure the Template

Create a terramate.hcl file to define your global variables and the stacks you want to generate:

# terramate.hcl
globals {
  vpc_cidr = "10.0.0.0/16"
}

stack "us-east-1" {
  vars = {
    region = "us-east-1"
  }
}

stack "eu-west-1" {
  vars = {
    region = "eu-west-1"
  }
}

3. Generate and Deploy

Run the following command from the root directory with the appropriate permissions to write to the filesystem:

# Generate the actual .tf files from the templates
terramate generate

# Orchestrate the apply across all generated stacks
terramate run terraform apply

Expected Result: Terramate creates separate directories for each region, populating them with terraform.tfvars files containing the region-specific values and the shared VPC CIDR.

Trade-offs and Limitations

While Terramate removes duplication, it introduces a new layer of abstraction. The primary risk is abstraction leakage. If you spend too much time creating complex, nested templates, debugging the resulting HCL becomes difficult because the code you are editing is not the code Terraform is executing.

Additionally, it is critical to remember that Terramate does not manage state. It is an orchestrator, not a state store. You still need a robust Terraform backend (like S3 or Terraform Cloud) configured within your modules to ensure state is locked and persisted correctly.

Verification and Rollback

To verify the result, inspect the generated directories. You should see that the .tfvars files differ by region but the module calls remain identical.

Rollback: Since terramate generate modifies the local filesystem by creating or updating .tf files, the primary way to roll back is via your version control system (Git). Revert the changes to your .terramate files and run terramate generate again to overwrite the generated HCL with the previous state.