Forem: Abraham Naiborhu

Terraform Drift Detection and Recovery on Google Cloud: Plan, Import, State, and GitHub Actions

Abraham Naiborhu — Tue, 26 May 2026 09:06:50 +0000

Hi! so this is my fourth terraform artefact. I'd like to say that creating infrastructure with Terraform is one thing, but using Terraform when reality changes outside the code is another thing.

For the fourth artifact in my Terraform x Google Cloud portfolio, I wanted to explore a more operational topic:

Terraform drift detection, import, and state recovery.

In this project, i will not be building a large infrastructure platform. This project is about understanding what happens when:

someone changes infrastructure manually
Terraform state no longer matches real infrastructure
an existing resource needs to be imported
a resource is accidentally removed from state
drift needs to be detected automatically

The artifact repository:

terraform-gcp-drift-import-recovery

The main goal:

Understand Terraform failure modes, not only Terraform provisioning.

Why I Built This Artifact

My previous Terraform artifacts focused on building and delivering infrastructure.

The portfolio journey looked like this:

Artifact 1 — Terraform GCP Foundation
Artifact 2 — Production-Lite GCP Web Platform
Artifact 3 — Terraform CI/CD with GitHub Actions and WIF
Artifact 4 — Drift Detection, Import, and State Recovery

The first three artifacts answered:

Can I create infrastructure?
Can I structure it properly?
Can I expose it securely?
Can I automate Terraform plan and apply?

This fourth artifact answers a different question:

What happens when Terraform is no longer the only actor changing infrastructure?

That question matters because real cloud environments are rarely perfect.

Someone may change a firewall rule manually.

Someone may create a resource directly from the console.

Someone may remove a resource from Terraform state by mistake.

Someone may perform an emergency change and forget to update the code.

This artifact is about detecting, understanding, and recovering from those situations.

What This Project Demonstrates

This project demonstrates:

Terraform remote state
baseline GCP infrastructure creation
manual drift simulation
terraform plan drift detection
terraform plan -detailed-exitcode
terraform plan -refresh-only
terraform state list
terraform state show
terraform state pull
terraform state rm
terraform import
importing manually created GCP resources
recovering after state removal
scheduled drift detection with GitHub Actions
GitHub issue creation when drift is detected
Workload Identity Federation
no service account JSON key

The lab intentionally uses simple Google Cloud resources:

VPC
subnet
firewall rule
service account

That is deliberate.

The objective is not infrastructure complexity.

The objective is Terraform behavior.

Why I Created a Separate Repository

I created this as a separate repository instead of adding it into my production-lite web platform repo.

Reason:

This lab intentionally creates abnormal infrastructure situations.

It includes:

manual changes outside Terraform
state removal
resource import
drift simulation
drift detection
recovery scenarios

Those activities should not be mixed into a main application platform repository.

This project is a controlled failure-mode lab.

Repository Structure

The repository is structured like this:

terraform-gcp-drift-import-recovery/
├── README.md
├── .gitignore
├── versions.tf
├── providers.tf
├── backend.tf.example
├── main.tf
├── variables.tf
├── outputs.tf
├── terraform.tfvars.example
├── locals.tf
├── environments/
│   └── dev.tfvars
├── imports/
│   ├── imported-network.tf.example
│   └── imported-firewall.tf.example
├── docs/
│   ├── architecture.md
│   ├── drift-detection-lab.md
│   ├── import-lab.md
│   ├── state-recovery-lab.md
│   ├── scheduled-drift-detection.md
│   ├── operations-runbook.md
│   ├── verification.md
│   ├── design-decisions.md
│   └── release-process.md
├── scripts/
│   ├── simulate-drift.sh
│   ├── create-manual-import-resources.sh
│   ├── cleanup-manual-import-resources.sh
│   └── bootstrap-wif-github.sh
└── .github/
    ├── workflows/
    │   ├── terraform-plan.yml
    │   └── drift-detection.yml
    └── ISSUE_TEMPLATE/
        └── drift_report.md

The structure separates:

baseline Terraform code
manual drift scripts
import examples
state recovery documentation
scheduled drift detection workflow
GitHub issue template

Baseline Infrastructure

The baseline infrastructure is intentionally small.

It creates:

custom VPC
subnet
firewall rule
service account

The firewall rule is the main drift target.

Why?

Because firewall rules are easy to modify manually and easy for Terraform to detect.

For example, Terraform may define:

allowed port: tcp:80

Then someone manually changes it to:

allowed ports: tcp:80,tcp:8080

That difference is drift.

Remote State Design

This project uses a GCS backend for Terraform state.

I added two GitHub repository variables for the state configuration:

TF_STATE_BUCKET = terraform-gcp-production-lite-tfstate
TF_STATE_PREFIX = terraform-gcp-drift-import-recovery/dev

Instead of committing a real backend.tf, the GitHub Actions workflow writes the backend config dynamically.

The workflow step looks like this:

- name: Write Terraform backend config
  shell: bash
  env:
    TF_STATE_BUCKET: ${{ vars.TF_STATE_BUCKET }}
    TF_STATE_PREFIX: ${{ vars.TF_STATE_PREFIX }}
  run: |
    set -euo pipefail

    if [[ -z "${TF_STATE_BUCKET}" ]]; then
      echo "TF_STATE_BUCKET repository variable is required." >&2
      exit 1
    fi

    if [[ -z "${TF_STATE_PREFIX}" ]]; then
      echo "TF_STATE_PREFIX repository variable is required." >&2
      exit 1
    fi

    cat > backend.tf <<EOF
    terraform {
      backend "gcs" {
        bucket = "${TF_STATE_BUCKET}"
        prefix = "${TF_STATE_PREFIX}"
      }
    }
    EOF

This keeps the backend configuration flexible across environments.

It also avoids hardcoding my state bucket and prefix directly in the workflow logic.

Lab 1 — Simulating Drift

The first lab simulates drift manually.

After deploying the baseline infrastructure, I modify the firewall rule outside Terraform.

Example:

export FIREWALL_RULE_NAME="$(terraform output -raw firewall_rule_name)"

gcloud compute firewall-rules update "${FIREWALL_RULE_NAME}" \
  --allow=tcp:80,tcp:8080

At this point:

Terraform code says: tcp:80
Google Cloud says: tcp:80,tcp:8080

That is drift.

Terraform code, Terraform state, and real infrastructure are no longer aligned.

Lab 2 — Detecting Drift with Terraform Plan

After simulating drift, I run:

terraform plan -var-file=environments/dev.tfvars

Terraform detects that the real firewall rule no longer matches the desired configuration.

The plan proposes to restore the firewall rule back to the Terraform-defined state.

That is the simplest drift detection mechanism:

Run terraform plan.
If Terraform proposes unexpected changes, investigate.

Lab 3 — Using `-detailed-exitcode`

For automation, I used:

terraform plan \
  -input=false \
  -no-color \
  -detailed-exitcode \
  -var-file=environments/dev.tfvars \
  -out=tfplan

The important behavior:

exit code 0 = no changes
exit code 1 = error
exit code 2 = changes detected

This is useful because a CI/CD workflow can use the exit code to determine whether drift exists.

In this artifact:

0 means no drift
2 means drift detected
1 means Terraform error

Lab 4 — Refresh-Only Planning

I also documented refresh-only planning:

terraform plan \
  -var-file=environments/dev.tfvars \
  -refresh-only

This is useful when I want to inspect how real infrastructure differs from Terraform state.

Normal plan answers:

What would Terraform change to make infrastructure match the code?

Refresh-only plan answers:

What has changed in real infrastructure compared to Terraform state?

Both are useful, but they answer different operational questions.

Lab 5 — Recovering from Drift

If the manual change was not approved, the recovery is simple:

terraform apply -var-file=environments/dev.tfvars

Terraform restores the resource to the desired configuration.

In this case, it removes the manually added port 8080.

Then I can confirm that the environment is clean:

terraform plan \
  -var-file=environments/dev.tfvars \
  -detailed-exitcode

Expected result:

exit code 0

That means Terraform sees no pending changes.

Lab 6 — Importing Existing Infrastructure

The next scenario is different.

Instead of changing an existing Terraform-managed resource, I create a resource manually outside Terraform.

Example:

gcloud compute networks create manual-import-network \
  --project="${PROJECT_ID}" \
  --subnet-mode=custom

This VPC exists in Google Cloud, but Terraform does not know about it.

To bring it under Terraform management, I need two things:

Terraform resource configuration
terraform import

Example Terraform configuration:

resource "google_compute_network" "imported_network" {
  name                    = "manual-import-network"
  auto_create_subnetworks = false
  routing_mode            = "REGIONAL"
}

Then import:

terraform import \
  -var-file=environments/dev.tfvars \
  google_compute_network.imported_network \
  "projects/${PROJECT_ID}/global/networks/manual-import-network"

After import:

terraform state list
terraform state show google_compute_network.imported_network
terraform plan -var-file=environments/dev.tfvars

The objective is to reach:

No changes.

That means the Terraform configuration and imported real resource are aligned.

Lab 7 — State Inspection

Terraform state is the mapping between Terraform resource addresses and real infrastructure objects.

Useful commands:

terraform state list

terraform state show google_compute_firewall.allow_http_internal

terraform state pull > state-backups/before-recovery.json

I included state inspection because drift and import are hard to understand without understanding state.

Terraform state answers:

Which real resource is this Terraform resource address connected to?

Lab 8 — State Recovery After Accidental State Removal

This lab simulates a state mistake.

First, I back up state:

mkdir -p state-backups

terraform state pull > state-backups/before-state-rm.json

Then I remove a resource from state:

terraform state rm google_compute_firewall.allow_http_internal

Important:

This does not delete the real firewall rule.
It only removes the mapping from Terraform state.

Now Terraform no longer knows that the real firewall rule belongs to the configuration.

If I run:

terraform plan -var-file=environments/dev.tfvars

Terraform may try to create the firewall rule again.

But the resource already exists in Google Cloud.

The correct recovery is to import it back:

terraform import \
  -var-file=environments/dev.tfvars \
  google_compute_firewall.allow_http_internal \
  "projects/${PROJECT_ID}/global/firewalls/${FIREWALL_RULE_NAME}"

Then verify:

terraform state list
terraform plan -var-file=environments/dev.tfvars

The target result:

No changes.

Lab 9 — Scheduled Drift Detection with GitHub Actions

The final part of this artifact is scheduled drift detection.

The workflow runs:

workflow_dispatch
schedule: every day at 23:00 UTC

The workflow performs:

checkout repository
set up Terraform
authenticate to Google Cloud using WIF
write backend.tf from repository variables
terraform init
terraform validate
terraform plan -detailed-exitcode
upload drift plan artifact
create GitHub issue if drift is detected

The key step:

terraform plan \
  -input=false \
  -no-color \
  -detailed-exitcode \
  -var-file=environments/dev.tfvars \
  -out=tfplan > drift-plan.txt

Then the workflow evaluates the exit code:

if [[ "${EXIT_CODE}" -eq 0 ]]; then
  echo "No drift detected."
  exit 0
elif [[ "${EXIT_CODE}" -eq 2 ]]; then
  echo "Drift detected."
  exit 0
else
  echo "Terraform plan failed."
  exit 1
fi

This is intentional.

If drift is detected, the workflow does not fail as a broken pipeline.

It creates a GitHub issue.

Why?

Because drift is not always a technical failure.

Sometimes drift is an intentional emergency change that needs to be reconciled.

The workflow should create visibility, not immediately destroy or revert something.

GitHub Issue Creation When Drift Is Detected

When Terraform returns exit code 2, the workflow creates a GitHub issue:

gh issue create \
  --title "${ISSUE_TITLE}" \
  --body-file drift-issue-body.md \
  --label "drift,terraform,incident"

The issue tells the operator to:

download the drift plan artifact
review whether the drift was intentional or accidental
revert accidental drift with Terraform apply
update Terraform code if the change was intentional
close the issue only after plan returns exit code 0

This turns drift detection into an operational workflow.

Not just a command.

Authentication with Workload Identity Federation

Like my previous Terraform CI/CD artifact, this project does not use a service account JSON key.

GitHub Actions authenticates to Google Cloud using Workload Identity Federation.

The flow is:

GitHub Actions OIDC token
  -> Google Workload Identity Provider
  -> Terraform drift CI/CD service account
  -> Google Cloud APIs

This keeps the workflow keyless.

No long-lived Google Cloud service account key is stored in GitHub.

Why I Do Not Auto-Apply Drift Fixes

It may be tempting to do this:

detect drift
automatically run terraform apply

I intentionally did not do that.

Reason:

Not all drift is accidental.

Some drift may come from:

emergency production fix
approved console change
another migration process
temporary incident workaround

The right first response is:

detect
notify
review
decide
then reconcile

Automatic remediation can be dangerous if the workflow does not understand why the drift happened.

So this artifact creates a GitHub issue instead.

What This Artifact Taught Me

The biggest lesson:

Terraform is not only a provisioning tool.
Terraform is also a control system.

What I Would Do Differently in Production

For a production environment, I would improve this further with:

least-privilege custom IAM role
Slack or email notification
deduplication of drift issues
severity classification
separate environments
policy-as-code checks
cost impact review
state backup automation
manual approval before remediation

But for this artifact, the core objective is complete:

simulate drift
detect drift
understand state
recover state
import resources
automate drift visibility

Terraform CI/CD with Google Cloud: Plan on Pull Request and Apply with Approval

Abraham Naiborhu — Sun, 24 May 2026 10:59:40 +0000

Simple Terraform codes on laptop is alright for learning. But, at some point, things gotten more complex and infrastructure changes need a more controlled workflow.

For my second Terraform x Google Cloud portfolio artifact, I had already built a production like web platform with:

VPC
app and DB subnets
Cloud NAT
private backend VMs
regional Managed Instance Group
HTTP/HTTPS Load Balancer
Cloud Armor security policy
remote Terraform state
modular Terraform structure

In this version, I added the next operational layer:

Terraform CI/CD

The goal was simple:

Pull Request -> Terraform Plan
Manual Approval -> Terraform Apply
No service account JSON key

This became:

v2.0 — Terraform CI/CD with GitHub Actions and Workload Identity Federation

Checkout my github! terraform-gcp-production-lite-web-platform

Why I Built This

Before this version, the workflow was still done locally:

local terminal
  -> terraform fmt
  -> terraform validate
  -> terraform plan
  -> terraform apply

That works for my learning, But i understand that in a team setting this way of doing things locally is not sustainable.

Thus, making me questions:

Can the change be reviewed before apply?
Can the Terraform plan run automatically on pull request?
Can apply require approval?
Can GitHub Actions authenticate to Google Cloud without a static key?
Can the workflow use remote state safely?

v2.0 was built to answer those questions.

What v2.0 Adds

This release adds:

GitHub Actions
Terraform plan on pull request
Terraform apply through manual workflow
GitHub environment approval before apply
Workload Identity Federation
Google service account impersonation
No service account JSON key
Remote state access from CI/CD
GitHub CLI-based release workflow

The important part is not just automation.

The important part is change control.

Final CI/CD Flow

The new workflow looks like this:

Pull Request
  -> terraform fmt -check
  -> terraform init
  -> terraform validate
  -> terraform plan
  -> upload plan artifact
  -> comment plan summary on PR

Manual Apply
  -> workflow_dispatch
  -> confirm input: APPLY
  -> GitHub environment approval
  -> terraform plan -out=tfplan
  -> terraform apply tfplan

This separates review from execution.

The PR workflow answers:

What will Terraform change?

The apply workflow answers:

Are we approved to apply this change?

Authentication Design

The most important security decision in this version:

No service account JSON key.

Instead of storing a long-lived Google Cloud key in GitHub Secrets, the workflow uses Workload Identity Federation.

The authentication flow is:

GitHub Actions OIDC token
  -> Google Workload Identity Provider
  -> Terraform CI/CD service account impersonation
  -> Google Cloud APIs

The GitHub repository is restricted through the Workload Identity Provider attribute condition:

assertion.repository == "abrahamparn/terraform-gcp-production-lite-web-platform"

That means the provider is only intended to trust this specific repository.

Why Workload Identity Federation Matters

A service account JSON key is a long-lived credential.

If it leaks, the impact can be serious.

Workload Identity Federation avoids that by allowing GitHub Actions to exchange its OIDC identity for short-lived Google Cloud access.

For this project, GitHub Actions impersonates a dedicated service account:

terraform-cicd@PROJECT_ID.iam.gserviceaccount.com

This gives the CI/CD pipeline a clear operational identity.

Workflow 1 — Terraform Plan on Pull Request

The first workflow runs on pull requests to main.

File:

.github/workflows/terraform-plan.yml

The workflow performs:

checkout repository
set up Terraform
authenticate to Google Cloud using WIF
set up gcloud
terraform fmt -check -recursive
terraform init
terraform validate
terraform plan
generate plain-text plan
upload plan artifact
comment plan summary on PR

In the screenshot, the Terraform Plan workflow successfully completed all steps:

Checkout repository
Set up Terraform
Authenticate to Google Cloud
Set up gcloud
Terraform format check
Terraform init
Terraform validate
Terraform plan
Generate plain-text plan
Upload Terraform plan artifact
Comment plan summary on PR

This is the main review workflow.

It allows infrastructure changes to be reviewed before they are applied.

Workflow 2 — Terraform Apply with Manual Approval

The second workflow is manually triggered.

File:

.github/workflows/terraform-apply.yml

The workflow uses:

workflow_dispatch
confirm_apply input
GitHub environment: terraform-apply
manual approval
terraform plan before apply
terraform apply using saved plan file

The apply workflow has two jobs:

Terraform Plan Before Apply
Terraform Apply

In the screenshot, the apply workflow succeeded after environment approval.

The deployment protection section shows:

Environment: terraform-apply
Approval: approved
Comment: go on

That approval gate is the main safety control before applying infrastructure changes.

Why I Still Run Plan Before Apply

One question I had while building this was:

Should the apply workflow reuse the PR plan artifact?

For this version, I decided not to.

Instead, the apply workflow creates a fresh plan immediately before apply.

Why?

Because PR plan artifacts can become stale.

Between PR review and manual apply:

state may change
main branch may change
plan artifact may expire
another workflow may run

So the safer v2.0 pattern is:

PR plan = review signal
Apply workflow plan = final execution plan

Then the apply step uses:

terraform apply tfplan

This keeps apply tied to the plan generated inside the apply workflow.

GitHub Environment Approval

The apply workflow uses this environment:

terraform-apply

This allows GitHub deployment protection rules to act as the approval gate.

The result is:

No automatic apply from pull request.
No apply just because code was pushed.
Apply only happens after manual workflow trigger and approval.

Repository Variables

I used GitHub repository variables for non-secret configuration:

GCP_PROJECT_ID
GCP_PROJECT_NUMBER
GCP_REGION
GCP_WORKLOAD_IDENTITY_PROVIDER
GCP_SERVICE_ACCOUNT
TF_WORKING_DIR
TF_VERSION

These values are not service account keys.

No Google Cloud JSON key is stored in GitHub.

Environment tfvars Strategy

One practical issue with Terraform CI/CD is variable management.

My project uses a lot of variables such as:

subnets
firewall_rules
service_accounts
Cloud Armor rules
managed SSL certificate domains

Passing all of that through TF_VAR_* environment variables would become messy.

So for this portfolio project, I used:

environments/dev.tfvars

This file contains non-sensitive environment configuration.

The workflow runs:

terraform plan -var-file=environments/dev.tfvars

and:

terraform plan -var-file=environments/dev.tfvars -out=tfplan

Important rule:

Only non-sensitive values should be committed.

Secrets should not be placed in dev.tfvars.

GitHub CLI Operations

I also tried to minimize GitHub UI usage.

For example, releases can be created using:

gh release create v2.0.0 \
  --title "v2.0.0 — Terraform CI/CD with GitHub Actions and WIF" \
  --notes "This release adds Terraform plan on pull request, manual approval before apply, and no key Google Cloud authentication through WIF."

The pull request can also be created using CLI:

gh pr create \
  --base main \
  --head feature/v2.0-terraform-cicd-wif \
  --title "add Terraform CI/CD with GitHub Actions and WIF" \
  --body "This PR introduces Terraform CI/CD with GitHub Actions, plan on pull request, manual approval before apply, and Workload Identity Federation with no SA JSON key."

And the manual apply workflow can be triggered with:

gh workflow run "Terraform Apply" \
  -f confirm_apply=APPLY \
  -f git_ref=main

