Terraform Pipelines in GitLab¶

Overview¶

Design a GitLab pipeline that runs init → validate → plan on merge requests (with a plan artefact) and a protected apply on the default branch — with remote state outside the runner workspace.

Terraform in GitLab CI automates Infrastructure as Code (IaC): every change is planned in review, then applied under gates. Store remote state with locking. Attach the binary plan as a job artefact so apply executes what reviewers saw. Never leave state only on the runner disk.

This is a core tutorial in Module 10 · Terraform Pipelines of the REBASH Academy GitLab CI/CD for Cloud & DevOps Engineers series — written for Cloud, DevOps, Platform, and SRE engineers.

Prerequisites¶

Kubernetes Deploys and GitLab Agent

Learning Objectives¶

By the end of this tutorial, you will be able to:

Sequence init, validate, plan, apply, and optional destroy
Store plan output as a GitLab artefact for MR review
Gate apply with a protected environment
Explain remote state + locking in CI
Use TF_IN_AUTOMATION and non-interactive flags

Architecture¶

This topic’s control points and relationships are shown below.

Theory¶

What it is¶

A Terraform pipeline maps CLI phases onto GitLab stages: fmt/validate and plan -out= on every MR (low / plan privilege); reviewed apply of the saved plan on the default branch or a protected environment; rare, heavily gated destroy. State lives in a remote backend with locking. CI uses short-lived credentials (often OIDC — Module 11). TF_IN_AUTOMATION=true and -input=false keep jobs non-interactive.

Why it matters¶

Laptop apply bypasses review and uses personal cloud keys. MR plans give reviewers a concrete diff; protected apply prevents unreviewed infrastructure changes. Plan artefacts stop “plan on Tuesday, apply Thursday’s different config.” State locking prevents two pipelines from corrupting the same workspace.

How it works¶

On MR: pin Terraform → init → validate → plan -out=tfplan → upload artefact (short expire_in).
Job log shows terraform show summary for reviewers.
On merge (or after environment approval): download the same artefact → apply -input=false tfplan.
Destroy jobs are manual and environment-protected.
Backend config comes from CI variables or a committed backend block — no secrets in Git.

Prefer apply-of-saved-plan for production.

Key concepts and comparisons¶

Concern	Good practice	Risk
State	Remote + lock	Local state on runner
Plan	Artefact tied to MR SHA	Fresh plan at apply with drift
Apply	Protected environment	Auto-apply on every push
Secrets	OIDC / masked vars	Static admin keys

Common pitfalls¶

Committing .terraform/ or terraform.tfstate to Git.
Applying without the reviewed plan artefact.
Logging plans that include secret attribute values.
One shared state key for all environments; fork MRs with apply roles.

Hands-on Lab¶

Create a workspace for this tutorial.

mkdir -p ~/rebash-gitlab/module-10 && cd ~/rebash-gitlab/module-10

Focus: plan/apply GitLab jobs with artefact plan (local backend)

Step 1 – Minimal Terraform + CI jobs¶

cat > versions.tf << 'EOF'
terraform {
  required_version = ">= 1.5.0"
  required_providers {
    null = { source = "hashicorp/null", version = "~> 3.2" }
  }
}
EOF
cat > main.tf << 'EOF'
resource "null_resource" "lab" {
  triggers = { note = "gitlab-terraform-lab" }
}
EOF
cat > .gitlab-ci.yml << 'EOF'
stages: [validate, plan, apply]
image: {name: hashicorp/terraform:1.9, entrypoint: [""]}
variables: {TF_IN_AUTOMATION: "true"}
validate:
  stage: validate
  script: ["terraform init -backend=false", "terraform validate"]
plan:
  stage: plan
  script: ["terraform init -backend=false", "terraform plan -out=plan.cache"]
  artifacts: {paths: [plan.cache], expire_in: 1 day}
apply:
  stage: apply
  needs: [plan]
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
      when: manual
  script: ["terraform init -backend=false", "terraform apply -auto-approve plan.cache"]
EOF

Step 2 – Local validate/plan/destroy¶

