Designing Terraform Modules Teams Actually Want to Reuse
Most Terraform sprawl I see comes from modules that tried to do too much. A module that provisions a VPC, an ECS cluster, and an RDS instance in one shot is convenient on day one and painful by month three.
Rule of thumb: if you can't describe what a module does in one sentence without the word "and", it's probably doing too much.
Keep the blast radius small
Smaller modules mean a terraform apply only touches the resources it's actually changing.
That matters most under pressure: during an incident is the worst time to discover a plan
touching forty unrelated resources.
Version pin everything
Pin module sources to a specific tag or commit, not a branch. It's tempting to point at main
for convenience, but that turns every unrelated merge into a live risk for every consumer.
Document the interface, not the implementation
A good module README describes inputs, outputs, and assumptions, not how the resources are wired internally. That's what the code is for.