The only part where UI is still useful is the environment approval step, because that is the point of having a manual deployment gate.

Evidence From the Workflow Runs

For this version, I captured two main screenshots.

Terraform Plan Workflow

The Terraform Plan workflow succeeded on pull request.

It completed:

authentication to Google Cloud
terraform fmt check
terraform init
terraform validate
terraform plan
plan artifact upload
PR plan comment

This proves the review workflow works.

Terraform Apply Workflow

The Terraform Apply workflow also succeeded.

It was manually triggered from main, required environment approval, then executed:

Terraform Plan Before Apply
Terraform Apply

The deployment protection section shows that the terraform-apply environment was approved before apply continued.

This proves the execution workflow works.

One Warning I Noticed

The workflow showed a warning related to Node.js 20 actions being deprecated.

This did not break the workflow.

The run still succeeded.

What This Version Does Not Solve Yet

v2.0 is intentionally focused.

It does not yet include:

policy-as-code
cost estimation
drift detection automation
custom least-privilege Terraform IAM role
multi-environment promotion
automatic rollback
scheduled plan

Those are future improvements.

For this version, the objective was:

reviewable plan
manual approved apply
keyless authentication

Final Architecture After v2.0

The infrastructure platform now has two layers:

Runtime platform

HTTPS Load Balancer
Cloud Armor
Backend Service
Regional MIG
Private backend VMs
Cloud NAT

Delivery platform

GitHub Pull Request
Terraform Plan workflow
GitHub Environment Approval
Terraform Apply workflow
Workload Identity Federation
No service account JSON key

That is the main improvement.

The project moved from:

I can provision infrastructure.

to:

I can manage infrastructure changes through a controlled delivery workflow.

Version Timeline

v1.0 — Production-Lite HTTP Platform
v1.1 — HTTPS and Custom Domain
v1.2 — Security Hardening with Cloud Armor
v2.0 — Terraform CI/CD with GitHub Actions and WIF

Next, I may continue with:

v2.1 — Drift Detection and Recovery

Because after CI/CD, the next important Terraform question is:

What happens when someone changes infrastructure outside Terraform?

Terraforming a Production-Lite GCP Web Platform: MIG, Cloud NAT, Load Balancer, and Private Backends

Abraham Naiborhu — Wed, 20 May 2026 06:18:00 +0000

Hi! After building my first Terraform artifact, The GCP Foundation Lite, I wanted to move one layer higher.

I wanted to answer a more complex question:

Can I provision infrastructure for an actual web platform?

Thus, I created this project titled "Production-Lite GCP Web Platform" using Terraform.

This project provisions:

custom VPC network
app subnet
reserved database subnet
map-based firewall rules
Cloud NAT
custom service account
regional Managed Instance Group
instance template
startup script
HTTP health check
backend service
external HTTP load balancer
remote Terraform state
reusable Terraform modules

The goal was not to create a full enterprise platform, but to create a small but production-shaped infra pattern that can run an application.

But, before i go even further, do check my github repository at terraform-gcp-production-lite-web-platform

Why I Built This

In my first artifact, I focused on the foundation layer.

That project included:

remote Terraform state
versioned GCS state bucket
custom VPC
role-based subnets
firewall rules
service accounts
IAM bindings
reusable modules

That was useful because it helped me understand how to create the base layer of a Google Cloud environment.

But a foundation alone does not run an application.

So for this second artifact, I wanted to build something closer to a real web platform.

The objective was to move from this:

Terraform creates the foundation.

To this:

Terraform provisions infrastructure that can serve application traffic.

What This Project Builds

This project creates:

custom VPC network
application subnet
reserved database subnet
firewall rules
Cloud Router
Cloud NAT
custom application service account
instance template
regional Managed Instance Group
HTTP health check
backend service
external HTTP load balancer
global forwarding rule
startup script
simple web application endpoint
remote state in GCS

The application VMs are private.

They do not have external IP addresses.

Users access the application through the external HTTP load balancer.

Outbound internet access from the private VMs is handled through Cloud NAT.

High-Level Architecture

The high-level architecture is:

User
  ↓
External HTTP Load Balancer
  ↓
Backend Service
  ↓
Regional Managed Instance Group
  ↓
Private Application VM
  ↓
Application Endpoint

For outbound access:

Private Application VM
  ↓
Cloud NAT
  ↓
Internet

The important point is this:

Inbound traffic enters through the load balancer.
Outbound traffic leaves through Cloud NAT.
The backend VM does not need a public IP address.

Architecture Diagram

User / Browser
      |
      v
External HTTP Load Balancer
      |
      v
Target HTTP Proxy
      |
      v
URL Map
      |
      v
Backend Service
      |
      v
Regional Managed Instance Group
      |
      v
Private App VM(s)
      |
      v
Application running from startup script

Private App VM(s)
      |
      v
Cloud NAT
      |
      v
Outbound Internet

What Production-Lite Means

For this project, production-lite means the infrastructure follows production-style patterns without trying to become a full enterprise platform.

This project includes:

private backend instances
load balancer entry point
health checks
Managed Instance Group
Cloud NAT
service account separation
firewall rules
remote state
Terraform modules

But this version does not include:

HTTPS
custom domain
Cloud Armor
Cloud SQL
Secret Manager
CI/CD
multi-region deployment
blue-green deployment
Kubernetes

Those features are important, but I intentionally deferred them.

The goal of v1.0 is to keep the scope focused:

Can I provision a production-shaped HTTP web platform with private backends?

Why Private Backend Instances Matter

One of the most important design choices in this project is that the backend VMs do not have external IP addresses.

In the instance template, the network interface does not include an access_config block.

Conceptually, the pattern is:

network_interface {
  subnetwork = var.subnetwork_self_link

  # No access_config block.
  # This intentionally creates VMs without external IP addresses.
}

This means the VM is not directly exposed to the internet.

Instead, application traffic must go through the load balancer.

That is a better pattern than exposing a VM directly with a public IP address.

A direct public VM might be fine for a quick test, but for an application platform, I want a cleaner entry point:

Internet
  -> Load Balancer
  -> Backend Service
  -> Private VM

Why Cloud NAT Is Needed

Because the backend VMs are private, they do not have direct outbound internet access through an external IP.

However, the VM still needs outbound access for operational tasks such as:

running apt-get update
installing packages
downloading dependencies
calling external services
bootstrapping the application during startup

This is where Cloud NAT is useful.

Cloud NAT allows private resources to initiate outbound internet connections without assigning public IP addresses to those resources.

In this project, Cloud NAT is created using:

Cloud Router
Cloud NAT gateway
selected subnet configuration

The important improvement from my earlier lab is that I do not need to NAT every subnet.

For this artifact, the app subnet receives NAT.

The reserved database subnet does not receive NAT by default.

This is the intended posture:

app subnet -> Cloud NAT enabled
db subnet  -> Cloud NAT not enabled by default

That separation is small, but architecturally meaningful.

Why I Used a Managed Instance Group

A standalone VM is simpler.

But a standalone VM does not really show platform thinking.

For this artifact, I used a regional Managed Instance Group.

The MIG uses:

instance template
target size
named port
autohealing policy
health check

The difference is important.

A standalone VM says:

I created a server.

A Managed Instance Group says:

I defined how application instances should be created, managed, replaced, and checked.

That is a stronger infrastructure pattern.

Why I Used an External HTTP Load Balancer

The external HTTP load balancer acts as the public entry point.

The load balancer connects to the backend service, and the backend service connects to the Managed Instance Group.

The request flow is:

User
  -> Global forwarding rule
  -> Target HTTP proxy
  -> URL map
  -> Backend service
  -> Managed Instance Group
  -> Application VM

This is more realistic than opening port 80 directly on a public VM.

It also allows me to test important infrastructure concepts:

backend services
health checks
named ports
firewall rules for health check probes
load-balanced application access

Why Health Checks Matter

The load balancer needs to know whether the backend instances are healthy.

For that, I use an HTTP health check.

The application exposes:

GET /
GET /healthz
GET /metadata

The /healthz endpoint is used by the health check.

This is better than using / as the health check path because / is usually a user-facing route, while /healthz is explicitly meant for machine health checking.

The expected response is simple:

ok

A simple health endpoint is enough for this version.

The goal is not to build a complex application.

The goal is to prove that the infrastructure can route traffic to a healthy backend.

Application Endpoints

The sample application exposes three endpoints.

Endpoint	Purpose
`/`	Root endpoint
`/healthz`	Health check endpoint
`/metadata`	Instance information endpoint

The root endpoint returns:

Hi from Terraform GCP Production-Lite Platform

The health endpoint returns:

ok

The metadata endpoint returns information such as:

{
  "service": "terraform-gcp-production-lite-web-platform",
  "environment": "dev",
  "version": "1.0.0",
  "hostname": "dev-web-mig-xxxx"
}

The application is intentionally small.

Terraform and infrastructure design are the focus.

Repository Structure

The repository structure is:

terraform-gcp-production-lite-web-platform/
├── README.md
├── .gitignore
├── versions.tf
├── providers.tf
├── backend.tf.example
├── main.tf
├── variables.tf
├── outputs.tf
├── terraform.tfvars.example
├── locals.tf
├── docs/
│   ├── architecture.md
│   ├── deployment-runbook.md
│   ├── operations-runbook.md
│   ├── verification.md
│   ├── design-decisions.md
│   └── version-roadmap.md
├── scripts/
│   └── startup.sh
└── modules/
    ├── network/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    ├── iam/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    ├── nat/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    ├── compute/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    └── load-balancer/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

There are five main modules:

network
iam
nat
compute
load-balancer

Each module has a specific responsibility.

Module Responsibilities

Module	Responsibility
`network`	VPC, subnets, firewall rules
`iam`	Service accounts and IAM role bindings
`nat`	Cloud Router and Cloud NAT
`compute`	Instance template and Managed Instance Group
`load-balancer`	HTTP load balancer resources

The root module connects them together.

The root module should answer:

What components make up this platform?
How are those components connected?

The child modules should answer:

How is each infrastructure area implemented?

This separation makes the repository easier to read.

Root Module Composition

The root main.tf composes the platform.

At a high level, the order is:

network
iam
nat
health check
compute
load balancer
IAP IAM bindings

This order makes sense because:

Compute needs network and IAM.
NAT needs network.
The load balancer needs the instance group.
IAP access needs IAM and firewall rules.

The root module should not contain all low-level resources.

It should orchestrate modules.

Network Module

The network module creates:

VPC
subnets
firewall rules

The VPC is created as a custom mode VPC:

resource "google_compute_network" "this" {
  name                    = local.final_network_name
  auto_create_subnetworks = false
  routing_mode            = "REGIONAL"
}

I use:

auto_create_subnetworks = false

because I want explicit control over subnet ranges.

This is cleaner than relying on automatically created subnets.

Map-Based Subnets

Instead of hardcoding each subnet as a separate resource, I define subnets as a map.

Example:

subnets = {
  app = {
    cidr_range            = "10.80.1.0/24"
    private_google_access = true
    role                  = "application"
  }

  db = {
    cidr_range            = "10.80.2.0/24"
    private_google_access = true
    role                  = "database-reserved"
  }
}

The network module then creates subnets using for_each.

Conceptually:

resource "google_compute_subnetwork" "subnets" {
  for_each = var.subnets

  name                     = "${var.environment}-${each.key}-subnet"
  region                   = coalesce(each.value.region, var.region)
  network                  = google_compute_network.this.id
  ip_cidr_range            = each.value.cidr_range
  private_ip_google_access = each.value.private_google_access
}

This is more flexible than writing:

resource "google_compute_subnetwork" "app" {
  ...
}

resource "google_compute_subnetwork" "db" {
  ...
}

If I want to add another subnet later, I can add another map entry.

For example:

cache = {
  cidr_range = "10.80.3.0/24"
  role       = "cache"
}

The module does not need to change.

Map-Based Firewall Rules

The network module also creates firewall rules from a map.

Example:

firewall_rules = {
  allow-lb-health-check = {
    description   = "Allow Google Cloud load balancer health checks and proxy traffic."
    source_ranges = ["35.191.0.0/16", "130.211.0.0/22"]
    target_tags   = ["web-backend"]

    allow = [
      {
        protocol = "tcp"
        ports    = ["80"]
      }
    ]
  }

  allow-iap-ssh = {
    description   = "Allow SSH to private backend instances through IAP."
    source_ranges = ["35.235.240.0/20"]
    target_tags   = ["web-backend"]

    allow = [
      {
        protocol = "tcp"
        ports    = ["22"]
      }
    ]
  }
}

The module creates firewall rules using for_each and dynamic allow blocks.

Conceptually:

resource "google_compute_firewall" "ingress_rules" {
  for_each = var.firewall_rules

  name          = "${var.environment}-${each.key}"
  network       = google_compute_network.this.name
  description   = each.value.description
  direction     = "INGRESS"
  source_ranges = each.value.source_ranges
  target_tags   = each.value.target_tags

  dynamic "allow" {
    for_each = each.value.allow

    content {
      protocol = allow.value.protocol
      ports    = allow.value.ports
    }
  }
}

I prefer this pattern because traffic policy becomes data-driven.

The module does not need to know every possible firewall rule.

It only needs to know how to create firewall rules from structured input.

Firewall Rules Used

For this version, I use three main firewall rules:

Rule	Purpose
`allow-lb-health-check`	Allows Google load balancer and health check traffic to backend VMs
`allow-iap-ssh`	Allows SSH through IAP TCP forwarding
`allow-internal`	Allows internal traffic inside the platform CIDR

The important security decision is that I do not open SSH to:

0.0.0.0/0

Instead, SSH access is designed around IAP.

IAM Module

The IAM module creates service accounts.

For this artifact, the main service account is the application VM service account.

Example input:

service_accounts = {
  app = {
    account_id    = "dev-prod-lite-app-sa"
    display_name  = "Production Lite App Service Account"
    description   = "Service account used by private application VM instances."
    project_roles = [
      "roles/logging.logWriter",
      "roles/monitoring.metricWriter"
    ]
  }
}

The service account is attached to the application instances.

This is cleaner than using the default Compute Engine service account.

It also makes the identity of the workload explicit.

NAT Module

The NAT module creates:

Cloud Router
Cloud NAT

In my earlier lab, Cloud NAT was applied to all subnets.

For this artifact, I wanted a more intentional design.

So NAT is applied only to selected subnet keys.

Example:

nat_subnet_keys = ["app"]

That means:

app subnet gets outbound internet through Cloud NAT
db subnet does not get NAT by default

This is a small design improvement, but it shows better network intent.

The app tier needs outbound access for package installation and application operations.

The reserved database tier should be more restricted.

Compute Module

The compute module creates:

instance template
regional Managed Instance Group
named port
autohealing policy

The instance template defines:

machine type
boot disk
network interface
startup script
service account
network tags

The important part is the network interface.

network_interface {
  subnetwork = var.subnetwork_self_link

  # No access_config block.
}

This keeps the VM private.

The MIG then uses the instance template:

resource "google_compute_region_instance_group_manager" "this" {
  name               = "${var.environment}-${var.mig_name}"
  region             = var.region
  base_instance_name = "${var.environment}-${var.mig_name}"
  target_size        = var.target_size

  version {
    instance_template = google_compute_instance_template.this.self_link
  }

  named_port {
    name = "http"
    port = var.app_port
  }

  auto_healing_policies {
    health_check      = var.health_check_self_link
    initial_delay_sec = 120
  }
}

The named port is important because the backend service uses it to send traffic to the correct backend port.

Load Balancer Module

The load balancer module creates:

global IP address
backend service
URL map
target HTTP proxy
global forwarding rule

The backend service connects the load balancer to the MIG.

Conceptually:

resource "google_compute_backend_service" "this" {
  name                  = "${var.environment}-${var.lb_name}-backend"
  protocol              = "HTTP"
  port_name             = "http"
  load_balancing_scheme = "EXTERNAL_MANAGED"
  timeout_sec           = 30

  health_checks = [
    var.health_check_self_link
  ]

  backend {
    group           = var.backend_instance_group
    balancing_mode  = "UTILIZATION"
    capacity_scaler = 1.0
  }
}

The load balancer then exposes the service through a global forwarding rule.

For v1.0, I use HTTP on port 80.

HTTPS will come later in v1.1.

Startup Script

The startup script bootstraps the application when the VM starts.

The script installs dependencies, creates the application files, and starts the service.

A simplified version of the application behavior is:

GET /         -> returns a simple message
GET /healthz -> returns ok
GET /metadata -> returns hostname and version information

The important operational improvement is that the application should run as a systemd service.

That is better than running a background process with &.

With systemd, I can check:

sudo systemctl status prod-lite-app

And view logs:

sudo journalctl -u prod-lite-app --no-pager -n 50

Remote State

Like the first artifact, this project uses a GCS backend for Terraform state.

Example backend:

terraform {
  backend "gcs" {
    bucket = "YOUR_TERRAFORM_STATE_BUCKET"
    prefix = "terraform-gcp-production-lite-web-platform/v1"
  }
}

The state path becomes something like:

gs://YOUR_TERRAFORM_STATE_BUCKET/terraform-gcp-production-lite-web-platform/v1/default.tfstate

Using remote state is important because this project is no longer a tiny one-file local experiment.

It has multiple modules and multiple cloud resources.

Remote state gives the project a more realistic workflow.

Git Safety

I do not commit real .tfvars files.

The repository includes:

terraform.tfvars.example

But ignores:

terraform.tfvars

The .gitignore includes:

.terraform/
*.tfstate
*.tfstate.*
*.tfvars
*.tfplan
crash.log
.DS_Store

This avoids committing local values, real project IDs, or state files.

Running the Project

The execution flow is:

1. Configure backend
2. Configure terraform.tfvars
3. Run terraform fmt
4. Run terraform init
5. Run terraform validate
6. Run terraform plan
7. Run terraform apply
8. Verify the load balancer and backend health

Configure Backend

cp backend.tf.example backend.tf

Then edit the bucket name.

Configure Variables

cp terraform.tfvars.example terraform.tfvars

Then edit:

project_id      = "your-gcp-project-id"
admin_principal = "user:your-email@example.com"

Run Terraform

terraform fmt -recursive
terraform init
terraform validate
terraform plan
terraform apply

Expected Output

After deployment, Terraform should output values such as:

network_name
subnets
firewall_rules
cloud_nat_name
cloud_router_name
health_check_name
mig_name
mig_instance_group
load_balancer_ip
load_balancer_url
curl_test_command
curl_health_check_command
platform_summary

The most important output is:

load_balancer_url

That URL is used to test the application.

Verification

After deployment, I can test the root endpoint:

curl -i http://LOAD_BALANCER_IP

Expected response:

Hi from Terraform GCP Production-Lite Platform

Test the health endpoint:

curl -i http://LOAD_BALANCER_IP/healthz

Expected response:

ok

Test the metadata endpoint:

curl -i http://LOAD_BALANCER_IP/metadata

Expected response:

{
  "service": "terraform-gcp-production-lite-web-platform",
  "environment": "dev",
  "version": "1.0.0",
  "hostname": "dev-web-mig-xxxx"
}

Verifying the Infrastructure

Verify the VPC:

gcloud compute networks list

Verify the subnets:

gcloud compute networks subnets list

Verify firewall rules:

gcloud compute firewall-rules list

Verify Cloud NAT:

gcloud compute routers nats list \
  --router=dev-nat-router \
  --region=asia-southeast2

Verify the Managed Instance Group:

gcloud compute instance-groups managed list

Verify backend health:

gcloud compute backend-services get-health BACKEND_SERVICE_NAME --global

Verify the application VM does not have an external IP:

gcloud compute instances list

This is one of the most important checks.

The application should be reachable through the load balancer, not directly through a public VM IP.

Accessing the Private VM Through IAP

Since the VM has no external IP, direct SSH is not available.

Instead, I use IAP TCP forwarding.

Example:

gcloud compute ssh INSTANCE_NAME \
  --zone=asia-southeast2-a \
  --tunnel-through-iap

This requires:

IAM permission for IAP tunnel access
OS Login role
firewall rule allowing IAP source range
correct target tag on the VM

The firewall source range for IAP TCP forwarding is:

35.235.240.0/20

This is better than opening SSH to the public internet.

Troubleshooting Notes

Load Balancer Returns 502

Possible causes:

application failed to start
health check path is wrong
firewall rule does not allow health check probes
target tag mismatch
named port mismatch
backend service points to the wrong instance group

Useful commands:

gcloud compute backend-services get-health BACKEND_SERVICE_NAME --global

sudo systemctl status prod-lite-app

