Writing a Reusable Module
Understanding what a module is (a directory of .tf files called via a module block) is different from knowing how to write a good one. A reusable module is a small piece of infrastructure API design: you're deciding what a consumer must supply, what they may optionally override, and what they get back. Good modules are opinionated enough to remove boilerplate and enforce standards (naming, tagging, security defaults), but flexible enough not to force every consumer into edge-case workarounds. This balance is the central design tension of module authoring.
Cricket analogy: Like designing a franchise's youth academy curriculum — deciding what drills every trainee must do, what techniques they may adapt to their style, and what skills they graduate with — balancing enforced fundamentals against room for individual flair.
Standard File Layout
A conventional module directory separates concerns into main.tf (core resources), variables.tf (input declarations), outputs.tf (exposed values), and often versions.tf (required_providers and required_version constraints). Larger modules may split main.tf further by concern (e.g. networking.tf, iam.tf) but the variables.tf / outputs.tf separation is close to universal because it gives anyone reading the module an immediate, predictable place to find its public interface without reading every resource block.
Cricket analogy: Like a team's operations manual split into a match-day plan (main.tf), a player-eligibility form (variables.tf), and a post-match stats sheet (outputs.tf), so any new selector can find the roster's public interface without reading every training log.
# modules/app-service/variables.tf
variable "name" {
type = string
description = "Base name for created resources"
}
variable "vpc_id" {
type = string
}
variable "subnet_ids" {
type = list(string)
}
variable "instance_type" {
type = string
default = "t3.small"
}
variable "tags" {
type = map(string)
default = {}
}
# modules/app-service/main.tf
resource "aws_launch_template" "this" {
name_prefix = "${var.name}-"
instance_type = var.instance_type
tag_specifications {
resource_type = "instance"
tags = merge(var.tags, { Name = var.name })
}
}
resource "aws_autoscaling_group" "this" {
vpc_zone_identifier = var.subnet_ids
min_size = 1
max_size = 3
desired_capacity = 1
launch_template {
id = aws_launch_template.this.id
version = "$Latest"
}
}
# modules/app-service/outputs.tf
output "asg_name" {
value = aws_autoscaling_group.this.name
}Designing the Interface
Good variable design favors sensible defaults for anything that has a reasonable organizational standard (instance sizing, retention periods) while leaving genuinely context-specific values (like vpc_id and subnet_ids above) required, with no default, so a caller can't silently misconfigure them by accident. Validation blocks and precise type constraints (object types with optional() attributes rather than a loose any) push errors to plan time. Outputs should expose everything a reasonable caller might need to wire into another module — under-exposing outputs is one of the most common reasons people end up forking a shared module instead of composing it.
Cricket analogy: Like defaulting a net-session duration to the academy standard while requiring each trainee to specify their actual batting stance (no sensible default), with a strict eligibility check flagging errors before the trial even starts, not mid-session.
A useful litmus test when designing a module's interface: could someone unfamiliar with the module's internals use it correctly just by reading variables.tf and outputs.tf, without opening main.tf? If not, the interface probably needs clearer variable names, descriptions, or validation.
A reusable child module should almost never include its own provider blocks; it should inherit provider configuration from whatever root module calls it (or receive explicit provider configurations via the module's providers argument for advanced multi-provider cases). Hardcoding a provider block, region, or credentials inside a shared module makes it far less reusable, since callers in different accounts, regions, or organizations can't easily override it.
Cricket analogy: Like a franchise's official youth academy curriculum never dictating which specific club or country a graduate must play for — it inherits that context from whichever team recruits them, keeping the curriculum reusable across leagues and countries.
Avoid using count or conditional logic scattered across many resources inside a module as a substitute for good input design — a boolean like create_nat_gateway toggling a resource on/off is fine, but a module riddled with a dozen interacting boolean flags becomes a combinatorial nightmare to test and reason about. Consider splitting such a module into smaller, more focused modules instead.
- A reusable module is an infrastructure API: design its inputs and outputs deliberately, not incidentally.
- Standard layout splits variables.tf and outputs.tf from main.tf so the public interface is easy to find.
- Give sensible defaults to values with an organizational standard; leave genuinely context-specific values required with no default.
- Precise type constraints and validation blocks catch misuse at plan time rather than deep in apply.
- Avoid hardcoding provider configuration inside a shared module; inherit it from the caller.
- Too many interacting boolean flags inside one module is a sign it should be split into smaller, focused modules.
Practice what you learned
1. Why is separating a module's code into variables.tf, main.tf, and outputs.tf a common convention?
2. Why should a value like vpc_id in a reusable module typically be required (no default) rather than optional?
3. Why is it generally discouraged for a reusable child module to include its own provider block?
4. What is a suggested litmus test for whether a module's interface is well designed?
5. What problem arises from a module having many interacting boolean toggle variables?
Was this page helpful?
You May Also Like
Terraform Modules Explained
Modules are Terraform's mechanism for packaging and reusing configuration. This topic explains what a module is, root vs. child modules, and how module calls connect inputs, resources, and outputs.
Variables and Variable Types
Input variables let Terraform configurations be parameterized and reused across environments. This topic covers declaring variables, type constraints, defaults, validation, and how to supply values.
Outputs and Locals
Output values expose data from a module for use by callers or the CLI, while local values let you name and reuse computed expressions within a module. Together they make configurations readable and composable.
File and Directory Structure Conventions
Consistent file layout and naming conventions keep Terraform projects navigable as they grow, separating variables, outputs, providers, and resources predictably.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAnsible Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics