Writing a Reusable Module

Analogy categoryAnalogies

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.

hcl

# 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?

Terraform Modules Explained

Workspaces for Environments

Related Study Notes in DevOps

Browse all study notes

DevOps

Nginx Study Notes

DevOps · 30 topics

DevOps

Ansible Study Notes

DevOps · 30 topics

DevOps

Advanced Kubernetes Study Notes

Kubernetes · 30 topics

DevOps

Advanced Bash Scripting Study Notes

Bash · 30 topics

DevOps

Apache Kafka Study Notes

Kafka · 30 topics

DevOps

Docker & Kubernetes Study Notes

YAML · 40 topics

Topics covered

#HCL#TerraformInfrastructureAsCodeStudyNotes#DevOps#WritingAReusableModule#Writing#Reusable#Module#Standard#StudyNotes#SkillVeris

Writing a Reusable Module