managing-terraform-recipe

Terraform Workflows

Quick Reference

Plan → Store → Review → Apply → Delete Plan

PLAN_FILE="/tmp/tf-plans/$(date +%Y%m%d_%H%M%S)_$(basename $(pwd)).tfplan"
terraform plan -parallelism=100 -out="$PLAN_FILE"
terraform apply -parallelism=100 "$PLAN_FILE" && rm "$PLAN_FILE"

When to Use

Terraform operations | plan | apply | infrastructure changes | IaC

Core Workflow

MANDATORY sequence:

1. terraform plan → store → /tmp/tf-plans/
2. Review plan output
3. terraform apply {plan_file}
4. Delete plan file (on success)

Plan file naming:

Format: YYYYMMDD_HHMMSS_{project_name}.tfplan
Example: /tmp/tf-plans/20250124_143022_myproject.tfplan

Planning

mkdir -p /tmp/tf-plans

PLAN_FILE="/tmp/tf-plans/$(date +%Y%m%d_%H%M%S)_$(basename $(pwd)).tfplan"
terraform plan -parallelism=100 -out="$PLAN_FILE"

Plan flags:

terraform plan -parallelism=100 -var-file=prod.tfvars -out="$PLAN_FILE"
terraform plan -parallelism=100 -target=aws_instance.web -out="$PLAN_FILE"
terraform plan -parallelism=100 -destroy -out="$PLAN_FILE"

Forbidden patterns:

terraform plan -out="$PLAN_FILE" -timeout=30m  ✗
terraform apply  ✗
terraform plan -out="$PLAN_FILE"  ✗
terraform force-unlock {LOCK_ID}  ✗
git commit -a  ✗

Applying

MANDATORY: Apply from stored plan + cleanup

terraform apply -parallelism=100 "$PLAN_FILE" && rm "$PLAN_FILE"

Pattern:

apply success → delete plan | apply fail → keep plan for debugging

Apply violations:

terraform apply  ✗
terraform apply -auto-approve  ✗
terraform apply "$PLAN_FILE"  ✗
terraform force-unlock {LOCK_ID}  ✗
git add terraform.tfstate  ✗
git add *.tfplan  ✗

Timeout Policy

NEVER set -timeout flag → Terraform handles internally

State Lock Policy

NEVER force-unlock without user confirmation → Risk of state corruption

Pattern:

State locked → Ask user first → User confirms → terraform force-unlock {LOCK_ID}
State locked → Ask user first → User declines → Wait for lock release

File Security Policy

State files contain SECRETS → NEVER commit → Delete when no longer needed
Plan files contain infrastructure details → NEVER commit → Auto-delete after apply

Critical rules:

State files: terraform.tfstate, *.tfstate, *.tfstate.backup
Plan files: *.tfplan

ALWAYS in .gitignore → NEVER commit to git → Risk of secret exposure

Pattern:

Before git commit → Verify no .tfstate or .tfplan files staged
Local state files no longer needed → Delete manually
Plan files → Auto-deleted after successful apply (already handled)

Cleanup:

git status | grep -E '\.tfstate|\.tfplan'
rm terraform.tfstate terraform.tfstate.backup
find . -name "*.tfstate.backup" -mtime +30 -delete

Common Operations

Operation	Command
Initialize	terraform init
Validate	terraform validate
Plan new	terraform plan -parallelism=100 -out="$PLAN_FILE"
Apply plan	terraform apply -parallelism=100 "$PLAN_FILE" && rm "$PLAN_FILE"
Destroy plan	terraform plan -parallelism=100 -destroy -out="$PLAN_FILE"
Destroy apply	terraform apply -parallelism=100 "$PLAN_FILE" && rm "$PLAN_FILE"

Plan Storage Management

ls -lh /tmp/tf-plans/
find /tmp/tf-plans/ -name "*.tfplan" -mtime +7 -delete
terraform show -json "$PLAN_FILE" | jq .

Error Handling

