Using Modules and Managing Versions

What it is

Using a module means calling it from a module block, passing it input values and reading its outputs. A module lets you package a set of resources once and reuse it across projects and environments.

Managing module versions means pinning the module code your configuration accepts, so an upstream change cannot alter your infrastructure without your approval.

How it works

Calling a module

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"

  name = "main"
  cidr = "10.0.0.0/16"
}

source and version are read by Terraform itself; name and cidr set the module's input variables. Each output of the module is available as module.vpc.OUTPUT_NAME.

Module blocks also accept the meta-arguments count, for_each, depends_on and providers, listed with the two Terraform arguments below.

Several instances with for_each

module "bucket" {
  source   = "./modules/bucket"
  for_each = toset(["logs", "assets"])
  name     = each.key
}

Each instance has its own address, such as module.bucket["logs"], and outputs are read as module.bucket["logs"].arn.

Standard module structure

HashiCorp recommends a standard layout for reusable modules.

Terraform does not require these file names; it reads every .tf file in the directory. The layout simply makes modules easier to read and lets the registry generate documentation. For composition, HashiCorp advises a flat module tree, where the root module connects small modules by passing one module's outputs into another's inputs.

Version constraints

The version argument takes a constraint string with these operators.

The ~> operator, the pessimistic constraint, allows only the rightmost version part to increase. HashiCorp advises pinning modules from outside your organization to avoid unexpected changes.

version works only with registries

The version argument applies only to modules from the public Terraform Registry or a private registry, such as the HCP Terraform private registry. For Git sources you pin with ?ref=, and local path modules have no version at all, because they are read in place.

Upgrading modules

terraform init installs the newest version that matches the constraint when no copy exists yet. Afterwards it keeps the installed version until you ask for an upgrade.

terraform init -upgrade

-upgrade checks for the newest versions of modules and providers that still match their constraints. The dependency lock file .terraform.lock.hcl records provider versions only; it does not lock module versions, so the constraint in the module block is your module pin.

How the exam asks about this

• "Which constraint lets a module take 2.3.x patches but not 2.4.0?" ~> 2.3.0.
• "Can the version argument pin a module sourced from a Git repository?" No; use ref in the source URL.
• "True or false: the dependency lock file pins module versions." False; it records provider versions only.