Modules

Copied code doesn’t stay the same. Each copy gets its own fixes, at its own time, or none at all. By the third service, nobody can say which copy is the right one.

This lesson is about modules: how to write a piece of infrastructure once, use it many times, and control when a change to it reaches everyone.

A module is a folder of .tf files. That’s all. You’ve been writing one since your first resource: the folder you run terraform in is a module too.

A child module has three kinds of files, by convention:

The file names are only a habit. Terraform reads every .tf file in the folder as one.

In the story, if the repository had been a module, Maya would have added scanning and immutable tags to the module once, and the next plan would have shown the change for both repositories.

A module for QuickCart’s network

Here’s a small but real network module: a VPC, public subnets in two or three availability zones, an internet gateway, and the route that makes the subnets public. What is a VPC? explains each piece. Here we care about how it’s packaged.

The inputs first:

variable "name" {
  description = "Name prefix for every resource, like quickcart-dev"
  type        = string
}

variable "cidr_block" {
  description = "The VPC's address range, like 10.10.0.0/16"
  type        = string

  validation {
    condition     = can(cidrhost(var.cidr_block, 0))
    error_message = "cidr_block must be an IPv4 range, like 10.10.0.0/16."
  }
}

variable "zone_count" {
  description = "How many availability zones to spread the public subnets across"
  type        = number
  default     = 2

  validation {
    condition     = var.zone_count >= 2 && var.zone_count <= 3
    error_message = "zone_count must be 2 or 3."
  }
}

variable "tags" {
  description = "Extra tags to put on every resource in the module"
  type        = map(string)
  default     = {}
}

Then the resources:

data "aws_availability_zones" "available" {
  state = "available"
}

locals {
  zones = slice(data.aws_availability_zones.available.names, 0, var.zone_count)
}

resource "aws_vpc" "this" {
  cidr_block           = var.cidr_block
  enable_dns_hostnames = true

  tags = merge(var.tags, { Name = var.name })
}

resource "aws_internet_gateway" "this" {
  vpc_id = aws_vpc.this.id

  tags = merge(var.tags, { Name = "${var.name}-igw" })
}

resource "aws_subnet" "public" {
  for_each = { for index, zone in local.zones : zone => index }

  vpc_id                  = aws_vpc.this.id
  availability_zone       = each.key
  cidr_block              = cidrsubnet(var.cidr_block, 8, each.value)
  map_public_ip_on_launch = true

  tags = merge(var.tags, { Name = "${var.name}-public-${each.key}" })
}

resource "aws_route_table" "public" {
  vpc_id = aws_vpc.this.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.this.id
  }

  tags = merge(var.tags, { Name = "${var.name}-public" })
}

resource "aws_route_table_association" "public" {
  for_each = aws_subnet.public

  subnet_id      = each.value.id
  route_table_id = aws_route_table.public.id
}

And the outputs, the only values the caller can read:

output "vpc_id" {
  description = "The VPC's ID, for security groups and load balancers"
  value       = aws_vpc.this.id
}

output "public_subnet_ids" {
  description = "One public subnet ID per zone"
  value       = [for subnet in aws_subnet.public : subnet.id]
}

output "zones" {
  description = "The availability zones the subnets are in"
  value       = local.zones
}

Notice what’s not in the module: no provider block, no region, no environment name. The root module decides those. That’s what lets the same module build dev, stg and a second region in Environments and regions.

Calling the module, and composing with it

The root module calls the module with a module block, then passes one of its outputs to something else. That’s composition: small pieces, wired together in the root.

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

  name       = "quickcart-dev"
  cidr_block = "10.10.0.0/16"
  zone_count = 2

  tags = {
    Project = "quickcart"
  }
}

resource "aws_security_group" "web" {
  name        = "quickcart-dev-web"
  description = "HTTPS from anywhere to the load balancer"
  vpc_id      = module.network.vpc_id

  ingress {
    description = "HTTPS from anywhere"
    from_port   = 443
    to_port     = 443
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }

  egress {
    description = "Everything out"
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }

  tags = {
    Project = "quickcart"
  }
}

You don’t need to build this now. The lab in Environments and regions builds this exact network, three times.

Where a module can come from

The source setting says where Terraform fetches the module’s code from. Three kinds cover almost everything:

In the git source, //network means “the network folder inside that repository”, and ?ref=v1.4.0 means “at the tag v1.4.0”.

Versioning: control when a change reaches you

A shared module will change. Pinning decides when each user gets the change.

To take a newer version on purpose, change the pin in a pull request, then run terraform init -upgrade and read the plan. The change to shared code then shows up as a change in your repository, where it can be reviewed.

When not to make a module

Modules make code easier to reuse, and harder to read. A module that only wraps one resource, with an input for each of its settings, adds a layer and saves nothing.