Error	Fix
No plan file	Run terraform plan -parallelism=100 -out="$PLAN_FILE" first
Plan expired	Re-run plan → apply new file
Lock error	Ask user → Confirm → terraform force-unlock {LOCK_ID}
Invalid credentials	Check AWS_PROFILE/credentials
AuthorizationFailure	Ask user → Check Engineering VPN connection → https://www.notion.so/andercore/Set-up-engineering-Azure-VPN-client-13e2b55ffcb380f3a952fed671aebbdc
State locked	Ask user → Wait or force-unlock (only if confirmed)
State file in git	git reset terraform.tfstate → Add to .gitignore → CRITICAL

Security Gates

Pre-apply checks:

terraform validate
terraform fmt -check
terraform show "$PLAN_FILE"

Pre-commit checks:

git status --porcelain | grep -E '\.tfstate|\.tfplan'
grep -E '\.tfstate|\.tfplan' .gitignore

.gitignore entries:

*.tfstate
*.tfstate.*
*.tfplan
.terraform/

State management:

terraform state list
terraform state show {resource}
terraform state pull > backup.tfstate

Validation Workflow (Execute After Terraform Operations)

MANDATORY: Run after plan/apply operations.

Phase	Action
1. Execute	Plan → store → apply sequence
2. Validate	Gather evidence from execution, confirm workflow compliance
3. Report	✓ Pass → Done | ✗ Fail → List violations with evidence
4. Fix	Violations found → Correct → Re-validate

Validation principle:

Validation = Evidence gathering + Output confirmation
NOT re-running operations

Validation method:

Review conversation context (NOT re-execute)
→ Gather evidence from tool calls/outputs
→ Check required steps occurred
→ Verify temporal order (plan before apply)
→ Cite evidence in report

Validation checks:

Check	Evidence Source
Plan executed first	Bash tool call: terraform plan
Plan stored in /tmp/tf-plans/	Bash output: PLAN_FILE path
Parallelism=100 used	Bash command: -parallelism=100 in args
No timeout flag used	Bash command: no -timeout in args
No force-unlock without confirmation	Conversation: AskUserQuestion before force-unlock
No state files committed	Git commands: no git add with .tfstate/.tfplan
Apply used stored plan	Bash tool call: terraform apply "$PLAN_FILE"
Plan deleted on success	Bash command: && rm "$PLAN_FILE"
Temporal order	Tool call sequence: plan before apply

Output format (with evidence):

VALIDATION REPORT:
✓ Plan first: terraform plan executed [Evidence] Bash call #1: terraform plan -out=...
✓ Plan storage: /tmp/tf-plans/20250124_143022_project.tfplan [Evidence] Bash output
✓ Parallelism: -parallelism=100 [Evidence] Bash call #1 and #2
✓ No timeout: No -timeout flag [Evidence] Bash command review
✓ No force-unlock: No terraform force-unlock or AskUserQuestion preceded it [Evidence] Conversation review
✓ No state files committed: No git add with .tfstate or .tfplan [Evidence] Git commands review
✓ Apply from plan: terraform apply "$PLAN_FILE" [Evidence] Bash call #2
✓ Plan cleanup: && rm "$PLAN_FILE" [Evidence] Bash call #2
✓ Temporal order: Plan (#1) before apply (#2) [Evidence] Tool call sequence
✗ FAIL: State file committed
✗ Evidence: git add command includes terraform.tfstate

VIOLATIONS (1):
1. State file added to git (CRITICAL SECURITY)
   Evidence: Bash call shows 'git add terraform.tfstate' (contains secrets - NEVER commit)

ACTION: Fix violations and re-validate

Re-validation required after fixes. Repeat until ALL checks pass.

Workflow Summary

Check directory → terraform init (if needed)
↓
terraform plan -parallelism=100 -out="$PLAN_FILE"
↓
Store: /tmp/tf-plans/{timestamp}_{project}.tfplan
↓
Review plan output
↓
terraform apply -parallelism=100 "$PLAN_FILE" && rm "$PLAN_FILE"
↓
Validate: All steps completed in order

Advanced

Module operations:

terraform get
terraform get -update
terraform output -module={module_name}

Workspace management:

terraform workspace list
terraform workspace new {name}
terraform workspace select {name}

Import existing resources:

PLAN_FILE="/tmp/tf-plans/$(date +%Y%m%d_%H%M%S)_import.tfplan"
terraform plan -parallelism=100 -out="$PLAN_FILE"
terraform apply -parallelism=100 "$PLAN_FILE" && rm "$PLAN_FILE"