Terraform Modules: Sourcing, Using, and Versioning Explained

A module is a container for multiple resources that are used together — a set of .tf files kept in a single directory. Modules are Terraform's primary unit of reuse and abstraction: instead of copy-pasting the same VPC, cluster, or database wiring into every configuration, you write it once as a module and call it wherever you need it.

Every Terraform configuration has at least one module, the root module, which consists of the .tf files in the directory where you run Terraform commands. A module that another module calls is a child module. Child modules can call further modules, forming a tree, though HashiCorp recommends keeping the hierarchy flat — a deeply nested module tree is harder to reason about than a root module that composes several shallow children.

Structurally, a module directory conventionally contains main.tf (resources), variables.tf (input variables), and outputs.tf (output values), but Terraform does not require these filenames — it loads every .tf file in the directory. What makes a directory a module is simply that it holds Terraform configuration; what makes it a child module is that a module block calls it.

Terraform finds a module's code through the source argument, which is required in every module block. Terraform resolves it during terraform init, before it evaluates ordinary expressions, so the value must be known at init time. On Terraform 1.12, the release the 004 exam is based on, that means a literal string. Terraform 1.15 and later also accept local values and input variables declared with const = true (in version as well as source), but never an ordinary input variable, a resource attribute or any other value that is only known later. The source string's format determines the installation method:

Local paths must begin with ./ or ../ — that prefix is how Terraform tells a local directory from a registry address, so modules/network without the prefix is looked up in the registry and fails. Local-path modules are loaded in place: edits to their files take effect on the next plan with no new init. An absolute path such as /srv/tf/modules/dns is not treated as a local path: init copies it into .terraform/modules like a downloaded package, so later edits in that directory are ignored until you run init again.

Registry sources use NAMESPACE/NAME/PROVIDER on the public registry (for example hashicorp/consul/aws); a private registry or HCP Terraform prefixes a hostname, giving HOSTNAME/NAMESPACE/NAME/PROVIDER.

Git sources need either the git:: prefix or a recognised shorthand. The github.com/ORG/REPO shorthand (Bitbucket has an equivalent bitbucket.org/ORG/REPO form) clones over HTTPS; the git@github.com:ORG/REPO.git form clones over SSH, which is what you use when the runner authenticates to GitHub with an SSH key. A plain https:// URL that is not the GitHub shorthand and has no git:: prefix is treated as an HTTP source, not as a Git repository: Terraform requests the URL, follows an X-Terraform-Get header (or terraform-get meta tag) to another source address if the server returns one, and otherwise expects an archive.

For packages that keep the module in a subdirectory, append a double slash: git::https://example.com/repo.git//modules/vpc. Git sources select what to check out with the ref query parameter, not the version argument, and the choice of ref matters:

Choosing a module per environment. Because source cannot come from an ordinary variable or a conditional built on one, one configuration cannot switch a single module block between two sources at run time. Write two module blocks, each with its own literal source, and gate each one with count (for example count = var.env == "prod" ? 1 : 0), or keep separate root configurations per environment.

You use a module by writing a module block in the calling configuration. The label after module is a local name you choose; source is required; version is strongly recommended for registry sources; and every remaining argument supplies a value to one of the child module's input variables:

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

  name = "prod-vpc"
  cidr = "10.0.0.0/16"

  azs             = ["eu-west-1a", "eu-west-1b"]
  private_subnets = ["10.0.1.0/24", "10.0.2.0/24"]
}

Here name, cidr, azs, and private_subnets are not Terraform keywords — they match variable blocks declared inside the module. Passing an argument the module does not declare is an error, and omitting a required variable (one with no default) is also an error.

After adding, removing, or changing the source of a module block you must run terraform init (or terraform get) so Terraform can install the module before planning. A local-path module needs no download, but Terraform still records it in the module manifest during init.

Variables in Terraform are scoped to the module that declares them — they are not global. A child module cannot read the calling module's variables, locals, or resources, and the caller cannot reach into the child. The only interface between them is explicit: input variables in, output values out.

Inside the child module, inputs are declared with variable blocks and results are exposed with output blocks:

variable "cidr" {
  type        = string
  description = "VPC CIDR block"
}

resource "aws_vpc" "this" {
  cidr_block = var.cidr
}

output "vpc_id" {
  value = aws_vpc.this.id
}

The caller supplies cidr as an argument in the module block and reads the result with the module.NAME.OUTPUT syntax:

resource "aws_instance" "app" {
  ami           = "ami-0abcdef1234567890"
  instance_type = "t3.micro"
  subnet_id     = module.vpc.private_subnets[0]
}

output "vpc_id" {
  value = module.vpc.vpc_id
}

Note the last snippet: a child module's outputs are not automatically shown by terraform output or exposed to its caller — the root module must re-export them with its own output block. This encapsulation is the point of modules: the caller depends only on the declared interface, so the module's internals can change freely.