sudo journalctl -u prod-lite-app --no-pager -n 100

VM Cannot Install Packages

Possible cause:

Cloud NAT is not configured correctly.

Useful check:

curl https://example.com

Run that from inside the VM.

IAP SSH Fails

Possible causes:

missing IAP role
missing OS Login role
missing service account user role
missing IAP firewall rule
wrong VM network tag

Check firewall rules:

gcloud compute firewall-rules list --filter="name~iap"

Important Design Decisions

1. Use private backend VMs

The backend application instances do not have external IP addresses.

This reduces direct exposure and forces traffic through the load balancer.

2. Use Cloud NAT

The private VMs still need outbound access.

Cloud NAT allows that without assigning public IPs to the VMs.

3. Use map-based subnet definitions

Subnets are defined through a map so the network module stays reusable.

Adding another subnet should not require another resource block.

4. Use map-based firewall rules

Firewall rules are also defined through a map.

This keeps ingress policy data-driven and easier to extend.

5. Use a Managed Instance Group

The application tier is managed as a group based on an instance template.

This is more production-shaped than a standalone VM.

6. Use HTTP only in v1.0

HTTPS is intentionally deferred to v1.1.

The v1.0 goal is to prove:

private backends
Cloud NAT
MIG
health checks
HTTP load balancing
firewall rules
remote state

7. Reserve a DB subnet without provisioning a database

The DB subnet demonstrates tiered network design.

A database is not provisioned in v1.0 because this artifact focuses on the web platform infrastructure.

What I Learned

This artifact helped me understand that application infrastructure is not only about creating a VM.

A proper platform needs several parts to work together:

networking
identity
firewall rules
NAT
compute lifecycle
health checks
load balancing
state management
documentation

The most interesting part for me was seeing how small configuration details affect the whole platform.

For example:

if the firewall source range is wrong, the load balancer cannot reach the backend
if the health check path is wrong, the backend becomes unhealthy
if Cloud NAT is missing, private VMs may fail during startup
if the MIG named port does not match the backend service, traffic may not route correctly
if SSH is opened to 0.0.0.0/0, the design becomes weaker

This project made me appreciate that infrastructure is a system.

Each component has to be designed with the others in mind.

What I Intentionally Did Not Add

I intentionally did not add HTTPS in this version.

I also did not add:

Cloud Armor
Cloud SQL
Secret Manager
CI/CD
custom domain
blue-green deployment
autoscaling policy
multi-region deployment

Those are useful, but I want this artifact to stay focused.

The purpose of v1.0 is to build the core web platform first.

Next Step

The next version will be:

v1.1 — HTTPS and Custom Domain

That version should add:

Google-managed SSL certificate
custom domain
HTTPS target proxy
global forwarding rule on port 443
optional HTTP-to-HTTPS redirect

After that, I want to continue with:

v1.2 — Security Hardening
v2.0 — Terraform CI/CD with GitHub Actions and Workload Identity Federation
v2.1 — Drift, Import, and State Recovery
v3.0 — Database and Secrets

References

Terraform GCS backend:
https://developer.hashicorp.com/terraform/language/backend/gcs

Google Cloud — Store Terraform state in Cloud Storage:
https://cloud.google.com/docs/terraform/resource-management/store-state

Google Cloud — External Application Load Balancer overview:
https://cloud.google.com/load-balancing/docs/https

Google Cloud — Terraform examples for external Application Load Balancers:
https://cloud.google.com/load-balancing/docs/https/ext-http-lb-tf-module-examples

Google Cloud — Cloud NAT overview:
https://cloud.google.com/nat/docs/overview

Google Cloud — IAP TCP forwarding:
https://cloud.google.com/iap/docs/using-tcp-forwarding

Building a GCP Terraform Foundation: VPC, IAM, and Remote State

Abraham Naiborhu — Fri, 15 May 2026 13:58:12 +0000

After going through several Terraform learning labs, I wanted to create my first Terraform artifact.

The goal was not to build a full production landing zone, but to build a clean GCP Terraform Foundation Lite project.

This project is meant to prove that I can bootstrap the basic foundation layer of a Google Cloud environment using Terraform.

It includes:

remote Terraform state
versioned GCS state bucket
custom VPC network
role-based public and private subnets
firewall rules
service accounts
IAM bindings
reusable modules
basic naming convention
GitHub-safe variable patterns

Why I Built This

In my earlier Terraform labs, I learned individual concepts:

installing Terraform
creating a VPC
using variables
using outputs
storing remote state in GCS
creating modules
creating service accounts
using Terraform with GitHub Actions

But those were learning labs. For this project, I wanted to convert those lessons into a cleaner artifact.

The objective was to create something that looks closer to a real Terraform repository. It's still simple, but structured enough to show a proper foundation pattern.

What This Project Builds

This project creates:

Google Cloud Storage bucket for Terraform state
object versioning for state recovery
custom VPC network
public-facing subnet
private workload subnet
IAP SSH firewall rule
internal traffic firewall rule
application service account
CI/CD service account
optional IAM bindings

The project is intentionally called Foundation Lite because it is not a full enterprise landing zone. It is a smaller version focused on the fundamentals.

Why Remote State Matters

By default, Terraform can store state locally in a file called:

terraform.tfstate

That is acceptable for early learning. However, from the labs I learn that local state is risky when the project becomes more serious.

If state only exists on my machine, then several problems appear:

What if the file is deleted?
What if another person needs to work on the infrastructure?
What if two people run Terraform at the same time?
What if I need to recover a previous state version?

For this project, I used Google Cloud Storage as the remote backend that stores Terraform state. Furthermore, I also enabled Object Versioning on the bucket because it gives me a recovery path if the state object is accidentally overwritten or deleted.

Reference:

https://developer.hashicorp.com/terraform/language/backend/gcs

https://cloud.google.com/storage/docs/samples/storage-bucket-tf-with-versioning

Why Bootstrap Is Separate

One important thing I learned is that the GCS bucket for Terraform state must exist before Terraform can use it as a backend.

That creates a bootstrapping problem:

Terraform needs a backend bucket.
But Terraform cannot use the backend bucket before it exists.

So I separated the project into two stages:

Stage	Folder	Purpose
Stage 1	`bootstrap/state-bucket`	Creates the GCS state bucket
Stage 2	`foundation`	Uses the GCS bucket as backend and creates the foundation resources

This separation makes the workflow clearer.

First, I bootstrap the state bucket.

Then I use that bucket to manage the foundation.

Repository Structure

The repository structure is:

terraform-gcp-foundation-lite/
├── README.md
├── .gitignore
├── docs/
│   └── architecture.md
├── bootstrap/
│   └── state-bucket/
│       ├── main.tf
│       ├── variables.tf
│       ├── outputs.tf
│       └── terraform.tfvars.example
├── foundation/
│   ├── backend.tf
│   ├── main.tf
│   ├── variables.tf
│   ├── outputs.tf
│   └── terraform.tfvars.example
└── modules/
    ├── network/
    │   ├── main.tf
    │   ├── variables.tf
    │   └── outputs.tf
    └── iam/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

There are two main folders:

bootstrap/
foundation/

And two reusable modules:

modules/network
modules/iam

Architecture

The high-level architecture is:

Bootstrap Terraform
  ↓
GCS State Bucket with Object Versioning
  ↓
Foundation Remote Backend
  ↓
Foundation Root Module
  ↓
Network Module + IAM Module

The network module creates the VPC, subnets, and firewall rules.

The IAM module creates service accounts and optional IAM role bindings.

Important Note About Public and Private Subnets in GCP

In Google Cloud, subnets are not inherently public or private in the same way as AWS.

A subnet becomes public-facing or private based on how workloads inside it are configured.

For example:

whether instances have external IPs
whether traffic enters through a load balancer
whether Cloud NAT exists
what firewall rules allow
how routing and exposure are designed

So in this project, I use public and private as role-based names.

They describe the intended function of each subnet.

They are not native GCP subnet types.

Stage 1: Bootstrap State Bucket

The first Terraform stage creates the GCS state bucket.

Folder:

bootstrap/state-bucket

The bucket resource looks like this:

resource "google_storage_bucket" "terraform_state" {
  name                        = var.state_bucket_name
  location                    = var.region
  uniform_bucket_level_access = true
  public_access_prevention    = "enforced"
  force_destroy               = false

  versioning {
    enabled = true
  }

  labels = {
    purpose     = "terraform-state"
    managed_by  = "terraform"
    environment = "bootstrap"
  }
}

There are several important settings here.

Uniform Bucket-Level Access

This keeps access management simpler by using IAM at the bucket level.

Public Access Prevention

This prevents the state bucket from accidentally becoming public.

Terraform state can contain sensitive infrastructure information, so the state bucket should never be publicly accessible.

Object Versioning

Object Versioning gives a recovery path if the Terraform state object is accidentally deleted or overwritten.

This is important because Terraform state is critical to Terraform-managed infrastructure.

Stage 2: Foundation Backend

After the bucket exists, the foundation stage can use it as a backend.

Folder:

foundation

Example backend:

terraform {
  backend "gcs" {
    bucket = "your-gcp-project-id-tfstate"
    prefix = "foundation"
  }
}

This stores the foundation state at:

gs://your-gcp-project-id-tfstate/foundation/default.tfstate

Network Module

The network module creates:

custom VPC
subnets
firewall rules

The module receives subnet definitions using a map.

Example:

subnets = {
  public = {
    cidr_range = "10.10.1.0/24"
    role       = "public-facing"
  }

  private = {
    cidr_range = "10.10.2.0/24"
    role       = "private-workload"
  }
}

The VPC is created as a custom mode VPC:

resource "google_compute_network" "vpc" {
  name                    = local.final_network_name
  auto_create_subnetworks = false
}

I use:

auto_create_subnetworks = false

because I want explicit control over the subnet ranges.

This is cleaner than relying on automatically created subnets.

Firewall Rules

The network module also creates firewall rules from a map.

Example:

firewall_rules = {
  allow-iap-ssh = {
    description   = "Allow SSH through IAP only."
    source_ranges = ["35.235.240.0/20"]
    target_tags   = ["iap-ssh"]

    allow = [
      {
        protocol = "tcp"
        ports    = ["22"]
      }
    ]
  }

  allow-internal = {
    description   = "Allow internal traffic inside the foundation CIDR range."
    source_ranges = ["10.10.0.0/16"]

    allow = [
      {
        protocol = "tcp"
        ports    = ["0-65535"]
      },
      {
        protocol = "udp"
        ports    = ["0-65535"]
      },
      {
        protocol = "icmp"
      }
    ]
  }
}

The IAP SSH rule is intentionally scoped to:

35.235.240.0/20

This is the source range used by IAP TCP forwarding.

I used this instead of opening SSH from:

0.0.0.0/0

That is a better security habit.

IAM Module

The IAM module creates service accounts.

Example input:

service_accounts = {
  app = {
    display_name = "Application Workload Service Account"
    description  = "Service account intended for application workloads."
    roles        = []
  }

  cicd = {
    display_name = "CI/CD Terraform Service Account"
    description  = "Service account intended for Terraform automation."
    roles        = []
  }
}

The module creates service accounts using for_each.

resource "google_service_account" "service_accounts" {
  for_each = var.service_accounts

  account_id   = "${var.environment}-${var.name_prefix}-${each.key}"
  display_name = each.value.display_name
  description  = each.value.description
}

This keeps identity creation separate from network creation.

That separation makes the repository easier to understand.

Naming Convention

The project uses a simple naming pattern:

environment-nameprefix-resource

Example:

dev-foundation-vpc
dev-foundation-public-subnet
dev-foundation-private-subnet
dev-foundation-app
dev-foundation-cicd

The goal is not to create the perfect naming standard.

The goal is to avoid random resource names.

Even a simple naming convention makes infrastructure easier to inspect later.

Git Safety

I do not commit real .tfvars files.

The repository includes:

terraform.tfvars.example

but ignores:

terraform.tfvars

The .gitignore includes:

.terraform/
*.tfstate
*.tfstate.*
*.tfvars
*.tfvars.json
!*.tfvars.example
*.tfplan
.DS_Store

This keeps local values and state files out of GitHub.

That is important because Terraform state and tfvars files can contain project-specific or sensitive information.

Running the Project

The execution order is:

1. Run bootstrap
2. Create the state bucket
3. Update foundation/backend.tf with the bucket name
4. Run foundation
5. Verify resources in GCP

Bootstrap

cd bootstrap/state-bucket
cp terraform.tfvars.example terraform.tfvars
terraform init
terraform fmt
terraform validate
terraform plan
terraform apply

Foundation

cd ../../foundation
cp terraform.tfvars.example terraform.tfvars
terraform init
terraform fmt -recursive
terraform validate
terraform plan
terraform apply

Expected Output

The foundation output should show a summary similar to:

foundation_summary = {
  environment      = "dev"
  network_name     = "dev-foundation-vpc"
  subnet_count     = 2
  firewall_count   = 2
  service_accounts = ["app", "cicd"]
}

This confirms that Terraform created:

one VPC
two subnets
two firewall rules
two service accounts

Verification

I can verify the VPC:

gcloud compute networks list \
  --filter="name=dev-foundation-vpc"

Verify subnets:

gcloud compute networks subnets list \
  --filter="network:dev-foundation-vpc"

Verify firewall rules:

gcloud compute firewall-rules list \
  --filter="network:dev-foundation-vpc"

Verify service accounts:

gcloud iam service-accounts list \
  --filter="email~dev-foundation"

Verify remote state:

gcloud storage ls gs://your-gcp-project-id-tfstate/foundation/

Expected:

gs://your-gcp-project-id-tfstate/foundation/default.tfstate

Next Step

This artifact only creates the foundation layer.

The next artifact will build on top of this idea by provisioning a production-lite GCP web platform.

That project will include:

Cloud NAT
Managed Instance Group
instance template
health check
HTTP load balancer
private backend instances

The foundation answers:

Can I bootstrap a clean Terraform-managed GCP environment?

The next artifact answers:

Can I provision infrastructure for an actual application platform?

CI/CD for Terraform on GCP: Plan on Pull Request, Apply with Approval, No Static Keys

Abraham Naiborhu — Wed, 13 May 2026 15:04:16 +0000

Hi guys, so, this will be my last lab.

In the previous labs, I used Terraform from my local machine.
The workflow was simple:

local terminal -> terraform plan -> terraform apply

That worked for learning, but it is not how I want to manage infrastructure changes in a more professional setup.

For this lab, I wanted to move Terraform execution into GitHub Actions.

The target workflow is:

Pull Request -> terraform fmt -> terraform validate -> terraform plan
Manual Approval -> terraform apply

The main goal is not only automation.

The main goal is infrastructure change control.

In this lab, I built a Terraform CI/CD workflow using:

GitHub Actions
Google Cloud Workload Identity Federation
Terraform remote state in Google Cloud Storage
terraform fmt -check
terraform validate
terraform plan
manual terraform apply
no downloaded service account JSON key

The key idea is:

Terraform should not only create infrastructure. Terraform changes should also be reviewed before they are applied.

Why This Lab Matters

Infrastructure as Code without review is dangerous.

Why only application code that needs review? why not Terraform? Thus, A better workflow is:

write Terraform code
open pull request
run terraform fmt and validate
run terraform plan
review the change
apply only after approval

This makes Terraform closer to a professional engineering workflow.

Why Workload Identity Federation?

One important decision in this lab was to avoid using a service account JSON key.

Instead, I used Workload Identity Federation.

The authentication flow is:

GitHub Actions OIDC token
  ↓
Google Workload Identity Provider
  ↓
Google service account impersonation
  ↓
Terraform can access Google Cloud

This means I do not need to download a long-lived service account key and store it in GitHub Secrets.

For this lab, GitHub Actions impersonates a Google Cloud service account through Workload Identity Federation.

Reference:

https://github.com/google-github-actions/auth

https://cloud.google.com/blog/products/identity-security/enabling-keyless-authentication-from-github-actions

What This Lab Creates

The infrastructure itself is intentionally simple.

This lab creates:

one custom VPC network
one subnet
remote Terraform state in Google Cloud Storage

Why simple?

Because the focus of this lab is not infrastructure complexity.

The focus is the Terraform delivery workflow.

I wanted the CI/CD workflow to be easy to debug before applying it to a bigger project such as my production-lite GCP web platform.

Folder Structure

The folder structure is:

terraform-gcp-learning-lab/
├── .github/
│   └── workflows/
│       ├── lab-09-terraform-plan.yml
│       └── lab-09-terraform-apply.yml
└── 09-terraform-cicd-github-actions/
    ├── backend.tf
    ├── main.tf
    ├── variables.tf
    ├── outputs.tf
    ├── terraform.tfvars.example
    └── README.md

The Terraform code lives inside:

09-terraform-cicd-github-actions/

The GitHub Actions workflows live inside:

.github/workflows/

Terraform Backend

The backend uses Google Cloud Storage.

terraform {
  backend "gcs" {
    bucket = "terraform-gcp-learning-lab-terraform-state"
    prefix = "terraform-gcp-learning-lab/09-terraform-cicd-github-actions"
  }
}

This keeps the state for this lab separate from the previous labs.

The expected state path is:

gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/09-terraform-cicd-github-actions/default.tfstate

Terraform Configuration

The Terraform configuration creates a small VPC and subnet.

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "6.8.0"
    }
  }
}

provider "google" {
  project = var.project
  region  = var.region
}

resource "google_compute_network" "vpc_network" {
  name                    = "${var.environment}-${var.network_name}"
  auto_create_subnetworks = false
}

resource "google_compute_subnetwork" "subnet" {
  name          = "${var.environment}-${var.subnet_name}"
  region        = var.region
  network       = google_compute_network.vpc_network.id
  ip_cidr_range = var.subnet_cidr_range
}

}

The expected resources are:

google_compute_network.vpc_network
google_compute_subnetwork.subnet

Variables

The root variables are defined in variables.tf.

variable "project" {
  description = "The Google Cloud project ID where resources will be created."
  type        = string

  validation {
    condition     = length(var.project) > 0
    error_message = "The project variable must not be empty."
  }
}

variable "region" {
  description = "Google Cloud region for regional resources."
  type        = string
  default     = "asia-southeast2"
}

variable "environment" {
  description = "Environment name used for resource naming."
  type        = string
  default     = "dev"
}

variable "network_name" {
  description = "Base name of the VPC network."
  type        = string
  default     = "cicd-network"
}

variable "subnet_name" {
  description = "Base name of the subnet."
  type        = string
  default     = "cicd-subnet"
}

variable "subnet_cidr_range" {
  description = "CIDR range for the subnet."
  type        = string
  default     = "10.90.1.0/24"
}

The project variable does not have a default value.

That is intentional.

I do not want to hardcode the Google Cloud project ID inside the Terraform configuration.

In GitHub Actions, I pass the value using:

-var="project=${{ vars.GCP_PROJECT_ID }}"

GitHub Repository Variables

In GitHub, I added repository variables under:

Settings -> Secrets and variables -> Actions -> Variables

The variables are:

Name	Example Value
`GCP_PROJECT_ID`	`terraform-gcp-learning-lab`
`GCP_REGION`	`asia-southeast2`
`GCP_WORKLOAD_IDENTITY_PROVIDER`	`projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/github/providers/github-provider`
`GCP_SERVICE_ACCOUNT`	`terraform-cicd@PROJECT_ID.iam.gserviceaccount.com`
`TF_WORKING_DIR`	`09-terraform-cicd-github-actions`
`TF_VERSION`	`1.15.1`

These are repository variables, not service account keys.

There is no downloaded JSON key.

Plan Workflow

The plan workflow runs on pull request.

File:

.github/workflows/lab-09-terraform-plan.yml

name: Lab 09 - Terraform Plan

on:
  pull_request:
    paths:
      - "09-terraform-cicd-github-actions/**"
      - ".github/workflows/lab-09-terraform-plan.yml"

permissions:
  contents: read
  id-token: write
  pull-requests: read

env:
  TF_IN_AUTOMATION: "true"
  TF_INPUT: "false"

