Terraform Patterns

Modern Infrastructure as Code patterns for Terraform, emphasizing modularity, safety, and team collaboration.

Core Principles

Note: HashiCorp changed Terraform license (BSL). OpenTofu is the community MPL-2.0 fork.

Standard Module Structure

Standard module: main.tf, variables.tf, outputs.tf, versions.tf, README.md + examples/. See reference.md for full directory tree.

Design Guidelines

1. Single responsibility - One logical component per module
2. Sensible defaults - Work out-of-the-box
3. Validate inputs - Catch errors early
4. Explicit outputs - Clear contract
5. Semantic versioning - Tag releases

State Management

Remote backend required. Enable versioning, locking, encryption, and IAM access control.

EC2 Import Workflow

Two-phase approach: achieve zero-diff on import first, then apply intentional changes (hardening) as a separate plan/apply.

Pre-Import Reconnaissance

Best practice: capture ground truth via describe-instances, describe-volumes, and describe-addresses before writing HCL. See examples.md for the full reconnaissance command set.

Drift-Prone Attributes (t2/t3)

Missing these causes perpetual plan drift: credit_specification, monitoring, ebs_optimized, root_block_device.throughput, root_block_device.iops.

Import Gotchas

• AMI: Pin as literal string, not data.aws_ami — data source may resolve to a different AMI, triggering instance replacement (ami is ForceNew)
• EIP association: Import uses the association ID (eipassoc-*), not the allocation ID — retrieve via describe-addresses --query 'Addresses[0].AssociationId'
• SG rename: AWS SG names are immutable — renaming triggers destroy+recreate. Use lifecycle { create_before_destroy = true } to avoid traffic gaps
• State cleanup: Before removing .tf files, run terraform state rm or terraform destroy -target for each managed resource to prevent orphans

Pre-Apply Discovery

Accounts with prior manual provisioning may have resources that conflict with Terraform-managed equivalents. Running recon before the first apply surfaces these — see examples.md for pre-apply recon commands.

Import-then-harden workflow: recon live state → match HCL to exact live attributes → terraform import → plan (verify zero-diff) → add intentional changes → apply.

data sources reference existing account-wide singletons (OIDC providers) without claiming ownership. resource blocks claim ownership — if the singleton already exists, the apply fails. See aws-security-hardening skill for OIDC provider details.

ECR Configuration

image_tag_mutability = "MUTABLE" accommodates pipelines that push :latest on every deploy — IMMUTABLE rejects the second push silently. SHA tags still provide traceability. ECR lifecycle policies prune orphaned layers accumulated from MUTABLE tag overwrites.

Gate Selection for Non-Terraform Infrastructure

The plan-cost quality gate assumes infrastructure = Terraform. For shell scripts, systemd units, and CI/CD changes classified under "infrastructure" in aiee/project.yaml, fall back to test-enforcement or peer review when no .tf files are changed.

Anti-Patterns

Critical Rules

1. Secrets in tfvars get committed to VCS and leak on any repo clone — store them in Secret Manager and reference dynamically.
2. Unlocked provider versions resolve to different releases across machines — commit .terraform.lock.hcl so every run is deterministic.
3. Unreviewed plans destroy production resources without warning — read every plan output, especially lines prefixed with -.
4. Untagged module references (?ref=main) pull breaking changes silently — pin with ?ref=v1.2.3 and treat upgrades as explicit decisions.
5. Drift discovered at apply time means a human is in the loop under pressure — running plan in CI surfaces drift before it becomes an incident. See reference.md for environment separation patterns, state safety, state lock prevention, zero-downtime migration, IAM binding placement, deployment process, cross-repo secret validation, and multi-phase ticket validation.

See examples.md for complete module examples, CI/CD pipelines, Makefile patterns, and pre-commit configuration.