Terraform Operational Standards

Patterns and rules that apply to all three Terraform repositories: azure-infra, aws-infra, azure-dde-infra.

---

Import-Before-Fixing Pattern

Rule: Never remediate an existing, unmanaged resource in the same PR that imports it into Terraform state. Always import first (zero diff), merge, then remediate in a separate PR.

Why

Combining import and remediation in one PR makes the plan unreadable: reviewers cannot distinguish "changes caused by taking ownership" from "changes caused by the remediation." More critically, if the import diff is wrong, the apply will destroy the resource and recreate it — potentially causing an outage or data loss.

When It Applies

This pattern is mandatory any time you are bringing an existing resource under Terraform management:

Resource type	Risk if skipped
Azure VMs	Names are immutable — wrong plan destroys and recreates with new resource ID
Databases (PostgreSQL, SQL)	Destroy = data loss
Firewalls / NSGs	Destroy = outage
Recovery Services Vaults	Destroy = loss of all recovery points
S3 buckets with Object Lock	Cannot be recreated easily
Any resource with dependents	Dependency chain failure on destroy

Steps

Step 1 — Import (zero-diff PR)

# 1. Write the HCL resource block matching current live config exactly.
# 2. Import the resource into state.
terraform import <resource.type.name> <resource_id>

# 3. Run plan — it must show no changes.
terraform plan

# 4. If plan shows changes, adjust HCL until plan is clean.
# 5. Open PR. The plan posted by CI must show "No changes."

Step 2 — Remediate (separate PR)

Once the zero-diff PR is merged:

# 1. Create a new branch.
# 2. Make the remediation change (add encryption, fix tags, enable logging, etc.).
# 3. Open a normal PR. CI plan now shows only the remediation change, nothing else.

PR Checklist Reminder

Every PR in the infra repos includes a checklist item:

If modifying existing resources: confirmed import-before-fix pattern applied — resource was imported with a zero-diff PR before this remediation PR was opened.

References

• azure-infra/CLAUDE.md → Architecture Principles → "Import before fixing"
• aws-infra/CLAUDE.md → Architecture Principles → "Import before fixing"
• azure-dde-infra/CLAUDE.md → Architecture Principles → "Import before fixing"

---

Terraform fmt Requirement

All .tf files must pass terraform fmt before committing. CI enforces this with a fmt-check step that fails the PR on any formatting diff.

Run after every edit:

terraform fmt <directory>/

---

PR Pre-Flight Checklist

Before opening any PR against an infra repo:

1. terraform init — confirm backend connects
2. terraform validate — syntax check
3. terraform plan -out=tfplan — paste the summary line in the PR description
4. New resource type? Check quota/service limits
5. Dependency ordering confirmed for new resources
6. External-facing URLs validated before dependent resources reference them
7. All 6 steps above pass — only then open the PR

---

Document History

Date	Change	Author
2026-04-15	Initial draft — import-before-fixing pattern, fmt requirement, PR checklist (MOD-008)	Kobe