Terraform modules

This chapter follows Formatting and validating Terraform files. Modules are how teams share patterns—a standard VPC, a Cloud Storage bucket with logging, or an IAM layout—without copy-pasting hundreds of lines.

Root module versus child modules

Every Terraform working directory is a module. The configuration you run terraform apply in is the root module. A child module is a module called from another module via a module block.

Child modules declare input variables (their public API) and outputs (values the parent can use). Resources inside a module are namespaced: module.network.vpc_id, not a bare resource name at the root.

Keep root modules thin: environment-specific tfvars, backend, and calls into shared child modules.

Writing a child module

A minimal GCS module might look like this:

1
variable "project_id" {
2
  type = string
3
}
4

5
variable "name_suffix" {
6
  type = string
7
}
8

9
variable "location" {
10
  type = string
11
}

1
resource "google_storage_bucket" "this" {
2
  name     = "${var.project_id}-${var.name_suffix}"
3
  location = var.location
4

5
  uniform_bucket_level_access = true
6
}

1
output "bucket_name" {
2
  value = google_storage_bucket.this.name
3
}

The module directory contains its own .tf files; it does not need a separate terraform block unless you pin providers inside the module (often providers are configured only in the root).

Calling a module

From the root module:

1
module "logs" {
2
  source = "./modules/log-bucket"
3

4
  project_id  = var.project_id
5
  name_suffix = "app-logs"
6
  location    = var.region
7
}
8

9
output "log_bucket" {
10
  value = module.logs.bucket_name
11
}

Run terraform init after adding or changing source so Terraform installs the module.

Module sources

Registry modules require a version constraint:

1
module "cloud_storage" {
2
  source  = "terraform-google-modules/cloud-storage/google"
3
  version = "~> 6.0"
4

5
  names   = ["foo"]
6
  project_id = var.project_id
7
  location   = var.region
8
}

Pin versions explicitly. Floating to latest Registry releases breaks CI when upstream introduces breaking changes.

Versioning and upgrades

Tag semantic versions on internal git modules (v1.0.0) and reference them with ?ref=v1.0.0. After upgrading a module version, run terraform init -upgrade to refresh the module cache, then plan and review diffs carefully—module upgrades can replace resources if argument names changed.

Document breaking changes in module README files and changelog entries so root modules can bump version constraints deliberately.

Refactoring with moved blocks

When you rename a resource or lift configuration into a module, Terraform otherwise plans destroy/create. moved blocks (Terraform 1.1+) retarget state without recreating cloud objects:

1
moved {
2
  from = google_storage_bucket.logs
3
  to   = module.logs.google_storage_bucket.this
4
}

Apply once with the moved block present, then remove the block after state reflects the new address. Combine with State data in Terraform for import and removed when retiring resources.

Next: State data in Terraform explains backends, locking, drift, and workspaces.