Prompt
How do I organize reusable IaC modules for a platform team?
Latest observation
A good way to organize reusable IaC modules for a platform team is to optimize for reuse, versioning, clear ownership, and safe consumption. The exact layout depends on your tooling, but the same principles apply whether you use Terraform, Pulumi, CloudFormation, Bicep, or Crossplane.
Core principles
-
Separate “modules” from “environments”
- Modules should be reusable building blocks.
- Environments should only compose modules and supply configuration.
- Avoid putting environment-specific logic inside modules.
-
Keep modules small and opinionated
- Each module should do one job well:
- VPC/networking
- IAM roles/policies
- EKS cluster
- S3 bucket
- RDS instance
- If a module grows too large, it becomes hard to reuse and version.
- Each module should do one job well:
-
Standardize inputs and outputs
- Inputs should be explicit and documented.
- Outputs should expose only what consumers need.
- Use consistent naming conventions and tags/labels across modules.
-
Version everything
- Treat modules like APIs.
- Use semantic versioning.
- Consumers should pin versions instead of tracking
main.
-
Design for least privilege and safe defaults
- Modules should enforce secure defaults.
- Allow overrides only where necessary.
- Make insecure settings opt-in rather than default.
-
Provide a paved road, not just primitives
- Platform teams usually need both:
- low-level modules for infrastructure primitives
- higher-level modules for common platform patterns
- Example:
s3-bucketplusapp-storagewrapper module.
- Platform teams usually need both:
A practical repository structure
A common structure looks like this:
iac/
modules/
networking/
vpc/
subnet/
security-group/
compute/
ecs-service/
eks-cluster/
lambda/
data/
s3-bucket/
rds/
dynamodb/
identity/
iam-role/
iam-policy/
observability/
logging/
metrics/
alerts/
live/
dev/
networking/
platform/
staging/
platform/
prod/
platform/
examples/
vpc-basic/
eks-with-addons/
What each folder is for
-
modules/- Reusable, versioned IaC components
- Minimal environment assumptions
- Ideally self-contained and tested
-
live/orenvironments/- Environment-specific composition
- References modules by version
- Contains account/region-specific values
- Keeps state separated per environment
-
examples/- Demonstrates how to use modules
- Helps consumers adopt modules correctly
- Can double as smoke tests
Recommended module taxonomy
Organize by domain rather than by team:
- Network
- VPC, subnets, routing, firewall rules
- Identity and access
- IAM roles, policies, service accounts
- Compute
- VM groups, container services, serverless functions
- Data
- Databases, queues, storage, caches
- Observability
- Logs, metrics, alerts, dashboards
- Security
- KMS keys, secrets, encryption policies
- Platform services
- Cluster baselines, ingress, DNS, artifact registries
This makes modules easy to find and reduces duplication.
When to make a wrapper module
Use a wrapper module when you want to:
- standardize best practices
- reduce the number of required inputs
- hide complexity from application teams
- compose multiple base modules into one opinionated service
Example:
- Base module:
s3-bucket - Wrapper module:
app-storage-bucketwith encryption, versioning, logging, lifecycle rules, and tags preconfigured
This is often the best way for a platform team to provide a “golden path.”
How to manage versioning
Use semantic versioning
1.0.0= stable initial release1.1.0= backward-compatible enhancement2.0.0= breaking change
Versioning rules
- Breaking input/output changes require a major bump
- Additive changes are minor
- Bug fixes are patch
Pin versions in consumers
Example:
module "vpc" {
source = "git::ssh://git.example.com/platform-iac.git//modules/networking/vpc?ref=v1.4.2"
}
This prevents accidental breakage from upstream changes.
Testing and quality gates
For reusable modules, testing is essential.
Minimum recommended checks
- Linting/formatting
- Static validation
- Policy checks
- Unit tests / module tests
- Integration tests in a sandbox account
Good practices
- Add examples that are deployed in CI
- Use ephemeral test environments for critical modules
- Validate outputs and resource properties, not just plan success
Documentation that helps adoption
Every module should have:
- purpose
- architecture diagram if needed
- input variables with descriptions and defaults
- outputs
- example usage
- gotchas / limitations
- version history / changelog
- ownership/contact
A README template is often enough, but it must be consistent.
Ownership and governance
For a platform team, clarity matters.
Assign ownership per module
- One module should have one clear owning team
- Define review requirements for changes
- Use CODEOWNERS or equivalent
- Publish support expectations and deprecation policy
Deprecation policy
- Announce deprecation early
- Support old and new versions for a transition period
- Avoid forced migration without a path
Practical design guidelines
Good module characteristics
- small surface area
- predictable outputs
- no hidden side effects
- configurable but not over-parameterized
- safe defaults
- provider/version constraints documented
- reusable across accounts/projects/regions
Avoid
- hardcoding environment names
- embedding CI/CD logic inside modules
- overusing variables for everything
- tightly coupling modules to each other
- exposing internals that consumers shouldn’t manage
A useful pattern: layers
Many platform teams use layered modules:
-
Foundation layer
- accounts/subscriptions/projects
- networking
- identity baseline
-
Platform layer
- clusters
- logging/monitoring
- secret management
- ingress/load balancing
-
Application enablement layer
- app databases
- queues
- storage
- service identities
This keeps responsibilities clean and reduces blast radius.
Example workflow
- Platform team builds and tests a module.
- Module is released with a version tag.
- Consumer teams use the version in their environment stacks.
- Platform team monitors usage and feedback.
- Changes are made through pull requests and release notes.
- Breaking changes are introduced only in major versions.
A simple rule of thumb
If a piece of IaC is:
- reused across multiple services or teams,
- versioned independently,
- and needs a stable interface,
then it should be a module.
If it is:
- specific to one environment,
- not expected to be reused,
- or mostly orchestration logic,
then it belongs in the environment/live layer.
Suggested starting point for a platform team
If you’re just starting, build these first:
- network baseline module
- IAM role/policy module
- storage module
- compute/service module
- observability module
- wrapper modules for common platform patterns
That usually covers most teams’ needs.
If you want, I can also give you:
- a Terraform-specific repo layout
- a module README template
- or a platform team module governance checklist.