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 and must be a literal string — it cannot reference variables, because Terraform resolves sources during terraform init, before evaluating expressions. The source string's format determines the installation method:

Local paths must begin with ./ or ../ — that prefix is how Terraform distinguishes a local directory from a registry address. Registry sources use the NAMESPACE/NAME/PROVIDER format (a private registry prefixes a hostname). For packages that keep the module in a subdirectory, append a double slash: git::https://example.com/repo.git//modules/vpc. Git sources select a branch, tag, or commit with the ref query parameter, not the version argument.

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.

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

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
}

depends_on forces every resource in the module to wait for the listed objects — use it sparingly, because it hides the real dependency and blocks Terraform's normal fine-grained ordering. Prefer expressing dependencies through input and output references, which Terraform tracks automatically.

providers maps provider configurations from the caller into the child, which is how you pass an aliased configuration — for example deploying the same module into two AWS regions:

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

  providers = {
    aws = aws.secondary
  }
}

A module that uses count or for_each must not contain its own provider blocks; provider configurations belong in the root module and are passed down implicitly (by matching names) or explicitly via providers. The child declares what it needs in required_providers, including configuration_aliases when it expects an aliased configuration.

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 installed-or-available version that satisfies all of them.

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.

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 occasionally useful when iterating on module sources, but in practice terraform init is the command you run day to day and the one the workflow expects.

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.