A Terraform module groups resources behind input variables and outputs. The root module composes those units and owns a particular state. A module is useful when it captures a repeated architectural decision, such as a private service endpoint, with a clear interface. Wrapping every single resource in a custom module can hide behavior without reducing risk.
Make this comfortable
Terraform modules: small interfaces and explicit state owners
Operational decision
A billing platform has one network module and one application endpoint module. Pass the network ID as an input rather than having the endpoint module discover or create an unreviewed network. Pin remote module versions; for a local source, review the same repository revision as the root configuration. The HCL sketch shows a root module call and a returned endpoint ID. It assumes a module directory with matching variables and output; it is not a full provider configuration. Document whether changing each input replaces a resource and who approves that replacement. Keep separate state units for infrastructure with different lifecycle owners, but do not pass secret values through broadly readable outputs. Use a plan to review the actual graph and retain locking for the root state. An attractive module interface does not make a destructive plan safe.
module "billing_endpoint" {
source = "./modules/private-service-endpoint"
network_id = module.billing_network.id
service_name = "billing-ledger"
owner_team = "payments-platform"
}
output "billing_endpoint_id" {
value = module.billing_endpoint.id
}Cost and verification
Modules reduce duplication but add versioning and interface maintenance. Deep nesting makes ownership and replacement behavior hard to inspect. Outputs can expose sensitive attributes in state even when marked sensitive in command output, so access to state remains important. A local module moves with the root repository; a remote module must be pinned and upgraded deliberately. Do not run parallel applies against a shared state merely because resources live in different module folders.
Common Mistakes
- Do not create an abstraction for every single resource by default.
- Do not hide resource replacement behind a harmless-looking variable name.
- Do not treat separate module folders as separate state locks.
Connected lessons
- DevOps: delivery, infrastructure, and reliable operations
- Terraform state: shared ownership and safe plans
- Configuration management: converge hosts without surprise restarts
- Cloud cost and capacity: assign an owner to each recurring resource
Advanced follow-up
Advanced follow-up
Platform operating-contract follow-up
devops
operations