Terraform / OpenTofu Module Layout
Modules follow Google's canonical file layout. The structure keeps modules navigable,
reviewable, and reusable; deviations are caught by automated lint.
Core Required Files (every module)
| File |
Purpose |
main.tf |
Primary resources, data sources, and module calls |
variables.tf |
Input variable declarations |
outputs.tf |
Output declarations |
versions.tf |
required_providers and required_version constraints |
README.md |
Module documentation: purpose, inputs, outputs, and usage |
Logical Resource Files
In accordance with Google's Terraform style guide, modules may split complex resource
configurations into logically grouped .tf files named [a-z0-9_]+\.tf:
network.tf, firewall.tf, iam.tf, dns.tf, storage.tf, compute.tf
locals.tf for local value expressions
data.tf for data source queries
Root Module Only
| File |
Purpose |
providers.tf |
Provider configuration blocks |
backend.tf |
Backend configuration |
Reusable child modules never configure providers or backends directly. They declare
provider requirements in versions.tf and receive provider instances from the caller.
Prohibited in Reusable Modules
- Environment root directories (
envs/, environments/)
- Variable definitions files (
*.tfvars, *.tfvars.json)
- State files (
*.tfstate, *.tfstate.backup)
Companion Artifacts
Every module ships with:
README.md documenting purpose, inputs, outputs, and usage.
examples/ with at least a minimal and a complete example (these double as
test fixtures).
tests/ with *.tftest.hcl files exercising the module.
Module Boundary Guardrail
Split into submodules based on subsystem cohesion (own lifecycle, independently
reusable, clean interface), never on line count alone. Module boundaries cost
plumbing, moved blocks, and state surgery. A cohesive 350-line module beats
three anemic submodules. The layout constraint creates natural pressure to
keep modules focused; the cohesion test decides when to cut.
1---2name: terraform-module-layout3description: Use when creating, reviewing, or restructuring Terraform or OpenTofu modules. Enforces Google-recommended module file layout and cohesion-based module boundaries.4metadata:5 source: https://skillmd.com/skills/selamy-labs/terraform-module-layout6---78# Terraform / OpenTofu Module Layout910Modules follow Google's canonical file layout. The structure keeps modules navigable,11reviewable, and reusable; deviations are caught by automated lint.1213## Core Required Files (every module)1415| File | Purpose |16|---|---|17| `main.tf` | Primary resources, data sources, and module calls |18| `variables.tf` | Input variable declarations |19| `outputs.tf` | Output declarations |20| `versions.tf` | `required_providers` and `required_version` constraints |21| `README.md` | Module documentation: purpose, inputs, outputs, and usage |2223## Logical Resource Files2425In accordance with Google's Terraform style guide, modules may split complex resource26configurations into logically grouped `.tf` files named `[a-z0-9_]+\.tf`:2728- `network.tf`, `firewall.tf`, `iam.tf`, `dns.tf`, `storage.tf`, `compute.tf`29- `locals.tf` for local value expressions30- `data.tf` for data source queries3132## Root Module Only3334| File | Purpose |35|---|---|36| `providers.tf` | Provider configuration blocks |37| `backend.tf` | Backend configuration |3839Reusable child modules never configure providers or backends directly. They declare40provider requirements in `versions.tf` and receive provider instances from the caller.4142## Prohibited in Reusable Modules4344- Environment root directories (`envs/`, `environments/`)45- Variable definitions files (`*.tfvars`, `*.tfvars.json`)46- State files (`*.tfstate`, `*.tfstate.backup`)4748## Companion Artifacts4950Every module ships with:5152- `README.md` documenting purpose, inputs, outputs, and usage.53- `examples/` with at least a minimal and a complete example (these double as54 test fixtures).55- `tests/` with `*.tftest.hcl` files exercising the module.5657## Module Boundary Guardrail5859Split into submodules based on subsystem cohesion (own lifecycle, independently60reusable, clean interface), never on line count alone. Module boundaries cost61plumbing, moved blocks, and state surgery. A cohesive 350-line module beats62three anemic submodules. The layout constraint creates natural pressure to63keep modules focused; the cohesion test decides when to cut.