jobs:
  terraform-plan:
    name: Terraform fmt, validate, and plan
    runs-on: ubuntu-latest

    defaults:
      run:
        working-directory: ${{ vars.TF_WORKING_DIR }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Authenticate to Google Cloud using WIF
        uses: google-github-actions/auth@v3
        with:
          project_id: ${{ vars.GCP_PROJECT_ID }}
          workload_identity_provider: ${{ vars.GCP_WORKLOAD_IDENTITY_PROVIDER }}
          service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v4
        with:
          terraform_version: ${{ vars.TF_VERSION }}

      - name: Terraform fmt check
        run: terraform fmt -check -recursive

      - name: Terraform init
        run: terraform init -input=false

      - name: Terraform validate
        run: terraform validate

      - name: Terraform plan
        run: |
          terraform plan \
            -input=false \
            -no-color \
            -var="project=${{ vars.GCP_PROJECT_ID }}" \
            -var="region=${{ vars.GCP_REGION }}"

The important part is:

permissions:
  contents: read
  id-token: write

The id-token: write permission is required for GitHub Actions to request an OIDC token for Workload Identity Federation.

Apply Workflow

The apply workflow is manually triggered.

File:

.github/workflows/lab-09-terraform-apply.yml

name: Lab 09 - Terraform Apply

on:
  workflow_dispatch:

permissions:
  contents: read
  id-token: write

env:
  TF_IN_AUTOMATION: "true"
  TF_INPUT: "false"

jobs:
  terraform-apply:
    name: Terraform plan and apply
    runs-on: ubuntu-latest
    environment: terraform-apply

    defaults:
      run:
        working-directory: ${{ vars.TF_WORKING_DIR }}

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Authenticate to Google Cloud using WIF
        uses: google-github-actions/auth@v3
        with:
          project_id: ${{ vars.GCP_PROJECT_ID }}
          workload_identity_provider: ${{ vars.GCP_WORKLOAD_IDENTITY_PROVIDER }}
          service_account: ${{ vars.GCP_SERVICE_ACCOUNT }}

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v4
        with:
          terraform_version: ${{ vars.TF_VERSION }}

      - name: Terraform fmt check
        run: terraform fmt -check -recursive

      - name: Terraform init
        run: terraform init -input=false

      - name: Terraform validate
        run: terraform validate

      - name: Terraform plan output file
        run: |
          terraform plan \
            -input=false \
            -no-color \
            -out=tfplan \
            -var="project=${{ vars.GCP_PROJECT_ID }}" \
            -var="region=${{ vars.GCP_REGION }}"

      - name: Terraform apply approved plan
        run: terraform apply -input=false -auto-approve tfplan

      - name: Terraform output
        run: terraform output

The apply workflow uses:

environment: terraform-apply

In GitHub, I configured this environment with required approval.

So the apply step is not fully automatic.

It still requires manual approval.

The Error I Encountered

My first plan workflow failed.

The error was:

Error: Invalid value for variable

on variables.tf line 1:
variable "project" {
  var.project is ""

The project variable must not be empty.

The important part is:

var.project is ""

This means Terraform did receive the variable, but the value was empty.

The workflow line was:

-var="project=${{ vars.GCP_PROJECT_ID }}"

So the likely issue was that vars.GCP_PROJECT_ID was empty or not configured correctly in GitHub Actions.

The authentication step still worked, but Terraform failed during the plan stage because the project variable was empty.

That was a useful lesson.

Authentication and Terraform input variables are related, but they are not the same thing.

WIF authentication lets GitHub Actions access Google Cloud.
Terraform variables tell Terraform what values to use.

In this case, WIF was working, but my Terraform variable was not being passed correctly.

The Fix

The fix was to check the GitHub repository variables.

In GitHub:

Repository -> Settings -> Secrets and variables -> Actions -> Variables

I made sure this variable existed exactly:

GCP_PROJECT_ID

with value:

terraform-gcp-learning-lab

The variable name must match exactly.

This:

GCP_PROJECT_ID

is not the same as:

PROJECT_ID

or:

GCP_PROJECT

After fixing the variable, the workflow was able to pass:

-var="project=${{ vars.GCP_PROJECT_ID }}"

correctly into Terraform.

Optional Debugging Step

A safe debugging step is to print whether the variable exists without printing sensitive values.

For this lab, GCP_PROJECT_ID is not a secret, so printing it is acceptable.

I can add this temporarily:

- name: Debug repository variables
  run: |
    echo "TF_WORKING_DIR=${{ vars.TF_WORKING_DIR }}"
    echo "GCP_REGION=${{ vars.GCP_REGION }}"
    echo "GCP_PROJECT_ID length=$(echo -n '${{ vars.GCP_PROJECT_ID }}' | wc -c)"

If the length is 0, the variable is missing or not available to the workflow.

I would remove this debug step after the workflow is stable.

The Successful Result

After fixing the variable, the workflow worked.

The plan workflow successfully ran:

terraform fmt -check
terraform init
terraform validate
terraform plan

Then the manual apply workflow successfully deployed the infrastructure.

The apply workflow created:

VPC network
subnet

The important thing is not that the infrastructure was complex.

The important thing is that Terraform was executed through GitHub Actions using Workload Identity Federation without a service account key.

Verifying the Infrastructure

After apply, I can verify the VPC:

gcloud compute networks list --filter="name=dev-cicd-network"

Expected:

dev-cicd-network

Then verify the subnet:

gcloud compute networks subnets list \
  --filter="name=dev-cicd-subnet"

Expected:

dev-cicd-subnet

I can also verify the remote state:

gcloud storage ls gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/09-terraform-cicd-github-actions/

Expected:

gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/09-terraform-cicd-github-actions/default.tfstate

What I Learned

This lab taught me that Terraform CI/CD is not only about running Terraform commands in GitHub Actions.

There are several separate concerns:

GitHub Actions workflow
Google Cloud authentication
Workload Identity Federation
Terraform remote state
Terraform variable injection
manual approval before apply

The error I encountered was useful because it showed that successful Google Cloud authentication does not guarantee Terraform has received the right input values.

WIF solved the authentication problem.

GitHub repository variables solved the Terraform input problem.

The key lesson was:

Authentication answers: who is running Terraform?
Variables answer: what values should Terraform use?

Those are different concerns.

Next Step

This lab is not the final artifact yet.

This is the learning lab for my future Terraform CI/CD artifact.

The next step is to take this same pattern and apply it to my larger Terraform project:

Production-Lite GCP Web Platform

That project will combine:

Terraform modules
remote state
VPC and subnets
Cloud NAT
Managed Instance Group
HTTP load balancer
GitHub Actions CI/CD
Workload Identity Federation

At that point, the infrastructure will not only be reproducible.

It will also be reviewable and safely deployable through CI/CD.

References

Managed Instance Group, Cloud NAT, Service Account, and HTTP Load Balancer

Abraham Naiborhu — Mon, 11 May 2026 09:40:55 +0000

In the previous lab, I created a private VM with no external IP and accessed it through IAP.

That lab worked for private access, but it also exposed an important issue.

The VM could be private, but without outbound internet access, the startup script could fail when trying to install packages.

In my case, Nginx installation failed because the VM had no external IP and no Cloud NAT.

That taught me an important distinction:

IAP = controlled inbound administrative access
Cloud NAT = outbound internet access for private resources

So in this lab, I wanted to build a more complete serving pattern.

Instead of using a single VM, I moved to:

instance template -> Managed Instance Group -> health check -> backend service -> HTTP load balancer

I also added Cloud NAT so the private backend instances can install Nginx during startup without needing external IP addresses.

What This Lab Builds

This lab provisions:

custom VPC network
app subnet
db subnet
Cloud Router
Cloud NAT
custom service account for MIG instances
IAM bindings
firewall rule for Google Cloud load balancer and health check traffic
internal firewall rule
HTTP health check
instance template
regional managed instance group
backend service
URL map
target HTTP proxy
global forwarding rule
external HTTP load balancer IP

The high-level architecture is:

Client
  ↓
Global forwarding rule
  ↓
Target HTTP proxy
  ↓
URL map
  ↓
Backend service
  ↓
Regional Managed Instance Group
  ↓
Private backend VMs
  ↓ outbound only
Cloud NAT

Why This Lab Matters

The previous private VM lab was about controlled administrative access.

This lab is about serving traffic properly.

A single VM is not enough for a production-like serving pattern.

A better pattern is to place backend instances inside a Managed Instance Group and expose them through a load balancer.

The backend instances remain private.

The public entry point is the load balancer.

Cloud NAT gives the backend instances outbound internet access for startup tasks such as package installation.

Folder Structure

The folder structure for this lab is:

08-mig-nat-http-lb/
├── backend.tf
├── main.tf
├── outputs.tf
├── startup.sh
├── terraform.tfvars
├── variables.tf
├── modules/
│   ├── gcp-cloud-nat/
│   ├── gcp-http-lb/
│   ├── gcp-mig/
│   ├── gcp-network/
│   └── gcp-service-account/

This lab uses five modules:

Module	Responsibility
`gcp-network`	Creates VPC, subnets, and firewall rules
`gcp-cloud-nat`	Creates Cloud Router and Cloud NAT
`gcp-service-account`	Creates a custom service account
`gcp-mig`	Creates instance template and managed instance group
`gcp-http-lb`	Creates the HTTP load balancer resources

Remote State

This lab still uses Google Cloud Storage as the Terraform backend.

terraform {
  backend "gcs" {
    bucket = "terraform-gcp-learning-lab-terraform-state"
    prefix = "terraform-gcp-learning-lab/08-mig-http-load-balancer"
  }
}

Each lab uses a different prefix so the state files do not collide.

Root Module

The root module wires all child modules together.

module "network" {
  source = "./modules/gcp-network"

  environment    = var.environment
  region         = var.region
  network_name   = var.network_name
  subnets        = var.subnets
  firewall_rules = var.firewall_rules
}

module "cloud_nat" {
  source = "./modules/gcp-cloud-nat"

  environment       = var.environment
  region            = var.region
  network_self_link = module.network.network_self_link
}

module "service_account" {
  source = "./modules/gcp-service-account"

  account_id   = "${var.environment}-${var.mig_service_account_id}"
  display_name = "${var.environment}-${var.mig_service_account_display_name}"
}

module "mig" {
  source                = "./modules/gcp-mig"
  service_account_email = module.service_account.email

  environment          = var.environment
  mig_name             = var.mig_name
  region               = var.region
  zone                 = var.mig_zone
  machine_type         = var.mig_machine_type
  subnetwork_self_link = module.network.subnets[var.mig_subnet_key].self_link
  tags                 = var.mig_tags

  startup_script_path    = "${path.module}/startup.sh"
  target_size            = var.mig_instance_count
  app_port               = var.app_port
  health_check_self_link = google_compute_health_check.http.self_link

  depends_on = [module.cloud_nat]
}

module "http_lb" {
  source = "./modules/gcp-http-lb"

  environment            = var.environment
  lb_name                = var.lb_name
  backend_instance_group = module.mig.mig_instance_group
  health_check_self_link = google_compute_health_check.http.self_link
  app_port               = var.app_port
}

The important dependency flow is:

network module -> Cloud NAT module
network module -> MIG module
service account module -> MIG module
MIG module -> HTTP load balancer module

The most important lines are:

network_self_link = module.network.network_self_link
subnetwork_self_link = module.network.subnets[var.mig_subnet_key].self_link
service_account_email = module.service_account.email
backend_instance_group = module.mig.mig_instance_group

These lines connect the modules together.

Cloud NAT Module

The Cloud NAT module creates a Cloud Router and Cloud NAT gateway.

resource "google_compute_router" "router" {
  name    = "${var.environment}-${var.router_name}"
  region  = var.region
  network = var.network_self_link
}

resource "google_compute_router_nat" "nat" {
  name                               = "${var.environment}-${var.nat_name}"
  router                             = google_compute_router.router.name
  region                             = var.region
  nat_ip_allocate_option             = "AUTO_ONLY"
  source_subnetwork_ip_ranges_to_nat = "ALL_SUBNETWORKS_ALL_IP_RANGES"

  log_config {
    enable = true
    filter = "ERRORS_ONLY"
  }
}

This solves the issue from the previous lab.

The backend instances can remain private while still having outbound internet access.

Service Account Module

This lab also creates a custom service account.

resource "google_service_account" "this" {
  account_id   = var.account_id
  display_name = var.display_name
}

The MIG instances use this service account instead of relying on the default Compute Engine service account.

The root module passes the service account email into the MIG module:

service_account_email = module.service_account.email

MIG Module

The MIG module creates an instance template and a regional managed instance group.

resource "google_compute_instance_template" "template" {
  name_prefix  = "${var.environment}-${var.mig_name}-template-"
  machine_type = var.machine_type
  tags         = var.tags

  disk {
    source_image = "debian-cloud/debian-12"
    auto_delete  = true
    boot         = true
    disk_size_gb = 10
    disk_type    = "pd-balanced"
  }

  network_interface {
    subnetwork = var.subnetwork_self_link
  }

  metadata_startup_script = file(var.startup_script_path)

  lifecycle {
    create_before_destroy = true
  }

  service_account {
    email  = var.service_account_email
    scopes = ["https://www.googleapis.com/auth/cloud-platform"]
  }
}

There is no external IP configuration in the network interface.

That means the backend instances remain private.

The regional managed instance group uses the template:

resource "google_compute_region_instance_group_manager" "mig" {
  name               = "${var.environment}-${var.mig_name}"
  region             = var.region
  base_instance_name = "${var.environment}-${var.mig_name}"
  target_size        = var.target_size

  version {
    instance_template = google_compute_instance_template.template.self_link
  }

  named_port {
    name = "http"
    port = var.app_port
  }

  distribution_policy_zones = [var.zone]

  auto_healing_policies {
    health_check      = var.health_check_self_link
    initial_delay_sec = 120
  }
}

The named port is important because the backend service uses:

port_name = "http"

So the MIG and backend service need to agree on the named port.

HTTP Load Balancer Module

The HTTP load balancer module creates:

global IP address
backend service
URL map
target HTTP proxy
global forwarding rule

resource "google_compute_global_address" "lb_ip" {
  name = "${var.environment}-${var.lb_name}-ip"
}

resource "google_compute_backend_service" "backend" {
  name                  = "${var.environment}-${var.lb_name}-backend"
  protocol              = "HTTP"
  port_name             = "http"
  load_balancing_scheme = "EXTERNAL_MANAGED"
  timeout_sec           = 30

  health_checks = [
    var.health_check_self_link
  ]

  backend {
    group           = var.backend_instance_group
    balancing_mode  = "UTILIZATION"
    capacity_scaler = 1.0
  }
}

The backend service points to the instance group output from the MIG module:

backend_instance_group = module.mig.mig_instance_group

That is the connection between the load balancer and the backend instances.

Firewall Rules

The firewall rules are still created by the network module.

The load balancer and health check rule allows:

source_ranges = ["35.191.0.0/16", "130.211.0.0/22"]
target_tags   = ["web-backend"]

The MIG instances also use:

mig_tags = ["web-backend"]

This means the firewall rule applies to the backend instances.

The rule allows traffic on port 80:

allow = [
  {
    protocol = "tcp"
    ports    = ["80"]
  }
]

Startup Script

The startup script installs Nginx and creates a simple HTML page.

#!/bin/bash
set -euo pipefail

apt-get update -y
apt-get install -y nginx

HOSTNAME="$(hostname)"
LOCAL_IP="$(hostname -I | awk '{print $1}')"

cat > /var/www/html/index.html <<EOF
<!doctype html>
<html>
  <head>
    <title>Terraform MIG Load Balancer Lab</title>
  </head>
  <body>
    <h1>Hello from Terraform Lab 008</h1>
    <p>This page is served from a private VM inside a Managed Instance Group.</p>
    <p>Hostname: ${HOSTNAME}</p>
    <p>Internal IP: ${LOCAL_IP}</p>
  </body>
</html>
EOF

systemctl enable nginx
systemctl restart nginx

In the previous private VM lab, this script failed because the VM had no external IP and no Cloud NAT.

In this lab, Cloud NAT should allow the backend instances to reach the internet and install Nginx successfully.

Variables

For local values, I used terraform.tfvars.

Public article version:

project         = "your-gcp-project-id"
region          = "asia-southeast2"
environment     = "dev"
admin_principal = "user:your-email@example.com"

network_name = "mig-lb-network"

subnets = {
  app = {
    cidr_range = "10.80.1.0/24"
  }

  db = {
    cidr_range = "10.80.2.0/24"
  }
}

firewall_rules = {
  allow-lb-health-check = {
    description   = "Allow Google Cloud load balancer health checks and proxy traffic."
    source_ranges = ["35.191.0.0/16", "130.211.0.0/22"]
    target_tags   = ["web-backend"]

    allow = [
      {
        protocol = "tcp"
        ports    = ["80"]
      }
    ]
  }

  allow-internal = {
    description   = "Allow internal traffic between lab subnets."
    source_ranges = ["10.80.0.0/16"]

    allow = [
      {
        protocol = "tcp"
        ports    = ["0-65535"]
      },
      {
        protocol = "udp"
        ports    = ["0-65535"]
      },
      {
        protocol = "icmp"
      }
    ]
  }
}

mig_name           = "web-mig"
mig_instance_count = 2
mig_machine_type   = "e2-micro"
mig_zone           = "asia-southeast2-a"
mig_subnet_key     = "app"
mig_tags           = ["web-backend"]

mig_service_account_id           = "web-mig-sa"
mig_service_account_display_name = "Web MIG Service Account"

lb_name  = "web-lb"
app_port = 80

I do not commit the real terraform.tfvars file to GitHub.

For GitHub, I use:

terraform.tfvars.example

Initialize, Format, and Validate

After preparing the files, I ran:

terraform init

Then:

terraform fmt -recursive

Then:

terraform validate

The validation result was:

Success! The configuration is valid.

Terraform Plan

The plan should show resources across multiple modules:

module.network
module.cloud_nat
module.service_account
module.mig
module.http_lb

The important thing here is not just the number of resources.

The important thing is the dependency chain:

VPC and subnets are created first.
Cloud NAT is attached to the network.
Instance template uses the app subnet and service account.
MIG creates backend instances.
Backend service uses the MIG instance group.
Load balancer exposes the backend service.

Terraform Apply

After reviewing the plan:

terraform apply

Then type:

yes

The apply process may take several minutes because the MIG needs time to create backend instances and the load balancer needs time to detect healthy backends.

Outputs

Useful outputs from this lab include:

terraform output load_balancer_ip
terraform output load_balancer_url
terraform output curl_test_command
terraform output lab_summary

The most important output is:

load_balancer_url

This is the public HTTP endpoint for the lab.

Testing the Load Balancer

To test the load balancer:

curl -i $(terraform output -raw load_balancer_url)

Expected result:

HTTP/1.1 200 OK

The response body should contain:

Hello from Terraform Lab 008

To test whether traffic may reach different backend instances:

for i in {1..5}; do
  curl -s $(terraform output -raw load_balancer_url) | grep Hostname
done

If both backend instances are healthy and receiving traffic, the hostname may change across requests.

Verifying Backend Health

I can check backend health using:

gcloud compute backend-services get-health dev-web-lb-backend \
  --global

Expected health state:

HEALTHY

If the backend is unhealthy, possible causes include:

startup script still running
Nginx failed to install
health check firewall rule is wrong
named port mismatch
backend instances are not listening on port 80

Verifying Private Backend Instances

The backend instances should not have external IP addresses.

gcloud compute instances list \
  --filter="name~dev-web-mig"

The external IP column should be empty.

This confirms that the backend instances are private.

The load balancer is public, but the backend instances are not directly exposed.

Verifying Cloud NAT

To verify Cloud NAT:

gcloud compute routers nats list \
  --router=dev-nat-router \
  --region=asia-southeast2

Expected result:

dev-nat-gateway

This confirms that Cloud NAT exists for the VPC.

Verifying Remote State

The remote state should be stored in Google Cloud Storage:

gcloud storage ls gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/08-mig-http-load-balancer/

Expected result:

gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/08-mig-http-load-balancer/default.tfstate

What I Learned

This lab connected several important Terraform and Google Cloud concepts.

The previous labs taught me:

how to create resources
how to use variables
how to use outputs
how to use remote state
how to create modules
how to create a private VM

This lab combined those concepts into a more realistic serving architecture.

The most important lesson is:

A private backend can still serve public traffic through a load balancer.

The backend instances do not need external IP addresses.

The public entry point is the load balancer.

The backend instances can still install packages during startup because Cloud NAT provides outbound internet access.

Another important lesson is how Terraform modules compose infrastructure:

network module creates network outputs
Cloud NAT module uses network output
service account module creates workload identity
MIG module uses subnet and service account outputs
load balancer module uses MIG output

Next Step

This lab uses an HTTP load balancer.

The next improvement would be to move from HTTP to HTTPS.

That would introduce:

managed SSL certificate
domain mapping
HTTPS proxy
forwarding rule on port 443
possibly Cloud DNS

That would make the infrastructure closer to a real public-facing production setup.

Private VM Access with IAP, OS Login, and Service Account

Abraham Naiborhu — Sun, 10 May 2026 08:06:49 +0000

In the previous Terraform lab, I created a private Compute Engine VM using module composition.

The VM was created from a reusable gcp-vm module, while the network was created from a reusable gcp-network module.

That lab helped me understand this pattern:

network module output -> root module -> VM module input

For this lab, I wanted to improve the access pattern.

Previously, the VM already had:

no external IP
an IAP SSH firewall rule
the iap-ssh network tag

However, that was only half of the private access story.

In this lab, I wanted to make the private VM access pattern more complete by adding:

custom VM service account
OS Login
IAP TCP forwarding access
IAM bindings
startup script verification
SSH access through IAP

The goal was to move from:

VM exists

to:

VM exists, has no external IP, and can be accessed in a controlled way through IAP.

What This Lab Builds

This lab provisions:

custom VPC network
app subnet
db subnet
firewall rule for IAP SSH
internal firewall rule
custom VM service account
IAM binding for IAP TCP forwarding
IAM binding for OS Login
IAM binding for service account usage
private Compute Engine VM
startup script for Nginx installation
remote Terraform state in Google Cloud Storage

The important thing is that the VM has no external IP address.

Architecture

The structure is now composed of three child modules:

07-private-vm-access-iap/
├── modules/
│   ├── gcp-network/
│   ├── gcp-service-account/
│   └── gcp-vm/

The root module wires them together:

Root module
│
├── module.network
│   ├── VPC
│   ├── app subnet
│   ├── db subnet
│   ├── IAP SSH firewall rule
│   └── internal firewall rule
│
├── module.vm_service_account
│   └── custom VM service account
│
├── IAM bindings
│   ├── IAP tunnel access
│   ├── OS Login admin access
│   └── service account user access
│
└── module.vm
    └── private VM

The main Terraform pattern is:

network module output -> root module -> VM module input
service account module output -> root module -> VM module input
IAM bindings -> controlled private VM access

Why IAP?

Normally, if a VM has an external IP, I can SSH into it from the internet if the firewall allows it.

But exposing SSH publicly is not a good habit.

For this lab, I wanted the VM to stay private.

So instead of giving the VM an external IP, I used Identity-Aware Proxy TCP forwarding.

The firewall rule allows SSH only from Google’s IAP TCP forwarding source range:

35.235.240.0/20

The VM also has this network tag:

iap-ssh

So the firewall rule applies only to instances with that tag.

Why OS Login?

I also enabled OS Login.

Instead of managing SSH keys manually in project or instance metadata, OS Login allows VM login access to be controlled through IAM.

For this lab, the selected admin principal receives:

roles/compute.osAdminLogin

This allows the principal to log in through OS Login with admin-level access.

Why a Custom Service Account?

I also created a dedicated service account for the VM.

The service account is:

dev-iap-private-vm-sa@terraform-gcp-learning-lab.iam.gserviceaccount.com

This is better than blindly using the default Compute Engine service account.

In real environments, each workload should have an identity that matches what it needs to do.

For this lab, the service account exists mainly to practice a cleaner VM identity pattern.

Backend Configuration

This lab still uses remote state in Google Cloud Storage.

Example backend.tf:

terraform {
  backend "gcs" {
    bucket = "terraform-gcp-learning-lab-terraform-state"
    prefix = "terraform-gcp-learning-lab/07-private-vm-access-iap"
  }
}

This means the state for this lab is isolated from the previous labs.

Root Module

The root module calls three child modules:

module "network" {
  source = "./modules/gcp-network"

  environment    = var.environment
  region         = var.region
  network_name   = var.network_name
  subnets        = var.subnets
  firewall_rules = var.firewall_rules
}

module "vm_service_account" {
  source = "./modules/gcp-service-account"

  account_id   = "${var.environment}-${var.vm_service_account_id}"
  display_name = "${var.environment} ${var.vm_service_account_display_name}"
}

module "vm" {
  source = "./modules/gcp-vm"

  environment           = var.environment
  vm_name               = var.vm_name
  machine_type          = var.vm_machine_type
  zone                  = var.vm_zone
  tags                  = var.vm_tags
  subnetwork_self_link  = module.network.subnets[var.vm_subnet_key].self_link
  service_account_email = module.vm_service_account.email
  startup_script_path   = "${path.module}/startup.sh"
  enable_oslogin        = var.enable_oslogin
}

The important lines are:

subnetwork_self_link = module.network.subnets[var.vm_subnet_key].self_link
service_account_email = module.vm_service_account.email

This means the VM module does not create its own network or service account.

Instead, it consumes outputs from other modules.

IAM Bindings

This lab also creates IAM bindings.

resource "google_project_iam_member" "iap_tunnel_user" {
  project = var.project
  role    = "roles/iap.tunnelResourceAccessor"
  member  = var.admin_principal
}

resource "google_project_iam_member" "os_admin_login" {
  project = var.project
  role    = "roles/compute.osAdminLogin"
  member  = var.admin_principal
}

resource "google_service_account_iam_member" "vm_service_account_user" {
  service_account_id = module.vm_service_account.name
  role               = "roles/iam.serviceAccountUser"
  member             = var.admin_principal
}

These roles support the access pattern:

Role	Purpose
`roles/iap.tunnelResourceAccessor`	Allows IAP TCP forwarding
`roles/compute.osAdminLogin`	Allows OS Login with admin privileges
`roles/iam.serviceAccountUser`	Allows the principal to use the VM service account

Network Module

The network module creates:

VPC
subnets
firewall rules

The firewall rule for IAP SSH allows traffic from:

35.235.240.0/20

and targets instances tagged with:

iap-ssh

My Terraform output showed:

"allow-iap-ssh" = {
  "name" = "dev-allow-iap-ssh"
  "source_ranges" = toset([
    "35.235.240.0/20",
  ])
  "target_tags" = toset([
    "iap-ssh",
  ])
}

VM Module

The VM module creates the private Compute Engine instance.

The VM resource uses:

network_interface {
  subnetwork = var.subnetwork_self_link
}

There is no access_config block.

That means the VM does not receive an external IP address.

The VM also uses:

metadata = {
  enable-oslogin = tostring(var.enable_oslogin)
}

and attaches the custom service account:

service_account {
  email  = var.service_account_email
  scopes = ["https://www.googleapis.com/auth/cloud-platform"]
}

Terraform Apply Result

After running:

terraform apply

the lab completed successfully.

The output showed:

vm_name = "dev-iap-private-vm"
vm_internal_ip = "10.60.1.2"
vm_machine_type = "e2-micro"
vm_service_account_email = "dev-iap-private-vm-sa@terraform-gcp-learning-lab.iam.gserviceaccount.com"
vm_zone = "asia-southeast2-a"

The lab summary showed:

lab_summary = {
  "environment" = "dev"
  "firewall_count" = 2
  "iap_ssh_enabled_pattern" = true
  "network_name" = "dev-iap-private-network"
  "os_login_enabled" = true
  "project" = "terraform-gcp-learning-lab"
  "region" = "asia-southeast2"
  "subnet_count" = 2
  "vm_external_ip" = "none"
  "vm_internal_ip" = "10.60.1.2"
  "vm_name" = "dev-iap-private-vm"
  "vm_service_account_email" = "dev-iap-private-vm-sa@terraform-gcp-learning-lab.iam.gserviceaccount.com"
  "vm_subnet_key" = "app"
  "vm_zone" = "asia-southeast2-a"
}

This confirmed that the VM was created privately with:

vm_external_ip = "none"

Verifying That the VM Has No External IP

I verified the VM using:

gcloud compute instances describe dev-iap-private-vm \
  --zone=asia-southeast2-a \
  --format="table(name,networkInterfaces[0].networkIP,networkInterfaces[0].accessConfigs)"

The result was:

NAME                NETWORK_IP  ACCESS_CONFIGS
dev-iap-private-vm  10.60.1.2

The ACCESS_CONFIGS field is empty.

That confirms that the VM has no external IP address.

SSH Command Through IAP

Terraform also generated the IAP SSH command:

gcloud compute ssh dev-iap-private-vm --zone=asia-southeast2-a --tunnel-through-iap

This command is important because the VM is private.

Without an external IP, I cannot SSH directly from the public internet.

The intended access path is through IAP TCP forwarding.

The One Thing That Failed: Startup Script Internet Access

Almost everything worked.

But one thing failed.

The startup script tried to install Nginx:

apt-get update -y
apt-get install -y nginx

The VM failed to fetch the Nginx package from Debian repositories.

The error was:

Failed to fetch https://deb.debian.org/debian-security/pool/updates/main/n/nginx/nginx_1.22.1-9%2bdeb12u4_amd64.deb
Cannot initiate the connection to deb.debian.org:443
Network is unreachable

This happened because the VM has no external IP address and I did not configure Cloud NAT.

So the VM was private, but it also had no outbound internet path to reach Debian package repositories.

This is an important distinction.

IAP solves private administrative access into the VM.
Cloud NAT solves outbound internet access from the VM.

In this lab, I configured IAP access, but I did not configure Cloud NAT yet.

That means SSH through IAP can work, but installing packages from the internet during startup may fail.

This is not a Terraform failure.

This is a network design gap.

What Worked

The successful parts were:

custom VPC created
app and db subnets created
VM created in the app subnet
VM has no external IP
custom service account attached to the VM
OS Login enabled
IAP SSH firewall rule created
IAP SSH command generated
Terraform outputs confirmed the infrastructure
remote state continued to work

The key output was:

vm_external_ip = "none"
vm_internal_ip = "10.60.1.2"
iap_ssh_enabled_pattern = true
os_login_enabled = true

That means the core private access pattern was successfully provisioned.

What Did Not Work

The startup script verification did not fully work because the VM could not install Nginx.

The command that would normally verify Nginx was:

curl -I http://localhost

But since Nginx installation failed, this verification could not succeed yet.

The root cause was not the startup script itself.

The root cause was that the private VM had no outbound internet path.

How I Would Fix This Next

There are several ways to fix this.

The most appropriate next lab is to add:

Cloud Router
Cloud NAT
private VM outbound internet access
startup script retry
Nginx installation verification

That would allow the VM to stay private while still being able to reach package repositories on the internet.

The improved design would be:

Private VM
    ↓ outbound internet
Cloud NAT
    ↓
Internet package repositories

The VM would still have no external IP.

But it could access the internet for outbound traffic through Cloud NAT.

What I Learned

This lab clarified an important distinction:

Private inbound access and private outbound access are different problems.

IAP helps solve inbound administrative access.

It lets me access a private VM without giving it an external IP.

But IAP does not automatically give the VM outbound internet access.

For outbound internet access from a VM with no external IP, I need something like Cloud NAT.

This is an important infrastructure lesson.

At first, I thought:

The VM has IAP, so it should be fine.

But that was incomplete.

The better understanding is:

IAP = controlled inbound access to private VM
Cloud NAT = outbound internet access from private VM

This failure actually made the lab better because it revealed a real production design consideration.

Creating a VM from Network Module Outputs

Abraham Naiborhu — Sat, 09 May 2026 15:49:20 +0000

In the previous lab, I created a reusable Terraform module for Google Cloud networking.

That module created:

a custom VPC network
multiple subnets
firewall rules
outputs for network, subnet, and firewall information

That was already an improvement from writing every resource directly in the root configuration.

However, the network module was still isolated. It created network resources, but nothing else was consuming those outputs yet.

So in this lab, I wanted to take the next logical step:

Create a Compute Engine VM that uses the subnet output from the network module.

At first, I considered creating the VM directly in the root module. But then I changed the format and added a second module:

modules/gcp-vm

So now the lab has two child modules:

modules/gcp-network
modules/gcp-vm

The purpose of this lab is to understand module composition.

The main idea is:

The network module creates the network.
The network module exposes subnet outputs.
The root module passes the selected subnet output into the VM module.
The VM module creates a VM inside that subnet.

What This Lab Builds

This lab creates:

one custom VPC network
two subnets
two firewall rules
one Compute Engine VM
a startup script that installs Nginx
remote state in Google Cloud Storage
outputs from both the network module and VM module

The final result from Terraform was:

Apply complete! Resources: 6 added, 0 changed, 0 destroyed.

The six resources were:

VPC network
app subnet
db subnet
IAP SSH firewall rule
internal firewall rule
Compute Engine VM

Folder Structure

The final folder structure is:

06-gcp-vm-and-network-module/
├── backend.tf
├── main.tf
├── modules
│   ├── gcp-network
│   │   ├── main.tf
│   │   ├── outputs.tf
│   │   └── variables.tf
│   └── gcp-vm
│       ├── main.tf
│       ├── outputs.tf
│       └── variables.tf
├── outputs.tf
├── README.md
├── startup.sh
├── terraform.tfvars
├── terraform.tfvars.example
└── variables.tf

There are now two child modules:

Module	Responsibility
`gcp-network`	Creates VPC, subnets, and firewall rules
`gcp-vm`	Creates the Compute Engine VM

The root module is responsible for wiring them together.

The Main Concept: Module Composition

In the previous lab, the network module created subnets and exposed them through outputs.

The output looked conceptually like this:

output "subnets" {
  value = {
    for subnet_key, subnet in google_compute_subnetwork.subnets :
    subnet_key => {
      name       = subnet.name
      id         = subnet.id
      region     = subnet.region
      cidr_range = subnet.ip_cidr_range
      self_link  = subnet.self_link
    }
  }
}

Because of this output, the root module can access:

module.network.subnets["app"].self_link

In this lab, that value is passed into the VM module.

The important pattern is:

network module output -> root module -> VM module input

This was the main learning point.

Remote State

This lab still uses Google Cloud Storage as the Terraform backend.

Example backend.tf:

terraform {
  backend "gcs" {
    bucket = "terraform-gcp-learning-lab-terraform-state"
    prefix = "terraform-gcp-learning-lab/06-gcp-vm-and-network-module"
  }
}

The state path is:

gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/06-gcp-vm-and-network-module/default.tfstate

Each lab has a different backend prefix so that the state files do not collide.

Root `main.tf`

The root main.tf configures the provider and calls both modules.

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "6.8.0"
    }
  }
}

