How to make Terraform changes

Aucert's infrastructure uses a three-tier Terraform layout. Each tier has different blast radius and safety requirements.

Three-tier layout

Tier	Path	State key	Blast radius
Foundation	infra/terraform/foundation/	foundation.tfstate	VNet, AKS, ACR, Key Vault, DNS, Internal PG — destroying anything here affects ALL environments
Internal Platform	infra/terraform/internal-platform/	internal-platform.tfstate	Astra infrastructure — separate from product, but shared team tooling
Environments	infra/terraform/environments/{env}/	{env}.tfstate	Per-env resources (Product PG, Redis) — scoped to one environment

Remote state is stored in aucert-tfstate-rg (Azure Storage Account, created manually before Terraform).

General workflow

Step 1: Plan

cd infra/terraform/{tier}
terraform init
terraform plan -out=plan.tfplan

Always review the plan output carefully before applying.

Step 2: Apply

terraform apply plan.tfplan

Step 3: Update context files

After applying, update the corresponding context file. This is mandatory — CI will block PRs that change Terraform without updating context.

Tier	Context file
Foundation	infra/.context/CLOUD.md + .context/CLOUD_SUMMARY.md
Internal Platform	infra/.context/INTERNAL_PLATFORM.md
Environments	infra/.context/ENVIRONMENTS.md

---

Tier-specific guidance

Foundation tier

danger

Maximum caution required. Foundation resources are shared across all environments. Destroying the VNet, AKS cluster, or Key Vault will take down everything.

Files:

infra/terraform/foundation/
  main.tf       # Provider, backend, resource group
  network.tf    # VNet, subnets, DNS zones
  aks.tf        # AKS cluster, node pool
  acr.tf        # Container registry
  keyvault.tf   # Key Vault
  database.tf   # Internal platform PostgreSQL

Before changing foundation:

1. Review what depends on the resource (other tiers, K8s workloads)
2. Use terraform state list to understand the full resource graph
3. Never remove prevent_destroy lifecycle rules without explicit approval
4. Plan changes during low-activity windows
5. Have rollback procedures documented

Common foundation changes:

• Adding a subnet: Edit network.tf, ensure CIDR doesn't overlap
• Scaling AKS nodes: Edit aks.tf node pool count
• Adding Key Vault secrets: Use az keyvault secret set (not Terraform for secret values)

Internal Platform tier

warning

Affects shared team tooling (Astra, Plane). Coordinate with the team before applying changes.

Common changes:

• Updating K8s manifests: Edit files in infra/k8s/internal-platform/
• Database schema changes: Use Flyway migrations, not Terraform

Environment tier (dev/staging/prod)

Safest tier — scoped to a single environment. Dev changes don't affect staging or production.

cd infra/terraform/environments/dev
terraform plan -out=plan.tfplan
terraform apply plan.tfplan

Files:

infra/terraform/environments/dev/
  main.tf           # Provider, backend, resource group
  database.tf       # Product PostgreSQL
  redis.tf          # Redis cache
  terraform.tfvars  # Dev-specific variable values
  variables.tf      # Variable declarations
  outputs.tf        # Exported values

Common environment changes:

• Scaling database: Edit database.tf SKU
• Adding Redis configuration: Edit redis.tf
• Provisioning staging: Copy dev/ structure to staging/, update terraform.tfvars

Safety checklist

Before applying any Terraform change:

• terraform plan reviewed — no unexpected destroys
• Resources with prevent_destroy are not being modified unsafely
• Context file update prepared in the same PR
• Team notified if foundation or internal-platform tier
• Rollback procedure considered for non-trivial changes

What's next

• Terraform tiers — Architecture deep dive
• Azure topology — Full resource inventory
• Secrets management — Key Vault integration