Infrastructure Changes

Every infrastructure change follows the same loop: edit Terraform files, plan locally, push a PR, and let Cloud Build verify. This page walks through each step.

Agent Skill

This skill automates the full workflow below

/infra [Describe your change]

Prerequisites

Complete the setup guide before your first infrastructure change.

Identify the project

This monorepo contains five infrastructure projects:

Each project follows the same directory layout:

infra/<project>/business_unit_1/
├── development/
├── non-production/ # UAT / Staging
└── production/

Edit the .tf files in the relevant environment directory.

Run Plan

Before pushing, run plan to preview what Terraform will do. The build system handles authentication, initialization, and formatting automatically.

./zig/zig build plan -- <project> <environment>

The environment argument accepts short aliases:

Omit the environment to plan all environments at once (slower but comprehensive):

./zig/zig build plan -- ha-infra

To plan a single submodule within an environment, pass it as a third argument:

./zig/zig build plan -- ha-infra non-production cloudflare

This is useful when your changes are scoped to one folder.

Reading the output

Terraform marks each resource with a symbol:

# Will be CREATED
+ resource "azurerm_virtual_machine" "web_server" { ... }

# Will be MODIFIED in-place
~ resource "azurerm_dns_record" "api" {
    ~ ttl = 300 -> 600
  }

# Will be DESTROYED then RECREATED --- investigate before approving
-/+ resource "azurerm_storage_account" "logs" { ... }

Replace (-/+) means destroy-then-recreate. This can cause downtime, data loss, or changed IP addresses. Always investigate replacements before approving a plan.

The summary line at the bottom tells you the totals:

Plan: 1 to add, 1 to change, 0 to destroy.

Review every change. Unexpected destroys or replacements mean your branch is out of date with plan — rebase first (see below).

Format and Rebase

Format your code before pushing:

./zig/zig build fmt

Then rebase on the latest plan branch:

git fetch origin
git rebase origin/plan

Why rebase? If someone merged changes after you branched, your plan will show phantom destroys — Terraform sees their resources in state but not in your stale config, so it tries to delete them. Rebasing pulls in their config and eliminates the false positives.

After rebasing, re-run plan to confirm only your intended changes remain.

Create a Pull Request

All PRs target the plan branch, not main.

When the plan shows only your intended changes:

1. Commit your Terraform changes
2. Push your branch
3. Open a PR to plan and request review from the DevOps team

Cloud Build Verification

GCP Cloud Build runs plan commands for all environments automatically when the PR is created. Review the CI output to confirm it matches your local plan.

If CI shows changes you don’t see locally:

1. Rebase on origin/plan and re-plan — your branch is behind
2. If changes persist after rebasing, someone may have made manual infrastructure changes (drift). Check the DevHive developer dashboard — its continuous fuzzer checks for infra_drift, which indicates manual changes. Flag any drift to the DevOps team.

Troubleshooting

Plan shows resources I didn’t touch Rebase on origin/plan and re-plan. Stale branches produce phantom destroys.

Plan shows -/+ (replace) on a resource I only modified Some attribute changes force recreation (e.g., renaming a storage account). Check the Terraform docs for the resource to confirm which attributes are “ForceNew.”

./zig/zig build plan fails before showing output Run ./zig/zig build install to ensure dependencies are up to date, then retry.

Builds, authentication, or cached state errors Clear the project cache and retry:

./zig/zig build clean

Next Steps

After your PR is approved and merged, see Deploying Releases.