provider "google" {
  project = var.project
  region  = var.region
}

module "network" {
  source = "./modules/gcp-network"

  environment    = var.environment
  region         = var.region
  network_name   = var.network_name
  subnets        = var.subnets
  firewall_rules = var.firewall_rules
}

module "vm" {
  source = "./modules/gcp-vm"

  environment          = var.environment
  vm_name              = var.vm_name
  machine_type         = var.vm_machine_type
  zone                 = var.vm_zone
  tags                 = var.vm_tags
  subnetwork_self_link = module.network.subnets[var.vm_subnet_key].self_link
  startup_script_path  = "${path.module}/startup.sh"
}

The most important line is:

subnetwork_self_link = module.network.subnets[var.vm_subnet_key].self_link

This line means:

Get the selected subnet from the network module output and pass it into the VM module.

If:

vm_subnet_key = "app"

then Terraform resolves:

module.network.subnets["app"].self_link

That is the subnet used by the VM.

Why This is Better Than Hardcoding the Subnet

Without module outputs, I could hardcode the subnet like this:

subnetwork = "dev-app-subnet"

But that is weaker.

The VM module should not guess or hardcode the subnet.

Instead, the network module creates the subnet, exposes the subnet self-link, and the root module passes that value into the VM module.

This makes the dependency clear.

The VM depends on the subnet created by the network module.

VM Module

The VM module is responsible for creating the Compute Engine instance.

Inside:

modules/gcp-vm/main.tf

the VM resource is defined like this:

resource "google_compute_instance" "app_vm" {
  name         = "${var.environment}-${var.vm_name}"
  machine_type = var.machine_type
  zone         = var.zone
  tags         = var.tags

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-12"
      size  = 10
      type  = "pd-balanced"
    }
  }

  network_interface {
    subnetwork = var.subnetwork_self_link
  }

  metadata_startup_script = file(var.startup_script_path)
}

The VM does not receive an external IP address because there is no access_config block inside the network_interface.

That means the VM is private.

This is intentional.

For this lab, I wanted the VM to use an internal IP only.

Startup Script

The VM uses a startup script to install Nginx.

File:

startup.sh

#!/bin/bash
set -euo pipefail

apt-get update -y
apt-get install -y nginx

cat > /var/www/html/index.html <<EOF
<!doctype html>
<html>
  <head>
    <title>Terraform Module Output VM</title>
  </head>
  <body>
    <h1>Hello from Terraform</h1>
    <p>This VM was created using a subnet output from the network module.</p>
  </body>
</html>
EOF

systemctl enable nginx
systemctl restart nginx

The startup script is passed into the VM module using:

startup_script_path = "${path.module}/startup.sh"

Then the VM module reads it using:

metadata_startup_script = file(var.startup_script_path)

Firewall Rules

The network module creates two firewall rules.

IAP SSH Rule

dev-allow-iap-ssh

This allows SSH from:

35.235.240.0/20

with the target tag:

iap-ssh

The VM also has the tag:

iap-ssh

That means the IAP SSH firewall rule applies to this VM.

Internal Rule

dev-allow-internal

This allows internal traffic from:

10.50.0.0/16

This is used for internal communication between the lab subnets.

Variables

The local values are stored in terraform.tfvars.

project      = "terraform-gcp-learning-lab"
region       = "asia-southeast2"
environment  = "dev"
network_name = "network-module"

subnets = {
  app = {
    cidr_range = "10.50.1.0/24"
  }

  db = {
    cidr_range = "10.50.2.0/24"
  }
}

firewall_rules = {
  allow-iap-ssh = {
    description   = "Allow SSH through IAP only."
    source_ranges = ["35.235.240.0/20"]
    target_tags   = ["iap-ssh"]

    allow = [
      {
        protocol = "tcp"
        ports    = ["22"]
      }
    ]
  }

  allow-internal = {
    description   = "Allow internal traffic between lab subnets."
    source_ranges = ["10.50.0.0/16"]

    allow = [
      {
        protocol = "tcp"
        ports    = ["0-65535"]
      },
      {
        protocol = "udp"
        ports    = ["0-65535"]
      },
      {
        protocol = "icmp"
      }
    ]
  }
}

vm_name         = "module-output-vm"
vm_machine_type = "e2-micro"
vm_zone         = "asia-southeast2-a"
vm_subnet_key   = "app"
vm_tags         = ["iap-ssh"]

The important VM value is:

vm_subnet_key = "app"

This tells Terraform to place the VM in the app subnet.

Initialize Terraform

After preparing the files, I ran:

terraform init

Because this lab uses two child modules, Terraform initializes both modules.

Expected output includes:

Initializing modules...
- network in modules/gcp-network
- vm in modules/gcp-vm

Format and Validate

Because this lab has nested module folders, I used:

terraform fmt -recursive

Then I validated the configuration:

terraform validate

Expected output:

Success! The configuration is valid.

Terraform Plan

Next, I ran:

terraform plan

Terraform planned to create six resources:

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

The planned resources included:

module.network.google_compute_firewall.ingress_rules["allow-iap-ssh"]
module.network.google_compute_firewall.ingress_rules["allow-internal"]
module.network.google_compute_network.vpc_network
module.network.google_compute_subnetwork.subnets["app"]
module.network.google_compute_subnetwork.subnets["db"]
module.vm.google_compute_instance.app_vm

This plan output is important because it shows the module boundaries.

Network resources are created under:

module.network

The VM is created under:

module.vm

Apply

After reviewing the plan, I applied the configuration:

terraform apply

Then I typed:

yes

Terraform completed successfully:

Apply complete! Resources: 6 added, 0 changed, 0 destroyed.

Terraform Outputs

After apply, I checked:

terraform output

The output showed the network, subnet, firewall, and VM information.

lab_summary = {
  "environment" = "dev"
  "firewall_count" = 2
  "network_name" = "dev-network-module"
  "project" = "terraform-gcp-learning-lab"
  "region" = "asia-southeast2"
  "subnet_count" = 2
  "vm_external_ip" = "none"
  "vm_internal_ip" = "10.50.1.2"
  "vm_name" = "dev-module-output-vm"
  "vm_subnet_key" = "app"
  "vm_subnet_link" = "https://www.googleapis.com/compute/v1/projects/terraform-gcp-learning-lab/regions/asia-southeast2/subnetworks/dev-app-subnet"
  "vm_zone" = "asia-southeast2-a"
}

This confirms several important things:

