Module Sources and Variable Scope

What it is

A module is a set of Terraform files in one directory. The directory where you run Terraform is the root module; any module it calls with a module block is a child module.

The source argument tells Terraform where a child module's code lives. Variable scope describes which values a module can see: each module only sees its own variables, locals and resources.

How it works

Source types

A local path must start with ./ or ../. Without that prefix, Terraform reads the string as a registry address.

Registry addresses use the form NAMESPACE/NAME/PROVIDER. A private registry adds the hostname in front, as in HOSTNAME/NAMESPACE/NAME/PROVIDER.

Selecting a Git revision or subdirectory

For Git sources, the ref query parameter picks a branch, tag or commit. A double slash selects a subdirectory inside the repository or archive.

module "vpc" {
  source = "git::https://example.com/infra.git//modules/vpc?ref=v1.2.0"
}

The version argument does not work with Git sources; ref does that job. Page 2 of this chapter covers version for registry modules.

How Terraform installs modules

terraform init installs every module that the configuration calls. Remote modules are downloaded into the .terraform/modules directory; local path modules are used in place and not copied.

terraform init
terraform get

terraform get downloads modules only, without the rest of initialization, and terraform get -update refreshes modules already installed. When you add a module block or change its source, run terraform init again before planning.

Variable scope

A child module cannot read the caller's variables, locals or resources, and the caller cannot reach inside the child. There are no global variables.

module "network" {
  source     = "./modules/network"
  cidr_block = "10.0.0.0/16"
}

resource "aws_instance" "web" {
  ami           = var.ami_id
  instance_type = "t3.micro"
  subnet_id     = module.network.subnet_id
}

Here cidr_block must match a variable "cidr_block" in the child, and subnet_id must be declared as an output in the child. Any child variable without a default must be set in the module block.

Variable names do not leak

Two modules can each declare a variable called region without conflict, because each name exists only in its own module. A value reaches a child only when the caller passes it explicitly, for example region = var.region.

Providers are the main exception to strict isolation: by default, a child module inherits the default provider configurations of its parent. The providers argument in a module block can pass a different, aliased configuration. Reusable modules should not declare their own provider blocks, because a module that does cannot be called with count, for_each or depends_on.

How the exam asks about this

• "Terraform reports the module source modules/app as an invalid registry address." The local path needs a ./ prefix: ./modules/app.
• "A child module needs the VPC ID that the root module creates. How does it receive it?" Pass it as an argument in the module block, matching an input variable in the child.
• "How does the root module use the subnet ID a child creates?" The child declares an output, read as module.network.subnet_id.