Which strategy best manages global variable propagation across hierarchical stacks in Terramate?

The Recommended Strategy

The most effective strategy for managing global variable propagation in Terramate is the Top-Down Inheritance Pattern. In this model, global constants and shared settings are defined in a root-level terramate.hcl file and propagated downward to leaf-node stacks during the generation phase. This centralizes the source of truth while leveraging Terramate's orchestration layer to inject these values into stack-specific .tfvars files.

Implementation Logic

To balance centralization with the need for stack-specific overrides, follow these architectural patterns:

• Root-Level Defaults: Define baseline variables at the highest possible level in the directory hierarchy. These act as the "global" defaults for all inheriting stacks.
• Hierarchical Overrides: Place override values in terramate.hcl files located in sub-directories. Terramate's inheritance logic allows child configurations to supersede parent values, ensuring that a specific environment (e.g., prod vs dev) can modify a global variable without affecting other branches of the tree.
• Generation-Time Injection: Use Terramate templates to map these hierarchical variables into the final HCL output. This keeps the orchestration logic separate from the Terraform resource logic.

Verification Steps

To verify that variables are propagating and overriding correctly, use the following scoped approach:

1. Identify a global variable in the root terramate.hcl.
2. Define a conflicting value for that same variable in a child stack's terramate.hcl.
3. Execute the generation command: terramate generate.
4. Inspect the resulting .tfvars file in the child stack directory to confirm the override took precedence over the global value.

Constraints and Validation

Terramate primarily functions as a generation-time orchestrator rather than a runtime validator. It does not provide a native "type-checking" or "constraint enforcement" mechanism (like a schema validator) to prevent invalid values from being written into the generated .tf files. Validation of variable constraints is deferred to the Terraform provider level during terraform plan or terraform apply.

Assumption: This guidance assumes the use of Terramate's standard hierarchical directory structure where terramate.hcl files are used for configuration inheritance.

Diagnostic Detail Needed: Are you utilizing custom Terramate templates for variable generation, or relying on the default generation behavior? This determines whether you can implement custom validation logic within the template itself.