if command -v terraform >/dev/null; then
  terraform init -backend=false && terraform validate
  terraform plan -out=plan.cache && terraform apply -auto-approve plan.cache
  terraform destroy -auto-approve
fi
grep -E 'plan.cache|when: manual' .gitlab-ci.yml

Final step – Cleanup note¶

terraform destroy -auto-approve 2>/dev/null || true
# Keep ~/rebash-gitlab/ for later tutorials

Validation¶

Lab commands run under ~/rebash-gitlab/module-10/
You can explain each Theory section in your own words
You used modern tooling where it applies to this topic
You can describe one production failure mode for this topic

Code Walkthrough¶

Production practice for Terraform Pipelines in GitLab always combines:

Inspect before you change (status, plan, logs, dry-run)
Prefer reversible, documented changes (Git, IaC, drop-ins, version pins)
Capture evidence (command output, pipeline logs) for handovers
Prefer current tools and APIs over legacy shortcuts
Least privilege — escalate credentials only when required

Keep runbooks short enough to follow under pressure. Automate checks; keep humans for judgement.

Security Considerations¶

Treat credentials and tokens for gitlab as privileged — never commit them
Prefer short-lived auth (OIDC, roles, SSO) over long-lived keys
Validate blast radius before apply/deploy/delete operations
Restrict who can approve production changes
Collect audit logs; limit who can read sensitive traces

Common Mistakes¶

Committing .terraform/ or terraform.tfstate to Git.

Validate assumptions against the Theory section and official docs before changing production.

Applying without the reviewed plan artefact.

Lab shortcuts (open security groups, admin roles, skip approvals) must not ship unchanged.

Changing production without a rollback path

Always know how to revert (previous artefact, prior release, state rollback, DNS failback).

Best Practices¶

Encode Terraform Pipelines in GitLab changes as code and review them in pull requests
Pin versions (images, modules, actions, provider plugins)
Separate environments with clear promotion gates
Alert on symptoms with runbooks attached
Destroy lab resources; tag everything with owner and expiry where possible

Troubleshooting¶

Symptom	Likely cause	Fix
Auth / permission denied	Wrong identity, policy, or scope	Check caller identity, roles, and least-privilege policies
Timeout / no route	Network, DNS, security group, or endpoint	Trace path, DNS, and allow-lists before retrying
Drift / unexpected plan	Manual change or wrong state/workspace	Reconcile desired vs actual; avoid click-ops on managed resources
Pipeline/job red	Flaky step, cache, or missing secret	Read failing step logs; bisect recent workflow/config changes
Cost spike	Idle load balancer, NAT, oversized compute	Inventory billable resources; stop/delete labs promptly

Summary¶

Terraform Pipelines in GitLab is essential for Cloud and DevOps engineers working with gitlab. Practise the lab until the inspection and change path is muscle memory, then continue the track.

Interview Questions¶

Why store terraform plan as an artifact before apply?
What does TF_IN_AUTOMATION change about Terraform CLI behaviour?
How do you keep state safe when plans run in CI?
Why is apply usually manual on the default branch?
How do you destroy lab infrastructure created in a pipeline experiment?

Sample answer — question 2

Confirm init backend config and that apply uses the exact plan artifact from the same pipeline. Drift and different variable sets between plan/apply are common.

Sample answer — question 4

Protect state with remote backends and restricted IAM/OIDC roles. Destroy experimental stacks in the same change window.

References¶

Terraform and GitLab · Automating Terraform · Environments

Terraform Pipelines in GitLab¶

Overview¶

Prerequisites¶

Learning Objectives¶

Architecture¶

Theory¶

What it is¶

Why it matters¶

How it works¶

Key concepts and comparisons¶

Common pitfalls¶

Hands-on Lab¶

Step 1 – Minimal Terraform + CI jobs¶

Step 2 – Local validate/plan/destroy¶

Final step – Cleanup note¶

Validation¶

Code Walkthrough¶

Security Considerations¶

Common Mistakes¶

Best Practices¶

Troubleshooting¶

Summary¶

Interview Questions¶

Related Tutorials¶

References¶