Terraform CI/CD: Designing Robust plan/apply Automation

This article lays out the practical guidelines for embedding Terraform plan/apply into CI/CD so you get both clear change visibility and safe deployments.

We break down the key topics that the exam often tests — freezing the change plan, state locking, approval gates, and version pinning — in a form you can actually apply in the field.

Goals and Scope

The goal is to build a pipeline that freezes the Terraform plan output in a form a human can review, and then applies only that exact same plan to production. This guarantees that even if code or external state changes after review, the applied content cannot be swapped out.

The intended reader is an intermediate-to-advanced practitioner who already understands cloud privilege separation and the basics of running a remote backend. Terraform version management, the provider lock file, and remote backend locking are the foundations for everything that follows.

• Pin Terraform and provider versions (commit .terraform.lock.hcl to VCS)
• Manage state remotely with locking enabled (e.g., S3 + DynamoDB, azurerm, gcs)
• CI generates and stores the plan; CD applies that exact plan after approval

Pipeline Design Principles

Always separate plan and apply into distinct phases, and have apply consume the stored plan file as-is. It is critical that the apply phase never re-runs plan.

Keep Terraform and provider versions identical between the CI and CD environments. Because a plan file depends on Terraform/provider versions and the OS, the entire workflow must assume version parity.

• Immutability: emit the plan as a binary (-out) and apply only that exact file
• Reproducibility: pin Terraform/provider versions and commit the lock file
• Safety: -input=false, least-privilege service principals, remote state with locking
• Observability: use -detailed-exitcode to detect changes programmatically, and store plan as an artifact
• Approval: place apply downstream of a human review, and control permissions and concurrency per environment

Baseline pipeline that separates plan from apply

Reference Implementation: Minimal CI/CD Staging

The following is a minimal example that proceeds in order: 1) static checks, 2) initialization, 3) validation, 4) saving the plan, 5) manual approval, 6) applying the plan. We express it as shell steps so it stays independent of any specific CI/CD product.

Inject backend configuration and sensitive variables from the CI secret store or environment variables, and disable interactivity with -input=false.

• Save the plan as plan.bin and hash it so you can detect tampering
• Apply by passing plan.bin directly (terraform apply plan.bin); never regenerate the plan
• Use -detailed-exitcode to skip the apply stage when there are no diffs

CI/CD reference script (pseudo-example)

# CI: 計画の生成
set -euo pipefail

# 1) フォーマットと静的検査
terraform fmt -check -recursive
terraform init \
  -input=false

# 2) バリデーション
terraform validate -no-color

# 3) ワークスペース/環境の選択
# export TF_WORKSPACE=staging
# terraform workspace select "$TF_WORKSPACE" || terraform workspace new "$TF_WORKSPACE"

# 4) 変更計画の作成（詳細終了コードで差分検出）
set +e
terraform plan \
  -out=plan.bin \
  -lock=true \
  -input=false \
  -no-color \
  -detailed-exitcode
rc=$?
set -e

if [ "$rc" -eq 0 ]; then
  echo "差分なし。apply は不要"; exit 0
elif [ "$rc" -eq 2 ]; then
  echo "差分あり。plan.bin を保存して承認待ちへ";
  sha256sum plan.bin > plan.bin.sha256
  # ここで CI のアーティファクトに plan.bin とハッシュを保存
else
  echo "plan 失敗"; exit $rc
fi

# --- 手動承認ゲート（人のレビュー）---

# CD: plan の適用（同一バージョンの Terraform/Provider 前提）
sha256sum -c plan.bin.sha256
terraform init -input=false
terraform apply -input=false -auto-approve plan.bin

Environment Separation and Approval Flow

Separate environments via directory splits (state separated per env directory), workspaces (one configuration, multiple states), or repository splits. In every case, state must be physically separated, and locking must be in place so concurrent apply runs cannot interfere with one another.

Center review and approval on the plan's visibility. The review target is not just the HCL diff but also the plan's summary of resource adds, changes, and deletes. Post-approval apply must use the plan.bin generated at approval time — never re-run plan immediately before apply.

• Directory split: envs/prod, envs/stg, etc. — the most intuitive option, with clearly separated state
• Workspaces: a fit when you want to switch tenants/environments while keeping the same configuration
• Approval gate: human approval, RBAC, recorded change rationale, and hash verification of the plan artifact

State Management, Locking, and Concurrency Control

Remote backends give you centralized state management and locking. Major backends — S3 + DynamoDB locking, azurerm, gcs — all ship with a locking mechanism. -lock defaults to true, but in CI/CD it's worth setting it explicitly to make intent clear.

Apply concurrency control at two layers. First, the backend lock. Second, CI/CD queuing that serializes apply runs against the same environment. Together, they prevent state corruption from parallel apply runs. Parallelism across separate environments and separate states becomes much easier to allow.

• Design so that terraform init -migrate-state is unnecessary unless the backend itself changes
• Reference outputs from other states via data "terraform_remote_state" so dependencies stay explicit
• Handle rollback via Git revert plus a fresh plan/apply — avoid editing state directly

Operational Pattern Comparison and Exam Prep Points

Terraform automation broadly splits into DIY general-purpose CI/CD, Terraform Cloud/Enterprise VCS integration, and API-driven execution. Compare them on state management, policy, approval UX, and cost when choosing.

From an exam perspective, frequently tested topics include plan freezing and apply separation, remote state and locking, version pinning, least privilege, the meaning of -detailed-exitcode, and where policy enforcement (such as Sentinel) fits in.

• Humans review the plan; machines execute apply faithfully
• Applying the identical plan makes "what was reviewed" and "what was applied" match exactly
• Policies like Sentinel/OPA are evaluated at the plan stage or as a pre-apply gate

Check Your Understanding

Frequently Asked Questions