Output	Meaning
`vm_name`	VM was created as `dev-module-output-vm`
`vm_internal_ip`	VM received internal IP `10.50.1.2`
`vm_external_ip`	VM has no external IP
`vm_subnet_key`	VM selected the `app` subnet
`vm_subnet_link`	VM consumed the app subnet self-link from the network module

The VM output also showed:

vm_selected_subnet_key = "app"
vm_selected_subnet_self_link = "https://www.googleapis.com/compute/v1/projects/terraform-gcp-learning-lab/regions/asia-southeast2/subnetworks/dev-app-subnet"

This proves that the VM was attached to the subnet created by the network module.

Subnet Outputs

The subnet outputs showed:

subnets = {
  "app" = {
    "cidr_range" = "10.50.1.0/24"
    "id" = "projects/terraform-gcp-learning-lab/regions/asia-southeast2/subnetworks/dev-app-subnet"
    "name" = "dev-app-subnet"
    "region" = "asia-southeast2"
    "self_link" = "https://www.googleapis.com/compute/v1/projects/terraform-gcp-learning-lab/regions/asia-southeast2/subnetworks/dev-app-subnet"
  }
  "db" = {
    "cidr_range" = "10.50.2.0/24"
    "id" = "projects/terraform-gcp-learning-lab/regions/asia-southeast2/subnetworks/dev-db-subnet"
    "name" = "dev-db-subnet"
    "region" = "asia-southeast2"
    "self_link" = "https://www.googleapis.com/compute/v1/projects/terraform-gcp-learning-lab/regions/asia-southeast2/subnetworks/dev-db-subnet"
  }
}

This confirms that the network module created both the app and db subnets.

Firewall Outputs

The firewall outputs showed:

firewall_rules = {
  "allow-iap-ssh" = {
    "id" = "projects/terraform-gcp-learning-lab/global/firewalls/dev-allow-iap-ssh"
    "name" = "dev-allow-iap-ssh"
    "source_ranges" = toset([
      "35.235.240.0/20",
    ])
    "target_tags" = toset([
      "iap-ssh",
    ])
  }
  "allow-internal" = {
    "id" = "projects/terraform-gcp-learning-lab/global/firewalls/dev-allow-internal"
    "name" = "dev-allow-internal"
    "source_ranges" = toset([
      "10.50.0.0/16",
    ])
    "target_tags" = toset(null) /* of string */
  }
}

The IAP SSH rule targets instances with the tag:

iap-ssh

The VM also uses:

vm_tags = ["iap-ssh"]

So the firewall rule is connected to the VM through network tags.

Verify the VM

I can verify the VM using:

gcloud compute instances list --filter="name=dev-module-output-vm"

I can also inspect the VM network interface:

gcloud compute instances describe dev-module-output-vm \
  --zone=asia-southeast2-a \
  --format="value(networkInterfaces[0].subnetwork,networkInterfaces[0].networkIP,networkInterfaces[0].accessConfigs)"

The expected result is:

subnetwork: dev-app-subnet
internal IP: 10.50.1.2
external IP/accessConfigs: empty

This means the VM is private and does not have an external IP.

Verify Remote State

Because this lab uses the GCS backend, the state is stored remotely.

I can verify it with:

gcloud storage ls gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/06-gcp-vm-and-network-module/

Expected output:

gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/06-gcp-vm-and-network-module/default.tfstate

Destroy

Because this is still a learning lab, I destroyed the resources after testing:

terraform destroy

Then I typed:

yes

Terraform destroyed the resources managed by this lab.

What I Learned

This lab helped me understand Terraform module composition more clearly.

In the previous lab, I had one child module:

gcp-network

In this lab, I added another child module:

gcp-vm

The most important lesson was not just creating a VM.

The important lesson was passing an output from one module into another module.

The flow is:

gcp-network creates subnets
gcp-network outputs subnet self-links
root module selects the app subnet
root module passes the subnet self-link into gcp-vm
gcp-vm creates a VM in that subnet

The key Terraform expression is:

module.network.subnets[var.vm_subnet_key].self_link

Breaking it down:

module.network

means the network child module.

.subnets

means the subnet output from that module.

[var.vm_subnet_key]

means select one subnet from the subnet map.

.self_link

means use the selected subnet self-link.

So if:

vm_subnet_key = "app"

Terraform uses:

module.network.subnets["app"].self_link

This is then passed into the VM module.

That is the main pattern I wanted to learn:

module output -> root module -> another module input

Next Step

The next logical step is to improve the VM access pattern.

Right now, the VM has no external IP and has an IAP SSH firewall rule.

The next lab could focus on testing private VM access through IAP, or improving the module further by adding:

service account for the VM
IAM binding for IAP SSH
OS Login configuration
startup script verification
HTTP health check or internal-only web service testing

Building a Reusable VPC, Subnets, and Firewall Rules Module

Abraham Naiborhu — Sat, 09 May 2026 07:16:13 +0000

In the previous Terraform labs, I created Google Cloud resources directly from the root configuration.

That worked, but the structure was still quite simple.

Every resource was defined directly inside the main Terraform configuration. For a small lab, that is fine. But as the infrastructure grows, putting everything in one root configuration can become harder to maintain.

So in this lab, I started learning Terraform modules.

The goal is to turn the previous VPC and subnet configuration into a reusable local module.

But instead of only creating one VPC and one subnet, I made the lab slightly more practical by creating:

one custom VPC network
two subnets
two firewall rules
reusable module inputs
module outputs
remote state using Google Cloud Storage

What is a Terraform Module?

A Terraform module is a collection of Terraform configuration files that are managed together.

In simple terms, a module is like a reusable infrastructure component.

For this lab, I created a local module called:

modules/gcp-network

This module is responsible for creating the GCP network resources.

The root configuration calls that module and passes values into it.

Root Module vs Child Module

The folder where I run Terraform commands is the root module.

In this lab, the root module is:

05-gcp-network-module/

The reusable child module is:

05-gcp-network-module/modules/gcp-network/

The root module is the entry point.

The child module is the reusable implementation.

The mental model is:

Root module = caller
Child module = reusable implementation
Child module variables = function parameters
Child module outputs = return values

Since I have written JavaScript before, this feels similar to calling a function.

The root module passes values into the child module, and the child module creates the infrastructure based on those values.

Final Folder Structure

The folder structure for this lab is:

05-gcp-network-module/
├── backend.tf
├── main.tf
├── variables.tf
├── outputs.tf
├── terraform.tfvars
├── terraform.tfvars.example
└── modules/
    └── gcp-network/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

For GitHub, I only commit:

05-gcp-network-module/
├── backend.tf
├── main.tf
├── variables.tf
├── outputs.tf
├── terraform.tfvars.example
└── modules/
    └── gcp-network/
        ├── main.tf
        ├── variables.tf
        └── outputs.tf

I do not commit:

terraform.tfvars
.terraform/
terraform.tfstate

Backend Configuration

This lab still uses remote state with Google Cloud Storage.

In backend.tf, I configured the GCS backend:

terraform {
  backend "gcs" {
    bucket = "terraform-gcp-learning-lab-terraform-state"
    prefix = "terraform-gcp-learning-lab/05-gcp-network-module"
  }
}

The bucket is:

terraform-gcp-learning-lab-terraform-state

The state path is:

terraform-gcp-learning-lab/05-gcp-network-module/default.tfstate

Each lab should have its own state prefix.

This avoids accidentally mixing state from different labs.

Root `main.tf`

The root main.tf configures the provider and calls the child module.

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "6.8.0"
    }
  }
}

provider "google" {
  project = var.project
  region  = var.region
}

module "network" {
  source = "./modules/gcp-network"

  environment    = var.environment
  region         = var.region
  network_name   = var.network_name
  subnets        = var.subnets
  firewall_rules = var.firewall_rules
}

The most important part is this:

module "network" {
  source = "./modules/gcp-network"
}

This tells Terraform to use the local module inside:

modules/gcp-network

The root module passes values such as:

environment
region
network_name
subnets
firewall_rules

into the child module.

Root `variables.tf`

In the root variables.tf, I declared the values that the lab accepts.

variable "project" {
  description = "The Google Cloud project ID where resources will be created."
  type        = string

  validation {
    condition     = length(var.project) > 0
    error_message = "The project variable must not be empty."
  }
}

variable "region" {
  description = "Default Google Cloud region for regional resources."
  type        = string
  default     = "asia-southeast2"

  validation {
    condition     = contains(["asia-southeast2", "asia-southeast1", "us-central1"], var.region)
    error_message = "Region must be one of: asia-southeast2, asia-southeast1, or us-central1."
  }
}

variable "environment" {
  description = "Environment name used for resource naming."
  type        = string
  default     = "dev"

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Environment must be one of: dev, staging, or prod."
  }
}

variable "network_name" {
  description = "Base name of the VPC network."
  type        = string
  default     = "network-module"

  validation {
    condition     = can(regex("^[a-z]([-a-z0-9]*[a-z0-9])?$", var.network_name))
    error_message = "Network name must use lowercase letters, numbers, and hyphens. It must start with a letter and end with a letter or number."
  }
}

variable "subnets" {
  description = "Map of subnets to create inside the VPC."
  type = map(object({
    cidr_range = string
    region     = optional(string)
  }))

  validation {
    condition = alltrue([
      for subnet_key, subnet in var.subnets :
      can(regex("^[a-z]([-a-z0-9]*[a-z0-9])?$", subnet_key)) &&
      can(cidrhost(subnet.cidr_range, 0))
    ])

    error_message = "Each subnet key must be a valid lowercase name, and each cidr_range must be a valid CIDR block."
  }
}

variable "firewall_rules" {
  description = "Map of ingress firewall rules to create."
  type = map(object({
    description   = optional(string)
    source_ranges = list(string)
    target_tags   = optional(list(string), [])
    allow = list(object({
      protocol = string
      ports    = optional(list(string))
    }))
  }))

  default = {}

  validation {
    condition = alltrue(flatten([
      for rule_name, rule in var.firewall_rules : [
        for source_range in rule.source_ranges :
        can(cidrhost(source_range, 0))
      ]
    ]))

    error_message = "Every firewall source range must be a valid CIDR block."
  }
}

This is more advanced than the previous labs because I am no longer passing only simple strings.

For subnets, I used:

map(object({
  cidr_range = string
  region     = optional(string)
}))

For firewall_rules, I used a more complex object structure because each firewall rule can contain:

description
source ranges
target tags
allowed protocols and ports

Child Module `variables.tf`

Inside the child module, I also declared the variables that the module expects.

File:

modules/gcp-network/variables.tf

variable "environment" {
  description = "Environment name used for resource naming."
  type        = string
}

variable "region" {
  description = "Default Google Cloud region for regional resources."
  type        = string
}

variable "network_name" {
  description = "Base name of the VPC network."
  type        = string
}

variable "subnets" {
  description = "Map of subnets to create inside the VPC."
  type = map(object({
    cidr_range = string
    region     = optional(string)
  }))
}

variable "firewall_rules" {
  description = "Map of ingress firewall rules to create."
  type = map(object({
    description   = optional(string)
    source_ranges = list(string)
    target_tags   = optional(list(string), [])
    allow = list(object({
      protocol = string
      ports    = optional(list(string))
    }))
  }))

  default = {}
}

At first, having variables in both the root module and child module felt repetitive.

But the purpose is different.

The root variables receive values from the outside, usually from terraform.tfvars.

The child module variables define the input contract of the reusable module.

The flow is:

terraform.tfvars
      ↓
root variables.tf
      ↓
root main.tf module block
      ↓
child module variables.tf
      ↓
child module main.tf resources

Child Module `main.tf`

Inside the child module, I defined the actual GCP resources.

File:

modules/gcp-network/main.tf

locals {
  final_network_name = "${var.environment}-${var.network_name}"
}

resource "google_compute_network" "vpc_network" {
  name                    = local.final_network_name
  auto_create_subnetworks = false
}

resource "google_compute_subnetwork" "subnets" {
  for_each = var.subnets

  name          = "${var.environment}-${each.key}-subnet"
  region        = coalesce(each.value.region, var.region)
  network       = google_compute_network.vpc_network.id
  ip_cidr_range = each.value.cidr_range
}

resource "google_compute_firewall" "ingress_rules" {
  for_each = var.firewall_rules

  name          = "${var.environment}-${each.key}"
  network       = google_compute_network.vpc_network.name
  description   = each.value.description
  direction     = "INGRESS"
  source_ranges = each.value.source_ranges
  target_tags   = each.value.target_tags

  dynamic "allow" {
    for_each = each.value.allow

    content {
      protocol = allow.value.protocol
      ports    = allow.value.ports
    }
  }
}

There are several important concepts here.

Using `locals`

I used a local value to build the final network name:

locals {
  final_network_name = "${var.environment}-${var.network_name}"
}

This means if:

environment  = "dev"
network_name = "network-module"

then the final network name becomes:

dev-network-module

Creating Multiple Subnets with `for_each`

Instead of creating subnet resources one by one, I used for_each.

resource "google_compute_subnetwork" "subnets" {
  for_each = var.subnets

  name          = "${var.environment}-${each.key}-subnet"
  region        = coalesce(each.value.region, var.region)
  network       = google_compute_network.vpc_network.id
  ip_cidr_range = each.value.cidr_range
}

This lets Terraform create multiple subnet resources from a map.

For example, in my terraform.tfvars, I defined:

subnets = {
  app = {
    cidr_range = "10.40.1.0/24"
  }

  db = {
    cidr_range = "10.40.2.0/24"
  }
}

Terraform then creates:

dev-app-subnet
dev-db-subnet

This is better than duplicating two separate google_compute_subnetwork blocks.

Creating Firewall Rules with `for_each`

I also used for_each for firewall rules.

resource "google_compute_firewall" "ingress_rules" {
  for_each = var.firewall_rules

  name          = "${var.environment}-${each.key}"
  network       = google_compute_network.vpc_network.name
  description   = each.value.description
  direction     = "INGRESS"
  source_ranges = each.value.source_ranges
  target_tags   = each.value.target_tags

  dynamic "allow" {
    for_each = each.value.allow

    content {
      protocol = allow.value.protocol
      ports    = allow.value.ports
    }
  }
}

This allows me to define firewall rules from a map instead of hardcoding each rule directly in the module.

Using a Dynamic Block

The firewall rule uses a dynamic block:

dynamic "allow" {
  for_each = each.value.allow

  content {
    protocol = allow.value.protocol
    ports    = allow.value.ports
  }
}

I used this because a firewall rule can allow multiple protocols.

For example, the internal rule allows:

TCP
UDP
ICMP

Instead of hardcoding multiple allow blocks, the dynamic block generates them from the input value.

Child Module Outputs

The child module also exposes outputs.

File:

modules/gcp-network/outputs.tf

output "network_name" {
  description = "The name of the VPC network."
  value       = google_compute_network.vpc_network.name
}

output "network_id" {
  description = "The ID of the VPC network."
  value       = google_compute_network.vpc_network.id
}

output "network_self_link" {
  description = "The self-link of the VPC network."
  value       = google_compute_network.vpc_network.self_link
}

output "subnets" {
  description = "Subnets created by this module."

  value = {
    for subnet_key, subnet in google_compute_subnetwork.subnets :
    subnet_key => {
      name       = subnet.name
      id         = subnet.id
      region     = subnet.region
      cidr_range = subnet.ip_cidr_range
      self_link  = subnet.self_link
    }
  }
}

output "firewall_rules" {
  description = "Firewall rules created by this module."

  value = {
    for rule_key, rule in google_compute_firewall.ingress_rules :
    rule_key => {
      name          = rule.name
      id            = rule.id
      source_ranges = rule.source_ranges
      target_tags   = rule.target_tags
    }
  }
}

These outputs allow the root module to consume and display the values created inside the child module.

Root Outputs

The root module then exposes selected module outputs.

File:

outputs.tf

output "network_name" {
  description = "The VPC network name created by the network module."
  value       = module.network.network_name
}

output "network_id" {
  description = "The VPC network ID created by the network module."
  value       = module.network.network_id
}

output "subnets" {
  description = "Subnets created by the network module."
  value       = module.network.subnets
}

output "firewall_rules" {
  description = "Firewall rules created by the network module."
  value       = module.network.firewall_rules
}

output "lab_summary" {
  description = "Summary of this module-based network lab."

  value = {
    project        = var.project
    environment    = var.environment
    region         = var.region
    network_name   = module.network.network_name
    subnet_count   = length(module.network.subnets)
    firewall_count = length(module.network.firewall_rules)
  }
}

The root output references the child module output like this:

module.network.network_name

This means:

Get the network_name output from the network module.

`terraform.tfvars`

For local values, I used terraform.tfvars.

project      = "terraform-gcp-learning-lab"
region       = "asia-southeast2"
environment  = "dev"
network_name = "network-module"

subnets = {
  app = {
    cidr_range = "10.40.1.0/24"
  }

  db = {
    cidr_range = "10.40.2.0/24"
  }
}

firewall_rules = {
  allow-iap-ssh = {
    description   = "Allow SSH through IAP only."
    source_ranges = ["35.235.240.0/20"]
    target_tags   = ["iap-ssh"]

    allow = [
      {
        protocol = "tcp"
        ports    = ["22"]
      }
    ]
  }

  allow-internal = {
    description   = "Allow internal traffic between lab subnets."
    source_ranges = ["10.40.0.0/16"]

    allow = [
      {
        protocol = "tcp"
        ports    = ["0-65535"]
      },
      {
        protocol = "udp"
        ports    = ["0-65535"]
      },
      {
        protocol = "icmp"
      }
    ]
  }
}

This creates:

one VPC
two subnets
two firewall rules

The IAP SSH source range is:

35.235.240.0/20

This is used for Identity-Aware Proxy TCP forwarding.

I used this instead of opening SSH to:

0.0.0.0/0

because opening SSH to the whole internet is not a good habit.

Initialize Terraform

After preparing the files, I ran:

terraform init

Because this lab uses a module, Terraform also initialized the module.

The expected output includes something like:

Initializing modules...
- network in modules/gcp-network

This is different from the previous labs.

Previously, Terraform initialized only the backend and provider.

Now, Terraform also recognizes the local child module.

Format and Validate

Because this lab has Terraform files inside the module folder, I used:

terraform fmt -recursive

Then I validated the configuration:

terraform validate

Expected output:

Success! The configuration is valid.

Plan

Next, I ran:

terraform plan

The expected plan was:

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

Terraform planned to create:

module.network.google_compute_network.vpc_network
module.network.google_compute_subnetwork.subnets["app"]
module.network.google_compute_subnetwork.subnets["db"]
module.network.google_compute_firewall.ingress_rules["allow-iap-ssh"]
module.network.google_compute_firewall.ingress_rules["allow-internal"]

This is an important difference.

Previously, resource addresses looked like this:

google_compute_network.vpc_network

Now, because the resource is created inside a module, the address starts with:

module.network

For example:

module.network.google_compute_network.vpc_network

This means the resource is managed inside the network module.

Apply

After reviewing the plan, I applied the configuration:

terraform apply

Then I typed:

yes

Terraform created the resources successfully.

Terraform Output

After the apply completed, I checked the outputs:

terraform output

The result was:

firewall_rules = {
  "allow-iap-ssh" = {
    "id" = "projects/terraform-gcp-learning-lab/global/firewalls/dev-allow-iap-ssh"
    "name" = "dev-allow-iap-ssh"
    "source_ranges" = toset([
      "35.235.240.0/20",
    ])
    "target_tags" = toset([
      "iap-ssh",
    ])
  }
  "allow-internal" = {
    "id" = "projects/terraform-gcp-learning-lab/global/firewalls/dev-allow-internal"
    "name" = "dev-allow-internal"
    "source_ranges" = toset([
      "10.40.0.0/16",
    ])
    "target_tags" = toset(null) /* of string */
  }
}
lab_summary = {
  "environment" = "dev"
  "firewall_count" = 2
  "network_name" = "dev-network-module"
  "project" = "terraform-gcp-learning-lab"
  "region" = "asia-southeast2"
  "subnet_count" = 2
}
network_id = "projects/terraform-gcp-learning-lab/global/networks/dev-network-module"
network_name = "dev-network-module"
subnets = {
  "app" = {
    "cidr_range" = "10.40.1.0/24"
    "id" = "projects/terraform-gcp-learning-lab/regions/asia-southeast2/subnetworks/dev-app-subnet"
    "name" = "dev-app-subnet"
    "region" = "asia-southeast2"
    "self_link" = "https://www.googleapis.com/compute/v1/projects/terraform-gcp-learning-lab/regions/asia-southeast2/subnetworks/dev-app-subnet"
  }
  "db" = {
    "cidr_range" = "10.40.2.0/24"
    "id" = "projects/terraform-gcp-learning-lab/regions/asia-southeast2/subnetworks/dev-db-subnet"
    "name" = "dev-db-subnet"
    "region" = "asia-southeast2"
    "self_link" = "https://www.googleapis.com/compute/v1/projects/terraform-gcp-learning-lab/regions/asia-southeast2/subnetworks/dev-db-subnet"
  }
}