The last row is the most common trap: one giant module that builds everything, with dozens of inputs. It becomes impossible to change safely, because every team depends on it. Several small modules, each doing one thing and composed in the root, like network.tf above, age much better.

Here is the root module calling the network module, with the security group outside it. Change one input at a time, and see which resources inside the module change, and whether the change escapes through an output. Then try reading a resource from outside.

$ terraform plan

No changes. Your infrastructure matches the configuration.

What to notice: a change only travels where the code sends it. name and tags stay inside the module. cidr_block replaces the VPC, which changes the vpc_id output, and that carries the change out to the security group. Outputs are both the module’s only way out and the path a change can escape along.

Free — two empty ECR repositories. ECR charges only for stored images, and you push none.

You’ll write a small module for an ECR repository with QuickCart’s standards built in, use it for two services, change the standard once, and watch both repositories follow. About 25 minutes.

You need Terraform 1.10 or later and a working AWS login in your terminal. Set up your computer covers both.

1. Make the folders

   TerminalCopy

   mkdir -p quickcart-modules/modules/ecr-repo

   Part	What it means
   mkdir	make a directory
   -p	make any missing parent folders too, and don’t complain if they already exist
   quickcart-modules/modules/ecr-repo	the project folder, and inside it the module’s folder

   TerminalCopy

   cd quickcart-modules

   Part	What it means
   cd quickcart-modules	move into the project folder. This is the root module; every command runs here

2. Write the module's inputs

   Create modules/ecr-repo/variables.tf:

   modules/ecr-repo/variables.tfCopy

   variable "name" {
     description = "The service's name, like orders. Lower case letters, numbers and hyphens"
     type        = string
   
     validation {
       condition     = can(regex("^[a-z][a-z0-9-]*$", var.name))
       error_message = "name must start with a lower-case letter and use only a-z, 0-9 and hyphens."
     }
   }
   
   variable "environment" {
     description = "Which environment the repository belongs to"
     type        = string
   
     validation {
       condition     = contains(["dev", "stg", "prod"], var.environment)
       error_message = "environment must be dev, stg or prod."
     }
   }
   
   variable "keep_images" {
     description = "How many images to keep. Older ones are deleted automatically"
     type        = number
     default     = 20
   
     validation {
       condition     = var.keep_images >= 1
       error_message = "keep_images must be at least 1."
     }
   }

   Setting	What it does	If you leave it out	When you’d change it
   name → type, no default	The caller must say which service this is	—	—
   name → validation	regex checks the name uses only lower-case letters, numbers and hyphens, which is what ECR accepts. can() turns a failed match into false	A bad name is only rejected by AWS, during apply	If your naming rules change
   environment → validation	contains accepts only dev, stg or prod	A typo like prd would quietly create a new, oddly named repository	When you add an environment
   keep_images → default = 20	Keep the newest 20 images unless told otherwise	Every caller would have to decide	If 20 is the wrong standard for you
   keep_images → validation	At least 1, so the policy can’t delete every image	A 0 would be rejected later by AWS with a less helpful error	Never

3. Write the module's resources and outputs

   Create modules/ecr-repo/main.tf. This is where QuickCart’s standards live:

   modules/ecr-repo/main.tfCopy

   resource "aws_ecr_repository" "this" {
     name                 = "quickcart-${var.environment}-${var.name}"
     image_tag_mutability = "IMMUTABLE"
     force_delete         = true
   
     image_scanning_configuration {
       scan_on_push = true
     }
   
     tags = {
       Project     = "quickcart"
       Environment = var.environment
       Service     = var.name
     }
   }
   
   resource "aws_ecr_lifecycle_policy" "this" {
     repository = aws_ecr_repository.this.name
   
     policy = jsonencode({
       rules = [{
         rulePriority = 1
         description  = "Keep only the newest images"
         selection = {
           tagStatus   = "any"
           countType   = "imageCountMoreThan"
           countNumber = var.keep_images
         }
         action = { type = "expire" }
       }]
     })
   }

   Setting	What it does	If you leave it out	When you’d change it
   resource "aws_ecr_repository" "this"	The repository. Inside a module that builds one of something, this is the usual name	—	—
   name	Built from the inputs: quickcart-dev-orders. The caller can’t break the naming pattern	Required	Never after creation: a new name replaces the repository
   image_tag_mutability = "IMMUTABLE"	A tag like v1 can never be moved to a different image	Defaults to MUTABLE	Rarely. Storing images: ECR explains why
   force_delete = true	terraform destroy deletes the repository even if it holds images	Destroy fails while any image is inside	Set it to false, or make it an input, for production
   image_scanning_configuration → scan_on_push	Every pushed image is checked for known vulnerabilities	Defaults to false: no scanning	Never, for QuickCart
   tags	Labels, including which service owns it	No labels	Add the tags your team requires
   aws_ecr_lifecycle_policy → repository	Which repository the policy applies to	Required	Never
   policy = jsonencode(…)	The rules, written as Terraform values and turned into the JSON that ECR expects	Required	—
   rulePriority, description	Rules run in priority order, lowest first. The description is shown in the console	Required / blank	When you add more rules
   selection → tagStatus = "any"	The rule looks at all images, tagged or not	Required	To treat untagged images differently
   countType = "imageCountMoreThan", countNumber	Match images beyond the newest keep_images	Required	—
   action → type = "expire"	Delete the matched images	Required	—

   Create modules/ecr-repo/outputs.tf:

   modules/ecr-repo/outputs.tfCopy

   output "repository_url" {
     description = "The address to push images to"
     value       = aws_ecr_repository.this.repository_url
   }

   Setting	What it does	If you leave it out	When you’d change it
   output "repository_url"	Lets the caller read the repository’s address as module.<name>.repository_url	The address can’t be read from outside the module	—
   description	Explains what the value is	Callers guess	—
   value	The address AWS gives the repository, like 111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-dev-orders	Required	—

