Terraform

Terraform

Quick Start (workflow)

terraform init
terraform plan -out=tfplan
terraform apply tfplan

Safety Checklist

• State: remote backend + locking; separate state per environment
• Reviews: plan in CI; apply from a trusted runner with approvals
• Guardrails: prevent_destroy and policy checks for prod

Load Next (References)

• references/state-and-environments.md — backends, locking, workspaces vs separate state, drift
• references/modules-and-composition.md — module interfaces, versioning, composition patterns
• references/workflows-and-guardrails.md — CI plan/apply, policy-as-code, safe migrations

Modules and Composition

Module Design Principles

• Keep module interfaces small and stable (inputs/outputs).
• Avoid over-abstraction; start with a root module, extract modules when duplication appears.
• Version modules and pin versions in consumers.

Recommended structure:

• Root module per environment (or per stack)
• Reusable modules for common building blocks (network, compute, database)

Inputs and Outputs

Patterns:

• Use typed variables with validation
• Expose only what downstream consumers need

variable "environment" {
  type        = string
  description = "Deployment environment (dev/staging/prod)"
  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "environment must be dev, staging, or prod"
  }
}

Iteration and Addressing

Prefer for_each over count when stable addressing matters:

• for_each uses keys (more stable across inserts)
• count shifts indexes when items are inserted/deleted

Safe Refactors

When renaming resources or moving them into modules:

• Use moved blocks (Terraform 1.1+) where possible
• Or use terraform state mv with care and review

Testing

Practical baseline:

• terraform fmt, validate, and plan in CI on every PR
• Add policy checks (security/cost) for production stacks

Optional:

• Terratest (Go) for integration tests
• terraform test (if standardised in the repo and tooling)

State and Environments

State Safety Rules

• Use a remote backend with locking for any shared environment.
• Treat state as sensitive; it often contains resource attributes and secrets.
• Separate state for production vs non-production to limit blast radius.

Backends and Locking

Patterns:

• Remote object store backend + lock table (common)
• Managed backend with built-in locking and history (common)

Checklist:

• Enable encryption at rest
• Restrict IAM access to the backend (read/write only for CI and break-glass operators)
• Enable versioning for state history

Environments: Workspaces vs Separate State

Prefer separate state per environment for most teams:

• Clear separation of prod vs staging
• Independent locking, permissions, and retention
• Fewer workspace foot-guns

Use workspaces when:

• A single root module is intentionally shared
• Workspace isolation is well understood and enforced in tooling

Drift, Imports, and State Ops

Drift:

• Run plan regularly in CI to detect drift (or scheduled checks).

Imports:

• Use terraform import for adopting existing resources.
• Follow with a plan to confirm parity.

State commands (use carefully):

terraform state list
terraform state show <addr>
terraform state mv <from> <to>
terraform state rm <addr>

Avoid manual edits of the state file.

Secrets

If a provider returns a secret value, it can land in state.

Patterns:

• Use secret managers for secret generation and distribution
• Prefer references (ARN/ID/path) over raw secret values
• Restrict state access and audit reads

Workflows and Guardrails

Standard Workflow

1) Format + validate (fmt, validate) 2) Plan in CI and publish the plan output 3) Review the plan (including diffs to sensitive resources) 4) Apply from a trusted runner after approval

Avoid ad-hoc local applies for shared environments.

Guardrails in Code

Lifecycle protections:

lifecycle {
  prevent_destroy = true
  create_before_destroy = true
}

Change management:

• Require explicit approvals for production applies
• Require plan-only for PRs and apply-only for protected branches

Policy and Security Checks

Common additions:

• tflint (linting)
• trivy config, tfsec, or checkov (IaC security)
• Conftest/OPA or Sentinel for policy-as-code
• Cost estimation gates (where applicable)

Migrations and Renames

Safer patterns:

• Use moved blocks for refactors
• Apply in small steps
• Avoid -target except for recovery and controlled migrations

Disaster Recovery

Checklist:

• Versioned remote state
• Backend access logs enabled
• Document break-glass procedure for state recovery and unlocks