The output confirms that Terraform created:

one VPC network
two subnets
two firewall rules

The lab_summary output is especially useful because it gives a quick summary:

firewall_count = 2
subnet_count   = 2
network_name   = "dev-network-module"

Verify the VPC in Google Cloud

I also verified the VPC using the Google Cloud CLI.

gcloud compute networks list --filter="name=dev-network-module"

Output:

NAME                SUBNET_MODE  BGP_ROUTING_MODE  IPV4_RANGE  GATEWAY_IPV4  INTERNAL_IPV6_RANGE
dev-network-module  CUSTOM       REGIONAL

This confirms that the VPC network was created in custom subnet mode.

Verify the Subnets

Then I checked the subnets:

gcloud compute networks subnets list \
  --filter="network:dev-network-module"

Output:

NAME            REGION           NETWORK             RANGE         STACK_TYPE  IPV6_ACCESS_TYPE  INTERNAL_IPV6_PREFIX  EXTERNAL_IPV6_PREFIX  UTILIZATION_DETAILS
dev-app-subnet  asia-southeast2  dev-network-module  10.40.1.0/24  IPV4_ONLY
dev-db-subnet   asia-southeast2  dev-network-module  10.40.2.0/24  IPV4_ONLY

This confirms that both subnets were created:

Subnet	CIDR Range
`dev-app-subnet`	`10.40.1.0/24`
`dev-db-subnet`	`10.40.2.0/24`

Verify Remote State

Because this lab uses the GCS backend, I verified the remote state file:

gcloud storage ls gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/05-gcp-network-module/

Output:

gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/05-gcp-network-module/default.tfstate

This confirms that the Terraform state is stored in Google Cloud Storage.

Destroy

Because this is still a learning lab, I destroyed the resources after testing:

terraform destroy

Then I typed:

yes

Terraform destroyed the resources managed by this lab.

The GCS state bucket was not destroyed because it was created outside this Terraform configuration.

What I Learned

This lab helped me understand Terraform modules much better.

Previously, I created infrastructure directly in the root configuration.

Now, I separated the configuration into two layers:

Root module = decides what to deploy
Child module = defines how to deploy it

The root module calls the child module:

module "network" {
  source = "./modules/gcp-network"
}

The child module creates the actual resources:

VPC
subnets
firewall rules

Terraform tfvars and Safer Variable Values

Abraham Naiborhu — Sat, 09 May 2026 07:07:52 +0000

In the previous lab, I configured Terraform remote state using Google Cloud Storage. I like that, but there was still one part of the workflow that i think can be automated.

Every time I ran:

terraform plan

or:

terraform apply

Terraform asked me to manually enter the Google Cloud project ID. I don't like that. So in this lab, I will improve the configuration by introducing:

terraform.tfvars
terraform.tfvars.example
safer GitHub patterns
variable validation
cleaner environment-based naming

The goal is not only to make Terraform stop asking for the project ID manually.

The goal is to make the configuration cleaner, safer, and closer to how Terraform is usually managed in a real project.

Reference: terraform website

Goals

The goals for this lab are simple:

Use terraform.tfvars to provide local variable values.
Stop typing the project ID manually during terraform plan and terraform apply.
Use terraform.tfvars.example as a safe template for GitHub.
Keep the real terraform.tfvars file out of version control.
Add validation rules to prevent bad variable values.
Continue using Google Cloud Storage as the remote backend.

Previous Problem

In the previous configuration, I declared the project variable like this:

variable "project" {
  description = "The Google Cloud project ID where resources will be created."
  type        = string
}

Because this variable does not have a default value, Terraform asked me to enter it manually.

For example:

terraform plan

Terraform would ask:

var.project
  The Google Cloud project ID where resources will be created.

  Enter a value:

Then I had to type:

terraform-gcp-learning-lab

The same thing happened when running:

terraform apply

This works, but it is repetitive.

A better way is to provide variable values using a terraform.tfvars file.

What is `terraform.tfvars`?

terraform.tfvars is a variable definition file.

Instead of manually typing variable values in the terminal, I can store those values in a file.

Terraform automatically loads a file named:

terraform.tfvars

when running commands like:

terraform plan
terraform apply
terraform destroy

This means I can define the values once and reuse them across Terraform commands.

Final Folder Structure

For this lab, my folder structure looks like this:

04-tfvars-safe-variable-values/
├── backend.tf
├── main.tf
├── variables.tf
├── outputs.tf
├── terraform.tfvars
├── terraform.tfvars.example
└── README.md

However, for GitHub, I should only commit:

04-tfvars-safe-variable-values/
├── backend.tf
├── main.tf
├── variables.tf
├── outputs.tf
├── terraform.tfvars.example
└── README.md

I should not commit:

terraform.tfvars

because real .tfvars files can contain environment-specific values or sensitive values.

Step 1: Configure the GCS Backend

Because the previous lab already created a GCS bucket for Terraform state, I reused the same bucket.

My state bucket is:

terraform-gcp-learning-lab-terraform-state

In backend.tf, I added:

terraform {
  backend "gcs" {
    bucket = "terraform-gcp-learning-lab-terraform-state"
    prefix = "terraform-gcp-learning-lab/04-tfvars-safe-variable-values"
  }
}

The important part here is the prefix.

prefix = "terraform-gcp-learning-lab/04-tfvars-safe-variable-values"

This gives the lab its own remote state path.

I do not want this lab to share the same state file as the previous remote state lab. Each lab should have its own isolated state path to avoid state collision.

Step 2: Create `variables.tf`

Next, I created variables.tf.

This time, I did not only declare basic variables. I also added:

descriptions
types
default values
validation rules

variable "project" {
  description = "The Google Cloud project ID where resources will be created."
  type        = string

  validation {
    condition     = length(var.project) > 0
    error_message = "The project variable must not be empty."
  }
}

variable "region" {
  description = "The Google Cloud region where regional resources will be created."
  type        = string
  default     = "asia-southeast2"

  validation {
    condition     = contains(["asia-southeast2", "asia-southeast1", "us-central1"], var.region)
    error_message = "Region must be one of: asia-southeast2, asia-southeast1, or us-central1."
  }
}

variable "environment" {
  description = "Environment name used for resource naming."
  type        = string
  default     = "dev"

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Environment must be one of: dev, staging, or prod."
  }
}

variable "network_name" {
  description = "Base name of the VPC network."
  type        = string
  default     = "tfvars-network"

  validation {
    condition     = can(regex("^[a-z]([-a-z0-9]*[a-z0-9])?$", var.network_name))
    error_message = "Network name must use lowercase letters, numbers, and hyphens. It must start with a letter and end with a letter or number."
  }
}

variable "subnet_name" {
  description = "Base name of the subnet."
  type        = string
  default     = "tfvars-subnet"

  validation {
    condition     = can(regex("^[a-z]([-a-z0-9]*[a-z0-9])?$", var.subnet_name))
    error_message = "Subnet name must use lowercase letters, numbers, and hyphens. It must start with a letter and end with a letter or number."
  }
}

variable "subnet_cidr_range" {
  description = "The CIDR range for the subnet."
  type        = string
  default     = "10.30.0.0/24"

  validation {
    condition     = can(cidrhost(var.subnet_cidr_range, 0))
    error_message = "Subnet CIDR range must be a valid CIDR block, for example 10.30.0.0/24."
  }
}

This makes the variables more self-documenting.

For example, this is better:

variable "region" {
  description = "The Google Cloud region where regional resources will be created."
  type        = string
  default     = "asia-southeast2"
}

than only writing:

variable "region" {}

The validation rules are also useful because they help catch bad values before Terraform creates or changes infrastructure.

Step 3: Create `main.tf`

Next, I created main.tf.

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "6.8.0"
    }
  }
}

provider "google" {
  project = var.project
  region  = var.region
}

resource "google_compute_network" "vpc_network" {
  name                    = "${var.environment}-${var.network_name}"
  auto_create_subnetworks = false
}

resource "google_compute_subnetwork" "subnet" {
  name          = "${var.environment}-${var.subnet_name}"
  region        = var.region
  network       = google_compute_network.vpc_network.id
  ip_cidr_range = var.subnet_cidr_range
}

This configuration creates:

Resource	Description
`google_compute_network.vpc_network`	A custom VPC network
`google_compute_subnetwork.subnet`	A subnet inside the VPC

The naming is now controlled by variables.

For example:

name = "${var.environment}-${var.network_name}"

If:

environment  = "dev"
network_name = "tfvars-network"

then the final VPC name becomes:

dev-tfvars-network

This is better than hardcoding one static name for every environment.

Step 4: Create `outputs.tf`

I also created an outputs.tf file.

output "environment" {
  description = "The environment used for this lab."
  value       = var.environment
}

output "vpc_network_name" {
  description = "The final VPC network name."
  value       = google_compute_network.vpc_network.name
}

output "vpc_network_id" {
  description = "The VPC network ID."
  value       = google_compute_network.vpc_network.id
}

output "subnet_name" {
  description = "The final subnet name."
  value       = google_compute_subnetwork.subnet.name
}

output "subnet_cidr_range" {
  description = "The subnet CIDR range."
  value       = google_compute_subnetwork.subnet.ip_cidr_range
}

output "lab_summary" {
  description = "Summary of the Terraform tfvars lab."

  value = {
    project     = var.project
    environment = var.environment
    region      = var.region
    network     = google_compute_network.vpc_network.name
    subnet      = google_compute_subnetwork.subnet.name
    cidr        = google_compute_subnetwork.subnet.ip_cidr_range
  }
}

The lab_summary output is useful because it shows the key values from the lab in one structured output.

Step 5: Create `terraform.tfvars`

Now I created the real local values file:

touch terraform.tfvars

Inside terraform.tfvars, I added:

project           = "terraform-gcp-learning-lab"
region            = "asia-southeast2"
environment       = "dev"
network_name      = "tfvars-network"
subnet_name       = "tfvars-subnet"
subnet_cidr_range = "10.30.0.0/24"

This is the file that Terraform will automatically read.

Because of this file, Terraform no longer needs to ask me to enter the project value manually.

Step 6: Create `terraform.tfvars.example`

The real terraform.tfvars file should not be committed to GitHub.

However, I still want other people to understand what values are needed to recreate the lab.

So I created:

touch terraform.tfvars.example

Inside terraform.tfvars.example, I added:

project           = "your-gcp-project-id"
region            = "asia-southeast2"
environment       = "dev"
network_name      = "tfvars-network"
subnet_name       = "tfvars-subnet"
subnet_cidr_range = "10.30.0.0/24"

This file is safe to commit because it does not contain my actual project-specific values.

The pattern is:

Commit terraform.tfvars.example.
Do not commit terraform.tfvars.

Step 7: Update `.gitignore`

At the root of my GitHub repository, I updated .gitignore.

# Terraform local files
.terraform/
*.tfstate
*.tfstate.*

# Terraform variable files that may contain sensitive or environment-specific values
*.tfvars
*.tfvars.json

# Keep example variable files
!*.tfvars.example

# Crash logs
crash.log
crash.*.log

# macOS
.DS_Store

This makes Git ignore real .tfvars files but still allow .tfvars.example files.

This is important because .tfvars files may contain values that should not be exposed publicly.

Step 8: Initialize Terraform

After preparing the files, I initialized Terraform:

terraform init

Expected result:

Successfully configured the backend "gcs"!

This means Terraform is using the GCS backend for remote state.

Step 9: Format and Validate

Then I formatted the files:

terraform fmt

After that, I validated the configuration:

terraform validate

Expected output:

Success! The configuration is valid.

Step 10: Run `terraform plan`

Now I ran:

terraform plan

This time, Terraform did not ask me to manually enter the project value.

That is because Terraform automatically loaded the value from:

terraform.tfvars

Expected plan summary:

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

Terraform planned to create:

one custom VPC network
one subnet

This is the first improvement of the lab.

The workflow is now cleaner because the repeated variable values are stored in a local .tfvars file.

Step 11: Test Variable Validation

Before applying the configuration, I tested the validation rules.

First, I intentionally changed the environment value in terraform.tfvars.

environment = "development"

Then I ran:

terraform plan

Terraform returned a validation error because the accepted values are only:

dev
staging
prod

The expected error is:

Environment must be one of: dev, staging, or prod.

After testing, I changed it back:

environment = "dev"

Then I tested the subnet CIDR validation.

I changed:

subnet_cidr_range = "10.30.0.0/24"

to:

subnet_cidr_range = "not-a-cidr"

Then I ran:

terraform plan

Terraform returned an error because the value was not a valid CIDR block.

The expected error is:

Subnet CIDR range must be a valid CIDR block, for example 10.30.0.0/24.

After testing, I changed it back:

subnet_cidr_range = "10.30.0.0/24"

This is the second improvement of the lab.

Terraform does not only accept values from terraform.tfvars. It can also validate whether the values are acceptable before creating infrastructure.

Step 12: Apply the Configuration

After confirming that the validation works, I applied the configuration:

terraform apply

Terraform showed the execution plan and asked for confirmation.

I typed:

yes

Expected result:

Apply complete! Resources: 2 added, 0 changed, 0 destroyed.

Terraform also displayed the outputs:

Outputs:

environment = "dev"
subnet_cidr_range = "10.30.0.0/24"
subnet_name = "dev-tfvars-subnet"
vpc_network_name = "dev-tfvars-network"

lab_summary = {
  "cidr" = "10.30.0.0/24"
  "environment" = "dev"
  "network" = "dev-tfvars-network"
  "project" = "terraform-gcp-learning-lab"
  "region" = "asia-southeast2"
  "subnet" = "dev-tfvars-subnet"
}

The exact output may look slightly different depending on the project and Terraform output order.

Step 13: Verify Remote State

Because this lab uses the GCS backend, I verified that the remote state was created in the correct path.

gcloud storage ls gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/04-tfvars-safe-variable-values/

Expected output:

gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/04-tfvars-safe-variable-values/default.tfstate

This confirms that the lab still uses remote state, but now with cleaner variable handling.

Step 14: Query Outputs

I can query all outputs:

terraform output

I can also query the summary output:

terraform output lab_summary

Or get the output in JSON format:

terraform output -json

The JSON output can be useful when Terraform output needs to be consumed by another tool or script.

Step 15: Destroy the Infrastructure

Because this is only a learning lab, I destroyed the resources after testing:

terraform destroy

Terraform showed the destroy plan and asked for confirmation.

I typed:

yes

Expected result:

Destroy complete! Resources: 2 destroyed.

The GCS bucket is not destroyed because it was not created by this Terraform configuration.

What I Learned

The main lesson from this lab is that Terraform variable management is not only about convenience.

At first, I only wanted to avoid typing the project ID repeatedly.

But after adding terraform.tfvars, terraform.tfvars.example, .gitignore, and validation rules, I realized that variable management also affects:

safety
repeatability
collaboration
repository hygiene
infrastructure naming consistency

Next Step

This lab improved the variable workflow.

The next logical step is to make the Terraform configuration reusable by introducing modules.

So far, every lab defines resources directly in the root configuration.

In the next lab, I want to learn how to turn the VPC and subnet configuration into a reusable Terraform module.

Storing Terraform State in Google Cloud Storage

Abraham Naiborhu — Thu, 07 May 2026 08:19:10 +0000

Again with another journey of mine!
In my previous Terraform labs, I created Google Cloud resources using Terraform with local state. By default, Terraform stores state locally in a file called:

terraform.tfstate

Previously, we are doing this locally, and now i want to try it in GCS (google cloud storage) to store my remote state.

In this article, I will move from local Terraform state to remote state using Google Cloud Storage. Thus, my goal is to use the remote state using Google Cloud Storage.

What This Lab Creates

We will create:

a Google Cloud Storage bucket for Terraform state
a Terraform GCS backend configuration
a custom VPC network
a custom subnet
a remote Terraform state file stored in GCS

My state bucket name is:

terraform-gcp-learning-lab-terraform-state

The state path in the bucket is:

terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/03-remote-state-gcs/default.tfstate

Why Remote State Matters

Terraform state is important because it tracks the relationship between Terraform configuration and real infrastructure.

For example, when Terraform creates a VPC, it stores information about that VPC in the state file.

So, when i run:

terraform plan

Terraform compares:

my current Terraform configuration
the current state
the real infrastructure in Google Cloud

Then Terraform decides what needs to be created, changed, or destroyed.

This is why state management is important.

If I only store state locally, it becomes harder to collaborate, recover, or operate Terraform safely.

Using Google Cloud Storage as the backend helps move the state file away from my local laptop and into a remote location.

Step 1: Set Environment Variables

First, I set the environment variables for my project, state bucket, and region.

export PROJECT_ID=terraform-gcp-learning-lab
export STATE_BUCKET="${PROJECT_ID}-terraform-state"
export REGION="asia-southeast2"

In my case:

PROJECT_ID = terraform-gcp-learning-lab
STATE_BUCKET = terraform-gcp-learning-lab-terraform-state
REGION = asia-southeast2

I used asia-southeast2 because this is the Jakarta region and currently I am in Jakarta.

Step 2: Create the GCS Bucket

Next, I created the Google Cloud Storage bucket that will store the Terraform state.

gcloud storage buckets create gs://${STATE_BUCKET} \
  --project=${PROJECT_ID} \
  --location=${REGION} \
  --uniform-bucket-level-access

This creates a GCS bucket with uniform bucket-level access enabled.

Uniform bucket-level access means access control is managed at the bucket level using IAM, instead of mixing IAM and object-level ACLs.

Step 3: Enable Bucket Versioning

After creating the bucket, I enabled versioning.

gcloud storage buckets update gs://${STATE_BUCKET} \
  --versioning

This is useful because Terraform state is important. So if you change it or remove it, you can go back to the previous version anytime you want.

If the state file is accidentally overwritten, bucket versioning can help provide a recovery path.

Step 3: Enable Bucket Versioning

After creating the bucket, I enabled versioning.

gcloud storage buckets update gs://${STATE_BUCKET} \
  --versioning

This is useful because Terraform state is important.

If the state file is accidentally overwritten, bucket versioning can help provide a recovery path.

I created a new folder for this lab:

mkdir 03-remote-state-gcs
cd 03-remote-state-gcs

Then I created the Terraform files:

touch backend.tf main.tf variables.tf outputs.tf

The folder structure looks like this:

03-remote-state-gcs/
├── backend.tf
├── main.tf
├── variables.tf
└── outputs.tf

Step 5: Configure the GCS Backend

The backend configuration tells Terraform where to store state.

In backend.tf, I added:

terraform {
  backend "gcs" {
    bucket = "terraform-gcp-learning-lab-terraform-state"
    prefix = "terraform-gcp-learning-lab/03-remote-state-gcs"
  }
}

The bucket is the GCS bucket name.

The prefix is the path inside the bucket where Terraform will store the state file.

In this lab, Terraform will store the state at:

gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/03-remote-state-gcs/default.tfstate

One important note:

Backend configuration cannot use normal Terraform variables like this:

bucket = var.bucket_name

That is because Terraform needs to configure the backend before it evaluates variables.

So for this beginner lab, I hardcoded the bucket name directly inside backend.tf.

Step 6: Create `variables.tf`

Next, I created the input variables.

variable "project" {
  description = "The Google Cloud project ID where resources will be created."
  type        = string
}

variable "region" {
  description = "The Google Cloud region where regional resources will be created."
  type        = string
  default     = "asia-southeast2"
}

variable "network_name" {
  description = "The name of the VPC network."
  type        = string
  default     = "remote-state-network"
}

variable "subnet_name" {
  description = "The name of the subnet."
  type        = string
  default     = "remote-state-subnet"
}

variable "subnet_cidr_range" {
  description = "The CIDR range for the subnet."
  type        = string
  default     = "10.20.0.0/24"
}

The project variable does not have a default value.

This means Terraform will ask me to provide the project ID when running commands such as:

terraform plan

or:

terraform apply

Step 7: Create `main.tf`

This is my main.tf:

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "6.8.0"
    }
  }
}

