Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 37 ยท Modules

Terraform Modules: Your First Reusable Module

Learn what Terraform modules are, how to write one with variables and outputs, call it from a root module and pass values between modules step by step.

A configuration with one hundred resources in a single folder is hard to read and harder to reuse. A module is simply a folder of .tf files that you can call like a function: pass inputs, get outputs, and get a set of resources created. Every Terraform configuration is already a module: the folder where you run terraform apply is the root module, and any module it calls is a child module.

Modules give you three things: reuse (create ten identical queues from one definition), abstraction (hide fifteen resources behind four inputs) and consistency (every team gets the same secure defaults).

Anatomy of a module

A small module that creates a private S3 bucket lives in modules/private-bucket:

TEXT
modules/private-bucket/
  main.tf
  variables.tf
  outputs.tf
HCL
# modules/private-bucket/variables.tf
variable "name" {
  type        = string
  description = "Globally unique bucket name."
}

variable "versioned" {
  type    = bool
  default = true
}

variable "tags" {
  type    = map(string)
  default = {}
}
HCL
# modules/private-bucket/main.tf
resource "aws_s3_bucket" "this" {
  bucket = var.name
  tags   = var.tags
}

resource "aws_s3_bucket_public_access_block" "this" {
  bucket                  = aws_s3_bucket.this.id
  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

resource "aws_s3_bucket_versioning" "this" {
  bucket = aws_s3_bucket.this.id
  versioning_configuration {
    status = var.versioned ? "Enabled" : "Suspended"
  }
}
HCL
# modules/private-bucket/outputs.tf
output "arn" {
  value = aws_s3_bucket.this.arn
}

output "id" {
  value = aws_s3_bucket.this.id
}

The name this is a common convention for the single main resource in a module. Variables are the module's inputs, outputs are its return values, and everything else is private: the caller cannot reach inside to aws_s3_bucket.this directly.

Calling the module

In the root module, use a module block. The source is a local path here:

HCL
module "uploads" {
  source = "./modules/private-bucket"

  name = "acme-uploads-prod"
  tags = { team = "web" }
}

module "reports" {
  source    = "./modules/private-bucket"
  name      = "acme-reports-prod"
  versioned = false
}

output "uploads_arn" {
  value = module.uploads.arn
}

After adding or changing a module source, run terraform init (or terraform get) so Terraform can load it. The resource addresses become module.uploads.aws_s3_bucket.this and module.reports.aws_s3_bucket.this: two independent copies.

flowchart LR
  subgraph Root["Root module"]
    U["module.uploads"]
    R["module.reports"]
  end
  U --> M1["private-bucket (copy 1): 3 resources"]
  R --> M2["private-bucket (copy 2): 3 resources"]
  M1 -->|"output arn"| Root

Each module call creates a separate instance of the same definition.

Modules as functions: a stand-in

You can model a module as a function that takes inputs (with defaults) and returns outputs plus the resources it creates. This program does exactly that, so you can see the "two copies" idea and the address prefixes.

Python A module is a function

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Passing values between modules

Modules do not see each other's resources. The root module is the glue: it passes one module's output as another module's input.

HCL
module "network" {
  source = "./modules/network"
  cidr   = "10.20.0.0/16"
}

module "app" {
  source     = "./modules/app"
  subnet_ids = module.network.private_subnet_ids
  vpc_id     = module.network.vpc_id
}

Terraform builds a dependency graph from these references: module.app waits for module.network. You rarely need depends_on on a module, and it is best avoided because it widens dependencies and can force needless replacements.

Python Wiring modules by outputs

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Rules of thumb

  • Outputs are the interface. If another configuration needs an attribute, expose it as an output; do not tell people to read inner resources.
  • Required inputs have no default; optional inputs do. Good defaults mean callers pass few arguments.
  • No provider blocks inside reusable modules. Declare required_providers for version needs, and let the root module configure the provider (Providers in the earlier chapter).
  • Add description and type to every variable and output; they are your documentation and appear in generated docs.
  • Start small. A module that wraps a single resource with no added policy is usually just indirection.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is the root module?

    Every configuration is a module; the working directory is the root module.
  2. 2. How does a caller read a value created inside a child module?

    Only outputs are exposed; internal resources are private.
  3. 3. What address does a bucket resource this inside module call uploads have?

    Child resources are prefixed with module.CALL_NAME.
  4. 4. After you add a new module block with a new source, what do you run first?

    init downloads or links the module so Terraform can load it.

Summary

  • A module is a folder of Terraform files used like a function: variables in, outputs out.
  • The folder you run Terraform in is the root module; module blocks call child modules.
  • Child resources get addresses prefixed with module.NAME.
  • Connect modules in the root by passing outputs as inputs.
  • Keep modules focused, documented and free of provider configuration.

Next: Designing Good Modules