Nested modules follow the same rule at every level. If the root calls module "stack" and stack calls module "vpc", the root cannot set a variable of vpc directly. To get a root value into vpc, declare a variable in stack, pass the value to it from the root, then pass var.NAME on from stack's module block to a variable declared in vpc. Outputs travel back up the same way, one level at a time.

Module blocks accept four meta-arguments, the same names you know from resources: count, for_each, depends_on, and providers.

count and for_each

count and for_each create multiple instances of an entire module. With count you index instances numerically (module.net[0].vpc_id); with for_each you key them by map key or set element (module.net["eu"].vpc_id):

module "net" {
  source   = "./modules/network"
  for_each = toset(["eu", "us"])

  region_key = each.key
}

To read one output from every instance of a counted module, use a splat: module.web[*].id returns a list with one element per instance. For a for_each module, which is a map of instances, use a for expression such as [for m in module.net : m.vpc_id]. A common use of count is making a whole module optional: count = var.enable_logging ? 1 : 0 creates zero or one instance.

depends_on

depends_on on a module block makes every resource in the module wait for the listed objects. Use it only when the dependency is hidden from Terraform. It has a cost beyond ordering: Terraform treats the whole module as dependent, so plans become more conservative — whenever any object named in depends_on has changes pending in the plan, data sources inside the module are read during apply instead of plan, so more values show as known after apply (with nothing pending upstream they are still read at plan time). When possible, express the dependency by passing an attribute of the upstream object (for example the IAM role ARN or the policy ID) as an input variable; Terraform then orders only the resources that actually use it.

providers

Default (unaliased) provider configurations are inherited by child modules implicitly. Aliased configurations are never inherited — you pass them with the providers map, for example to deploy the same module into a second AWS Region:

module "dr" {
  source = "./modules/network"

  providers = {
    aws = aws.secondary
  }
}

When a child needs two configurations of the same provider, it declares them in its required_providers block with configuration_aliases, and the caller maps each one:

# in the child module
terraform {
  required_providers {
    aws = {
      source                = "hashicorp/aws"
      configuration_aliases = [aws.primary, aws.backup]
    }
  }
}

# in the root module
module "replica" {
  source = "./modules/replica"
  providers = {
    aws.primary = aws.use1
    aws.backup  = aws.euw1
  }
}

Provider configurations belong in the root module. A legacy child module that contains its own provider blocks is incompatible with count, for_each and depends_on on the module block. The fix is to remove the provider blocks from the child, keep its required_providers declaration, and configure the provider in the root (passing it implicitly or with providers).

The version argument constrains which release of a module Terraform installs — and it works only for registry sources: the public Terraform Registry, a private registry, or the HCP Terraform registry. Adding version to a module with a local, Git, HTTP, S3, or GCS source is an error; Git sources version through ?ref=, and local paths always use whatever code is on disk.

Version constraints use the same operators as provider requirements: = (exact), !=, >, >=, <, <=, and the pessimistic operator ~>, which allows only the rightmost version component to increase — ~> 5.1 accepts 5.2 but not 6.0, while ~> 5.1.0 accepts 5.1.4 but not 5.2. When multiple constraints are combined, Terraform selects the newest available version that satisfies all of them.

Prerelease versions (such as 3.4.0-rc1) are selected only by an exact constraint naming that version (version = "3.4.0-rc1"). Ranges and ~> skip them, so a constraint like ~> 3.2 resolves to the newest stable release it allows, never to a newer prerelease.

module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = ">= 5.0.0, < 6.0.0"
}

Pin versions in anything shared or production-bound. An unconstrained registry module installs the newest version at init time, so two runs of the same configuration can install different code and a new major release can break your plan without any change on your side. Note one difference from providers: the dependency lock file records provider versions, not module versions, so your version constraint is the only thing holding a module release steady. A range such as ~> 4.2 lets a fresh clone install a newer release than an existing working directory already has, even with a committed lock file. When every engineer and CI runner must install the identical release, use an exact constraint (version = "4.2.3"), and pin Git sources to a commit SHA.

Terraform installs modules during terraform init, alongside backend initialization and provider installation. Downloaded module code is cached in the .terraform/modules directory of the working directory, with a manifest mapping each module call to its source. Whenever you add a new module block or change a source or version, run init again — terraform plan will refuse to run and tell you the module is not yet installed.

terraform get does the module-download step alone, without touching the backend or providers. It is useful when iterating on module calls, but in practice terraform init is the command you run day to day and the one the workflow expects. Do not confuse it with terraform init -backend=false: that skips backend configuration but still installs providers as well as modules.

Neither command upgrades an already-installed module by default. To move to a newer version allowed by your constraint, run terraform init -upgrade (or terraform get -update), which re-checks the registry and installs the newest acceptable release. This is a favorite exam distinction: plain init keeps what is already selected; -upgrade is what actually picks up newer module and provider versions.