Module Inputs and Outputs

A module communicates with the outside world through exactly two channels: input variables it accepts and outputs it exposes. Everything else — its resources, its locals, its data sources — is private. Designing those two surfaces well is most of what makes a module pleasant or painful to use.

The difference between a module people adopt and one they fight is rarely the resources inside; it is the interface. A tight, well-typed, documented surface of a handful of inputs reads like a contract. Forty loosely-typed knobs read like a trap, with a thousand ways to misconfigure and no obvious right call.

Inputs as the Public API

Input variables are the module's public API. Each one carries a type, a description, and — where there is a safe default — a default value. The type turns a whole class of misuse into a plan-time error at the call site instead of a confusing failure deep in apply. The description is the documentation a caller reads to know what the input means. Treat that interface as the module's real product; the resources are an implementation detail behind it.

variable "identifier" {
  type        = string
  description = "Name for the RDS instance."
}

variable "instance_class" {
  type        = string
  description = "RDS instance class, e.g. db.t3.micro."
  default     = "db.t3.micro"
}

variable "allocated_storage" {
  type        = number
  description = "Storage in GB."
  default     = 20
}

Outputs as Return Values

Outputs are what the module promises to expose — the IDs, ARNs, and endpoints a caller needs to wire it into the rest of the system. They are the only way a parent reads anything from inside the module, which makes them a contract, not a convenience. Keep the set minimal: every output is something a consumer can come to depend on, so expose what they actually need and nothing internal.

output "endpoint" {
  value       = aws_db_instance.this.endpoint
  description = "Connection endpoint for the database."
}

output "port" {
  value       = aws_db_instance.this.port
  description = "Port the database listens on."
}

Encapsulation

Whatever the module creates inside — the RDS instance, its subnet group, its parameter group, the locals that compute names — is invisible to callers except through the outputs. A caller cannot reach module.db.aws_db_instance.this; it can only read module.db.endpoint. That wall is what lets the module change its internals freely. Rename the resource, split it in two, add a parameter group — as long as the inputs and outputs hold, no caller notices.

The corollary is that anything you expose becomes part of the contract. An internal resource reference that leaks out — a caller who learned they could read some attribute — is a dependency you now have to preserve through every refactor. Encapsulation only holds if you are disciplined about what crosses the boundary.

Sensible Defaults

The split between required and optional inputs decides how the common case reads. A required input — no default — forces every caller to supply it; an optional one with a default lets the simplest use be a single line. Get this right and the everyday call is short and the advanced call is still possible. Get it wrong by making everything required, and the simplest use of the module needs twenty arguments.

Default the values that are genuinely environment-independent — a sensible instance class, a 20 GB starting volume, a 7-day backup retention. Require the values that have no safe default, like the name or the subnet IDs the module cannot guess. The result is a module whose common case is one line and whose escape hatches are there when you need them.

Interface Stability

Inputs and outputs are a contract, so changing them is a versioning event. Adding a new optional input with a default is safe — existing callers pass the same arguments and get the same result. Removing an input, renaming one, changing its type, or dropping an output is a breaking change: it makes a caller's existing code fail or behave differently, and under SemVer it belongs in a major version bump.

This is why a small, deliberate interface ages well. The fewer inputs and outputs you commit to, the fewer things you can break later. Add optional inputs over time as real use cases arrive; resist exposing internals you might have to keep forever.