provider "google" {
  project = var.project
  region  = var.region
}

resource "google_compute_network" "vpc_network" {
  name                    = var.network_name
  auto_create_subnetworks = false
}

resource "google_compute_subnetwork" "subnet" {
  name          = var.subnet_name
  region        = var.region
  network       = google_compute_network.vpc_network.id
  ip_cidr_range = var.subnet_cidr_range
}

This configuration creates two resources:

Resource	Description
`google_compute_network.vpc_network`	Custom VPC network
`google_compute_subnetwork.subnet`	Subnet inside the VPC

I set:

auto_create_subnetworks = false

because I want to create a custom mode VPC.

That means the subnet is created explicitly by Terraform instead of being automatically created by Google Cloud.

Step 8: Create `outputs.tf`

I also created a simple outputs.tf file to display useful information after the resources are created.

output "vpc_network_name" {
  description = "The name of the VPC network."
  value       = google_compute_network.vpc_network.name
}

output "vpc_network_id" {
  description = "The ID of the VPC network."
  value       = google_compute_network.vpc_network.id
}

output "subnet_name" {
  description = "The name of the subnet."
  value       = google_compute_subnetwork.subnet.name
}

output "subnet_cidr_range" {
  description = "The CIDR range of the subnet."
  value       = google_compute_subnetwork.subnet.ip_cidr_range
}

These outputs make it easier to see selected infrastructure information after running terraform apply.

Step 9: Initialize Terraform

Before applying the configuration, I initialized Terraform.

terraform init

This command initializes the working directory, downloads the provider, and configures the GCS backend.

The important part is this:

Successfully configured the backend "gcs"!

This means Terraform is now configured to store state in Google Cloud Storage.

Step 10: Format and Validate

After initialization, I formatted the Terraform files:

terraform fmt

Then I validated the configuration:

terraform validate

Expected output:

Success! The configuration is valid.

Step 11: Run Terraform Plan

Next, I reviewed the execution plan:

terraform plan

Because the project variable does not have a default value, Terraform asked me to enter it:

var.project
  The Google Cloud project ID where resources will be created.

  Enter a value:

I entered:

terraform-gcp-learning-lab

Terraform then generated a plan.

Expected result:

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

Terraform planned to create:

one VPC network
one subnet

Step 12: Apply the Configuration

After reviewing the plan, I applied the configuration:

terraform apply

Terraform asked for the project value again.

I entered:

terraform-gcp-learning-lab

Then Terraform asked for confirmation:

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value:

I typed:

yes

After the apply finished, Terraform created the VPC and subnet.

Step 13: Verify the State File in GCS

After applying the configuration, I checked the bucket.

The state file was created under this path:

terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/03-remote-state-gcs/default.tfstate

This confirms that Terraform state is now stored in Google Cloud Storage.

To check it using the CLI:

gcloud storage ls gs://${STATE_BUCKET}/terraform-gcp-learning-lab/03-remote-state-gcs/

Expected output:

gs://terraform-gcp-learning-lab-terraform-state/terraform-gcp-learning-lab/03-remote-state-gcs/default.tfstate

This is the key result of the lab.

The infrastructure is still managed by Terraform, but the state is no longer stored only as a local terraform.tfstate file.

Step 14: Query the Outputs

I can still query outputs normally:

terraform output

Even though the state is remote, Terraform commands still work from my local terminal.

The difference is that Terraform reads and writes state from the GCS backend.

Step 15: Destroy the Infrastructure

Because this is only a learning lab, I destroyed the resources after testing:

terraform destroy

Terraform asked for the project value again.

Then it showed the destroy plan.

I typed:

yes

This destroyed the VPC and subnet managed by Terraform.

Important note:

This does not delete the GCS bucket because the bucket was created manually using gcloud, not by this Terraform configuration.

What I Learned

In this lab, I learned that Terraform state is one of the most important parts of Terraform.

Previously, my Terraform state was stored locally.

After this lab, my Terraform state is stored remotely in Google Cloud Storage.

Next Step

This lab still asks me to enter the project variable manually.

In the next article, I want to improve the workflow by using:

terraform.tfvars
cleaner variable values
safer GitHub patterns using terraform.tfvars.example

That should make the Terraform workflow more practical and less repetitive.

Terraform Outputs on GCP: Querying Useful Data from a VPC, Subnet, and VM

Abraham Naiborhu — Tue, 05 May 2026 16:08:17 +0000

Hi, we are back again. Previously, I created a simple Google Cloud VPC and then improved the configuration by introducing variables.

This time, I want to continue with another Terraform concept: outputs. But, we will not be using the previous code, because adding outputs for one vpc is too simple. So, I made the lab slightly more practical.

In this lab, I will create:

a custom VPC network
a subnet with a defined CIDR range
a small Compute Engine VM
Terraform outputs to query useful information after provisioning

The goal is to understand how Terraform outputs can expose important infrastructure data after resources are created.

Reference: Hasicorp website about gcp tutorial

Why Outputs Matter

When Terraform creates infrastructure, it stores a lot of resource data in the state file. However, as users, we usually do not need to read everything.

Most of the time, we only care about specific values, such as:

the VM internal IP address
the VPC name
the subnet CIDR range
the VM self-link
a structured summary of the created resources

This is where outputs are useful.

Outputs allow us to expose selected resource information after terraform apply.

They can also be queried later using:

terraform output

What This Lab Builds

This lab creates three Google Cloud resources:

Resource	Purpose
`google_compute_network.vpc_network`	Custom VPC network
`google_compute_subnetwork.subnet`	Regional subnet inside the VPC
`google_compute_instance.vm_instance`	Small Compute Engine VM inside the subnet

The VM will be created without an external public IP address.

This happens because the network_interface block does not include an access_config block.

For this lab, that is fine because the goal is not to SSH into the VM or expose an application. The goal is to learn how Terraform outputs work.

Create a new lab folder

Because this is a new lab, I created a new folder.

mkdir learn-terraform-gcp-lab-output
cd learn-terraform-gcp-lab-output

Then create three files:

touch main.tf variables.tf outputs.tf

The folder should look like this:

learn-terraform-gcp-lab-output/
├── main.tf
├── variables.tf
└── outputs.tf

Create `variables.tf`

First, open variables.tf.

nano variables.tf

Then add the following variable declarations:

variable "project" {
  description = "The Google Cloud project ID where resources will be created."
  type        = string
}

variable "region" {
  description = "The Google Cloud region where regional resources will be created."
  type        = string
  default     = "us-central1"
}

variable "zone" {
  description = "The Google Cloud zone where the VM instance will be created."
  type        = string
  default     = "us-central1-c"
}

variable "network_name" {
  description = "The name of the VPC network."
  type        = string
  default     = "terraform-output-network"
}

variable "subnet_name" {
  description = "The name of the subnet."
  type        = string
  default     = "terraform-output-subnet"
}

variable "subnet_cidr_range" {
  description = "The CIDR range for the subnet."
  type        = string
  default     = "10.10.0.0/24"
}

variable "instance_name" {
  description = "The name of the Compute Engine VM instance."
  type        = string
  default     = "terraform-output-vm"
}

variable "machine_type" {
  description = "The machine type for the Compute Engine VM instance."
  type        = string
  default     = "e2-micro"
}

This file only declares the input variables Terraform can accept.

The important distinction is:

variables.tf declares input variables.
main.tf uses those variables.
outputs.tf exposes selected resource data after apply.

Create `main.tf`

Next, open main.tf.

nano main.tf

Then add the following Terraform configuration:

terraform {
  required_providers {
    google = {
      source  = "hashicorp/google"
      version = "6.8.0"
    }
  }
}

provider "google" {
  project = var.project
  region  = var.region
  zone    = var.zone
}

resource "google_compute_network" "vpc_network" {
  name                    = var.network_name
  auto_create_subnetworks = false
}

resource "google_compute_subnetwork" "subnet" {
  name          = var.subnet_name
  region        = var.region
  network       = google_compute_network.vpc_network.id
  ip_cidr_range = var.subnet_cidr_range
}

resource "google_compute_instance" "vm_instance" {
  name         = var.instance_name
  machine_type = var.machine_type
  zone         = var.zone

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-12"
    }
  }

  network_interface {
    subnetwork = google_compute_subnetwork.subnet.id
  }
}

Understanding `main.tf`

Google Provider

The provider block tells Terraform which Google Cloud project, region, and zone to use.

provider "google" {
  project = var.project
  region  = var.region
  zone    = var.zone
}

The values come from the variables declared in variables.tf.

Custom VPC Network

resource "google_compute_network" "vpc_network" {
  name                    = var.network_name
  auto_create_subnetworks = false
}

This creates a custom VPC network.

The important part is:

auto_create_subnetworks = false

This means Google Cloud will not automatically create subnets for us.

Instead, we will define our own subnet manually.

Subnet

resource "google_compute_subnetwork" "subnet" {
  name          = var.subnet_name
  region        = var.region
  network       = google_compute_network.vpc_network.id
  ip_cidr_range = var.subnet_cidr_range
}

This creates a subnet inside the VPC.

The subnet uses this CIDR range:

10.10.0.0/24

This value comes from:

var.subnet_cidr_range

Compute Engine VM

resource "google_compute_instance" "vm_instance" {
  name         = var.instance_name
  machine_type = var.machine_type
  zone         = var.zone

  boot_disk {
    initialize_params {
      image = "debian-cloud/debian-12"
    }
  }

  network_interface {
    subnetwork = google_compute_subnetwork.subnet.id
  }
}

This creates a small Compute Engine VM using:

e2-micro

The VM is attached to the subnet using:

subnetwork = google_compute_subnetwork.subnet.id

Because there is no access_config block, this VM does not get an external public IP address.

It only receives an internal IP address from the subnet.

Create `outputs.tf`

Now we create the output definitions.

Open outputs.tf.

nano outputs.tf

Then add:

output "vpc_network_name" {
  description = "The name of the VPC network created by Terraform."
  value       = google_compute_network.vpc_network.name
}

output "vpc_network_id" {
  description = "The ID of the VPC network created by Terraform."
  value       = google_compute_network.vpc_network.id
}

output "subnet_name" {
  description = "The name of the subnet created by Terraform."
  value       = google_compute_subnetwork.subnet.name
}

output "subnet_cidr_range" {
  description = "The CIDR range of the subnet created by Terraform."
  value       = google_compute_subnetwork.subnet.ip_cidr_range
}

output "vm_instance_name" {
  description = "The name of the VM instance created by Terraform."
  value       = google_compute_instance.vm_instance.name
}

output "vm_instance_zone" {
  description = "The zone where the VM instance was created."
  value       = google_compute_instance.vm_instance.zone
}

output "vm_internal_ip" {
  description = "The internal IP address of the VM instance."
  value       = google_compute_instance.vm_instance.network_interface[0].network_ip
}

output "vm_self_link" {
  description = "The self-link of the VM instance."
  value       = google_compute_instance.vm_instance.self_link
}

output "lab_summary" {
  description = "A structured summary of the resources created in this lab."

  value = {
    project        = var.project
    region         = var.region
    zone           = var.zone
    vpc_name       = google_compute_network.vpc_network.name
    subnet_name    = google_compute_subnetwork.subnet.name
    subnet_cidr    = google_compute_subnetwork.subnet.ip_cidr_range
    vm_name        = google_compute_instance.vm_instance.name
    vm_internal_ip = google_compute_instance.vm_instance.network_interface[0].network_ip
  }
}

This is the main focus of the lab.

Instead of only creating resources, we are selecting which resource attributes should be easy to view after provisioning.

Format the Terraform Files

Run:

terraform fmt

This formats the Terraform configuration files.

Initialize Terraform

Run:

terraform init

This initializes the working directory and downloads the Google provider.

Validate the Configuration

Run:

terraform validate

Expected output:

Success! The configuration is valid.

Apply the Configuration

Run:

terraform apply

Because the project variable does not have a default value, Terraform will ask for it.

var.project
  The Google Cloud project ID where resources will be created.

  Enter a value:

Enter your Google Cloud project ID.

Terraform will show the execution plan.

In my case, Terraform planned to create three resources:

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

The resources were:

google_compute_network.vpc_network
google_compute_subnetwork.subnet
google_compute_instance.vm_instance

Terraform also showed that some output values were only known after apply:

vm_internal_ip = (known after apply)
vm_self_link   = (known after apply)

That makes sense because the VM internal IP and self-link do not exist until Google Cloud creates the VM.

After reviewing the plan, type:

yes

Apply Result

After Terraform finished provisioning, my output looked like this:

Apply complete! Resources: 3 added, 0 changed, 0 destroyed.

Outputs:

lab_summary = {
  "project" = "terraform-gcp-learning-lab"
  "region" = "us-central1"
  "subnet_cidr" = "10.10.0.0/24"
  "subnet_name" = "terraform-output-subnet"
  "vm_internal_ip" = "10.10.0.2"
  "vm_name" = "terraform-output-vm"
  "vpc_name" = "terraform-output-network"
  "zone" = "us-central1-c"
}
subnet_cidr_range = "10.10.0.0/24"
subnet_name = "terraform-output-subnet"
vm_instance_name = "terraform-output-vm"
vm_instance_zone = "us-central1-c"
vm_internal_ip = "10.10.0.2"
vpc_network_id = "projects/terraform-gcp-learning-lab/global/networks/terraform-output-network"
vpc_network_name = "terraform-output-network"

At this point, Terraform had created:

one VPC network
one subnet
one VM instance

It also exposed selected infrastructure data through outputs.

Query the Outputs

After apply, we can query all outputs using:

terraform output

Example output:

lab_summary = {
  "project" = "terraform-gcp-learning-lab"
  "region" = "us-central1"
  "subnet_cidr" = "10.10.0.0/24"
  "subnet_name" = "terraform-output-subnet"
  "vm_internal_ip" = "10.10.0.2"
  "vm_name" = "terraform-output-vm"
  "vpc_name" = "terraform-output-network"
  "zone" = "us-central1-c"
}
subnet_cidr_range = "10.10.0.0/24"
subnet_name = "terraform-output-subnet"
vm_instance_name = "terraform-output-vm"
vm_instance_zone = "us-central1-c"
vm_internal_ip = "10.10.0.2"
vpc_network_id = "projects/terraform-gcp-learning-lab/global/networks/terraform-output-network"
vpc_network_name = "terraform-output-network"

We can also query one specific output.

For example:

terraform output vm_internal_ip

The result:

"10.10.0.2"

This is useful because I do not need to inspect the full Terraform state just to find the VM internal IP address.

Query a Structured Output

I also created a structured output called lab_summary.

Run:

terraform output lab_summary

Example result:

{
  "project" = "terraform-gcp-learning-lab"
  "region" = "us-central1"
  "subnet_cidr" = "10.10.0.0/24"
  "subnet_name" = "terraform-output-subnet"
  "vm_internal_ip" = "10.10.0.2"
  "vm_name" = "terraform-output-vm"
  "vpc_name" = "terraform-output-network"
  "zone" = "us-central1-c"
}

This is more readable than scanning the full state file.

Output as JSON

Terraform can also return outputs in JSON format.

Run:

terraform output -json

This returns structured JSON data.

Example:

{
  "vm_internal_ip": {
    "sensitive": false,
    "type": "string",
    "value": "10.10.0.2"
  },
  "vpc_network_name": {
    "sensitive": false,
    "type": "string",
    "value": "terraform-output-network"
  }
}

We can also save the output into a JSON file:

terraform output -json > terraform-outputs.json

This can be useful when another script, pipeline, or tool needs to consume Terraform output data.

Inspect Terraform State

Outputs are useful, but they do not replace state.

Terraform still stores resource information in the state file.

To list resources tracked by Terraform, run:

terraform state list

My result:

google_compute_instance.vm_instance
google_compute_network.vpc_network
google_compute_subnetwork.subnet

Then I tried to inspect the Compute Engine instance with:

terraform state show google_compute_instance

Terraform returned an error:

Error parsing instance address: google_compute_instance

This command requires that the address references one specific instance.
To view the available instances, use "terraform state list". Please modify
the address to reference a specific instance.

This happened because google_compute_instance is only the resource type.

Terraform needs the full resource address.

The correct command is:

terraform state show google_compute_instance.vm_instance

This command showed detailed information about the VM, including:

machine type
zone
internal IP
boot disk
subnet
scheduling configuration
shielded instance configuration

This was a useful mistake because it clarified the difference between:

resource type

and:

resource address

Destroy the Infrastructure

Because this lab creates a VM, I destroyed the resources after testing.

Run:

terraform destroy

Terraform will ask for the project value again if it was not provided through another method.

Then it will show a destroy plan.

In my case, the destroy plan showed:

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

It also showed that outputs would be removed:

Changes to Outputs:
  - lab_summary       = {...} -> null
  - vm_internal_ip    = "10.10.0.2" -> null
  - vpc_network_name  = "terraform-output-network" -> null

After reviewing the destroy plan, type:

yes

Important: wait until Terraform shows:

Destroy complete! Resources: 3 destroyed.

After that, you can also verify from the Google Cloud Console that the VM, subnet, and VPC have been removed.

What I Learned

From this lab, I learned that Terraform outputs are not just decoration at the end of terraform apply.

Outputs are a clean way to expose the specific infrastructure values that matter.

Instead of manually searching through the state file or Google Cloud Console, I can query useful values directly:

terraform output
terraform output vm_internal_ip
terraform output lab_summary
terraform output -json

The most important idea for me is:

Terraform creates infrastructure, state tracks infrastructure, and outputs expose selected infrastructure data.

I also learned that outputs can be simple values or structured objects.

For example, vm_internal_ip is a simple string output, while lab_summary is a structured output that groups multiple values together.

This makes outputs useful not only for humans, but also for automation.

Next Step

This lab still asks me to manually enter the project variable during terraform apply and terraform destroy.

In the next lab, I want to improve that by using:

terraform.tfvars
terraform.tfvars.example
safer variable value management
avoiding repeated manual input

That should make the Terraform workflow cleaner and more practical.

Forem: Abraham Naiborhu

Terraform Drift Detection and Recovery on Google Cloud: Plan, Import, State, and GitHub Actions

Why I Built This Artifact

What This Project Demonstrates

Why I Created a Separate Repository

Repository Structure

Baseline Infrastructure

Remote State Design

Lab 1 — Simulating Drift

Lab 2 — Detecting Drift with Terraform Plan

Lab 3 — Using -detailed-exitcode

Lab 4 — Refresh-Only Planning

Lab 5 — Recovering from Drift

Lab 6 — Importing Existing Infrastructure

Lab 7 — State Inspection

Lab 8 — State Recovery After Accidental State Removal

Lab 9 — Scheduled Drift Detection with GitHub Actions

GitHub Issue Creation When Drift Is Detected

Authentication with Workload Identity Federation

Why I Do Not Auto-Apply Drift Fixes

What This Artifact Taught Me

What I Would Do Differently in Production

Terraform CI/CD with Google Cloud: Plan on Pull Request and Apply with Approval

Why I Built This

What v2.0 Adds

Final CI/CD Flow

Authentication Design

Why Workload Identity Federation Matters

Workflow 1 — Terraform Plan on Pull Request

Workflow 2 — Terraform Apply with Manual Approval

Why I Still Run Plan Before Apply

GitHub Environment Approval

Repository Variables

Environment tfvars Strategy

GitHub CLI Operations

Evidence From the Workflow Runs

Terraform Plan Workflow

Terraform Apply Workflow

One Warning I Noticed

What This Version Does Not Solve Yet

Final Architecture After v2.0

Runtime platform

Delivery platform

Version Timeline

Terraforming a Production-Lite GCP Web Platform: MIG, Cloud NAT, Load Balancer, and Private Backends

Why I Built This

What This Project Builds

High-Level Architecture

Architecture Diagram

What Production-Lite Means

Why Private Backend Instances Matter

Why Cloud NAT Is Needed

Why I Used a Managed Instance Group

Why I Used an External HTTP Load Balancer

Why Health Checks Matter

Application Endpoints

Repository Structure

Module Responsibilities

Root Module Composition

Network Module

Map-Based Subnets

Map-Based Firewall Rules

Firewall Rules Used

IAM Module

NAT Module

Compute Module

Load Balancer Module

Startup Script

Remote State

Git Safety

Running the Project

Configure Backend

Configure Variables

Run Terraform

Expected Output

Verification

Verifying the Infrastructure

Accessing the Private VM Through IAP

Troubleshooting Notes

Load Balancer Returns 502

Lab 3 — Using `-detailed-exitcode`