Enforcing Naming Conventions with Terramate Policies: A Practical Guide

Problem: Governance Drift in Terraform Repositories

When teams grow, Terraform modules can slip into a state where resources are named inconsistently, missing required tags, or even using disallowed providers. Manual reviews catch many of these issues, but they are slow and error‑prone. The result is drift from organizational policy and an increased risk of non‑compliant infrastructure.

Thesis: Terramate’s Policy Layer Adds a Declarative Governance Hook

Terramate’s policy feature lets you write reusable, declarative rules that run automatically before any terraform plan. By codifying naming conventions, mandatory tags, and resource restrictions, you can block misconfigurations early, reduce audit effort, and keep your Terraform codebase compliant without adding a new toolchain.

How Terramate Policies Work

Policies are written in Terramate’s simple declarative language (a subset of HCL). They are stored alongside your Terraform modules in a policy/ directory and evaluated by the tmt policy test command. The evaluation happens at the Terramate layer, so it sees the full module graph and can enforce rules across module boundaries.

Key concepts:

• Policy modules – reusable policy snippets that can be imported into other policies.
• Policy tests – declarative checks that run against the current module state.
• Policy report – a JSON or HTML report generated by Terramate, viewable on the dashboard or in CI logs.

Concrete Example: Forbid aws_instance Resources

1. Create a module that uses aws_instance

   # modules/webapp/main.tf
   resource "aws_instance" "web" {
     ami           = "ami-123456"
     instance_type = "t3.micro"
   }
   

2. Define a policy that disallows aws_instance

   # policy/forbid-aws-instance.tmt
   policy "forbid-aws-instance" {
     description = "Disallow any aws_instance resources"
     rule "no_aws_instance" {
       source = "resource.aws_instance"
       assert = false
       error_message = "aws_instance resources are not allowed"
     }
   }
   

3. Run the policy test

   # Run in the repository root
   $ tmt policy test
   
   INFO  Policy "forbid-aws-instance" executed
   FAIL  Rule "no_aws_instance" violated: aws_instance resources are not allowed
   
   ERROR  Policy test failed – plan aborted
   

   Run this before terraform plan in your CI pipeline:

   tmt policy test && terraform plan
   

4. Verify the audit log

   After a failing run, open the Terramate dashboard. The policy report shows the violation, the resource path, and the commit that introduced it. This gives you traceability for remediation.

Trade‑Offs and Limitations

• Runtime overhead – Policy evaluation adds a few seconds to each tmt policy test call. In large monorepos with many modules, this can become noticeable.
• Separate from Terraform validation – Terramate policies run before Terraform’s own terraform validate. Errors that Terraform would catch (e.g., syntax errors) still need to be handled separately.
• Policy maintenance – Policies live in code, so they need versioning, reviews, and updates when module structures change. A well‑defined Git workflow for policy changes is essential.
• Potential overrides – If a team introduces a --skip-policy flag or misconfigures the CI job, governance can be bypassed. Guard against this by making policy tests mandatory in the merge pipeline.

Practical Checklist for Adopting Terramate Policies

1. Install Terramate CLI (v0.15+): curl -fsSL https://github.com/gruntwork-io/terramate/releases/download/v0.15.0/terramate_linux_amd64.tar.gz | tar -xz -C /usr/local/bin
2. Initialize Terramate in your repo: tmt init
3. Create a policy/ directory and add your first policy module.
4. Add tmt policy test as a pre‑plan step in your CI pipeline.
5. Configure the Terramate dashboard to capture policy reports.
6. Review and merge policy changes through the same PR workflow as infrastructure code.

Conclusion

Terramate’s policy layer gives teams a lightweight, declarative way to enforce governance across all Terraform modules. While it adds a small runtime cost and requires disciplined policy maintenance, the payoff is early detection of non‑compliant infrastructure and audit‑ready logs. Start with a simple rule—like forbidding a specific resource type—and iterate from there.