4. Use the module twice

   Back in the project folder, create main.tf. This is the root module:

   main.tfCopy

   terraform {
     required_version = ">= 1.10.0"
   
     required_providers {
       aws = {
         source  = "hashicorp/aws"
         version = "~> 6.0"
       }
     }
   }
   
   provider "aws" {
     region = "us-east-1"
   }
   
   module "orders_repo" {
     source = "./modules/ecr-repo"
   
     name        = "orders"
     environment = "dev"
   }
   
   module "payments_repo" {
     source = "./modules/ecr-repo"
   
     name        = "payments"
     environment = "dev"
     keep_images = 10
   }

   Setting	What it does	If you leave it out	When you’d change it
   required_version, required_providers	Terraform 1.10 or later, and any 6.x AWS provider. Your first resource explains both	Terraform takes whatever it finds, which may change under you	When you upgrade on purpose
   provider "aws" → region	Where both repositories are built. The module doesn’t choose; the root does	Terraform uses your login’s default region	To build elsewhere
   module "orders_repo" / "payments_repo"	Two uses of the same module. Each has its own name, and its own resources in the state	—	One block per service
   source = "./modules/ecr-repo"	The module’s folder	Required	—
   name, environment	The two required inputs	Terraform stops: Missing required argument	—
   keep_images = 10	Payments keeps fewer images; orders takes the default 20	The default is used	Per service

   Create outputs.tf:

   outputs.tfCopy

   output "orders_repository_url" {
     description = "Where to push the orders service's images"
     value       = module.orders_repo.repository_url
   }
   
   output "payments_repository_url" {
     description = "Where to push the payments service's images"
     value       = module.payments_repo.repository_url
   }

   Setting	What it does	If you leave it out	When you’d change it
   value = module.orders_repo.repository_url	Reads the module’s output and shows it after apply	Nothing is printed; the value still exists in the state	—
   description	Explains the output	—	—

5. Initialise, plan and apply

   TerminalCopy

   terraform init

   Part	What it means
   terraform init	find the modules the code calls, download the AWS provider, and prepare the folder

   You should see

   Initializing the backend...
   
   Initializing modules...
   - orders_repo in modules/ecr-repo
   - payments_repo in modules/ecr-repo
   
   Initializing provider plugins...
   - Finding hashicorp/aws versions matching "~> 6.0"...
   - Installing hashicorp/aws v6.66.0...
   - Installed hashicorp/aws v6.66.0 (signed by HashiCorp)
   
   Terraform has been successfully initialized!

   Your provider version may be newer, and the two module lines may come in either order. There’s a new line here you haven’t seen before: Initializing modules.

   TerminalCopy

   terraform apply

   Part	What it means
   terraform apply	plan the changes, show them, and make them once you type yes

   Read the plan before you type yes. Every address now starts with the module’s name:

   Part of the plan

     # module.orders_repo.aws_ecr_lifecycle_policy.this will be created
     # module.orders_repo.aws_ecr_repository.this will be created
     # module.payments_repo.aws_ecr_lifecycle_policy.this will be created
     # module.payments_repo.aws_ecr_repository.this will be created
   
   Plan: 4 to add, 0 to change, 0 to destroy.

   Type yes.

   You should see

   module.orders_repo.aws_ecr_repository.this: Creating...
   module.payments_repo.aws_ecr_repository.this: Creating...
   module.orders_repo.aws_ecr_repository.this: Creation complete after 1s [id=quickcart-dev-orders]
   module.payments_repo.aws_ecr_repository.this: Creation complete after 1s [id=quickcart-dev-payments]
   module.orders_repo.aws_ecr_lifecycle_policy.this: Creating...
   module.payments_repo.aws_ecr_lifecycle_policy.this: Creating...
   module.orders_repo.aws_ecr_lifecycle_policy.this: Creation complete after 0s [id=quickcart-dev-orders]
   module.payments_repo.aws_ecr_lifecycle_policy.this: Creation complete after 0s [id=quickcart-dev-payments]
   
   Apply complete! Resources: 4 added, 0 changed, 0 destroyed.
   
   Outputs:
   
   orders_repository_url = "111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-dev-orders"
   payments_repository_url = "111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-dev-payments"

   Your account ID appears in place of 111122223333, and the lines may come in a different order. Two small blocks built four resources, each with scanning, immutable tags and a clean-up policy.

   AWSIn the AWS console: ECR→Private registry→Repositories

   You should see

   quickcart-dev-orders and quickcart-dev-payments, both with Tag immutability set to Immutable. Open one, and Lifecycle Policy in the left menu shows the rule.

