Overview
This section documents our opinionated approach to writing, organizing, and operating Terraform code. It covers naming conventions, structural guidelines, state management, and everyday best practices that every engineer working on infrastructure should follow.
Naming Conventions
Consistent naming reduces cognitive load and makes resources discoverable across the organization. All Terraform identifiers and cloud resource names must follow these conventions.
Backends
Terraform state is the source of truth for your infrastructure. Treat it with the same care as a production database.
Module Structure
Modules are the primary reuse mechanism in Terraform. A well-structured module is self-documenting, easy to test, and safe to version independently.
Code Organization
Repository Layout
Variables & Outputs
Variables
Providers
- Pin provider versions using ~> (pessimistic constraint) to allow patch updates but prevent major-version surprises.
Modules
- Prefer small, single-purpose modules over large all-in-one modules.
Secrets Management
- Never commit secrets, passwords, or API keys to version control.
CI/CD Pipeline
All production changes must go through the CI/CD pipeline. Developer machines may run apply only against personal sandbox environments.
Lifecycle & Version Management
Destroy Protection