6. Change the standard once

   A new rule arrives: every repository must carry a ManagedBy tag, so people know not to edit it by hand. You change the module, not each repository. Update the tags in modules/ecr-repo/main.tf; the whole file now reads:

   modules/ecr-repo/main.tfCopy

   resource "aws_ecr_repository" "this" {
     name                 = "quickcart-${var.environment}-${var.name}"
     image_tag_mutability = "IMMUTABLE"
     force_delete         = true
   
     image_scanning_configuration {
       scan_on_push = true
     }
   
     tags = {
       Project     = "quickcart"
       Environment = var.environment
       Service     = var.name
       ManagedBy   = "terraform"
     }
   }
   
   resource "aws_ecr_lifecycle_policy" "this" {
     repository = aws_ecr_repository.this.name
   
     policy = jsonencode({
       rules = [{
         rulePriority = 1
         description  = "Keep only the newest images"
         selection = {
           tagStatus   = "any"
           countType   = "imageCountMoreThan"
           countNumber = var.keep_images
         }
         action = { type = "expire" }
       }]
     })
   }

   Setting	What it does	If you leave it out	When you’d change it
   ManagedBy = "terraform"	The only new line: a tag every repository built by this module will carry	—	—

   TerminalCopy

   terraform plan

   Part	What it means
   terraform plan	show what would change, without changing anything

   Part of the plan

     # module.orders_repo.aws_ecr_repository.this will be updated in-place
     ~ resource "aws_ecr_repository" "this" {
           id                   = "quickcart-dev-orders"
           name                 = "quickcart-dev-orders"
         ~ tags                 = {
               "Environment" = "dev"
             + "ManagedBy"   = "terraform"
               "Project"     = "quickcart"
               "Service"     = "orders"
           }
   
     # module.payments_repo.aws_ecr_repository.this will be updated in-place
   
   Plan: 0 to add, 2 to change, 0 to destroy.

   One edit, two repositories. This is the story’s missing fix: had the payments repository come from the module, the security review’s change would have reached it too. The full plan also shows tags_all changing, which is the tags plus any the provider adds.

   Apply it, and type yes:

   TerminalCopy

   terraform apply

   Part	What it means
   terraform apply	make the tag change on both repositories

   You should see

   Apply complete! Resources: 0 added, 2 changed, 0 destroyed.

7. Watch the module refuse a bad input

   In main.tf, change the payments module’s name from "payments" to "Payments", with a capital P, then plan:

   TerminalCopy

   terraform plan

   Part	What it means
   terraform plan	check the inputs against the module’s validation rules, then plan

   Terraform stops with

   Error: Invalid value for variable
   
     on main.tf line 26, in module "payments_repo":
     26:   name        = "Payments"
       ├────────────────
       │ var.name is "Payments"
   
   name must start with a lower-case letter and use only a-z, 0-9 and hyphens.
   
   This was checked by the validation rule at
   modules/ecr-repo/variables.tf:5,3-13.

   Nothing was built or changed. The module’s author wrote that rule once, and every caller gets the check. Change the name back to "payments" before you go on.

8. Clean-up step: Clean up

   TerminalCopy

   terraform destroy

   Part	What it means
   terraform destroy	plan the removal of everything this root module built, including everything inside its modules, and do it once you type yes

   You should see

   Plan: 0 to add, 0 to change, 4 to destroy.
   
   Changes to Outputs:
     - orders_repository_url   = "111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-dev-orders" -> null
     - payments_repository_url = "111122223333.dkr.ecr.us-east-1.amazonaws.com/quickcart-dev-payments" -> null

   Type yes.

   You should see

   Destroy complete! Resources: 4 destroyed.

   AWSIn the AWS console: ECR→Private registry→Repositories

   You should see

   Neither repository is listed.

   Keep the quickcart-modules folder if you like; it costs nothing on your laptop.