Terraform Guide

Terraform module diagram: draw the structure your repo already has

A well-factored Terraform repo already contains its own architecture diagram, encoded as module blocks: networking, databricks, key_vault, lakebase. The names are meaningful, the boundaries are deliberate, and the wiring between modules is written down as output references. A module diagram makes that structure visible instead of asking readers to reconstruct it from directory listings.

Try it free
6 min readFor maintainers of multi-module Terraform repositories

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

147/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Modules are the right unit for the diagram

When someone asks how the platform fits together, the answer is almost always phrased in modules: the storage module feeds the workspace module, the catalog module sits on both. Resources are the detail level below; providers are the detail level below that. A diagram whose containers are the modules matches how the team already talks.

The wiring between modules is also already explicit in the source. When module B takes module.a.storage_account_id as an input, that is an architectural statement: B depends on what A provisions. Resolving those references through module outputs gives you the true cross-module edges without guessing.

What Datadef draws for a multi-module repo

Each stack becomes an outer zone, each module with more than one visible resource becomes a zone inside it, and resources keep their real names and provider icons. Cross-module references, resolved through outputs to the actual resources on both ends, become the arrows, labelled with the attribute that carries them.

Multiplicity is preserved instead of exploded. A module instantiated with for_each over your projects stays one zone with the count. A resource created per environment shows the real numbers, like 10 catalogs in DEV and 1 in PROD, on a single node.

Local modules are expanded into their resources. Registry and git modules cannot be expanded from source, so each call becomes one node carrying its name, source, and version, wired to whatever feeds it. A repo that is mostly terraform-aws-modules composition still produces a real diagram.

Keeping it current

The module diagram is regenerated by the sync, daily and on demand, from the connected branch or tag. Because node identities derive from Terraform addresses, a re-sync updates the picture instead of reshuffling it: the databricks module zone stays where your mental map put it.

The companion architecture.md carries a generated module reference table, one row per module with source and resource count, in the terraform-docs style but maintained by the sync. Embed the diagram in the repo README with one markdown line and the README stops lying.

FAQ

Does it show resources inside each module or just module boxes?

Both. Modules render as zones, and the real resources render as nodes inside them: major resources individually with their provider icons, repeated minor types as one node with the count and names. Module-only boxes hide too much; resource-only lists lose the structure.

How are registry modules like terraform-aws-modules/vpc handled?

A registry or git module cannot be expanded from your repository alone, so the call is drawn as one node with its name, source, and version, for example vpc from terraform-aws-modules/vpc/aws at 5.8.1. References like module.vpc.vpc_id wire it to the rest of the diagram.

What about a module instantiated several times with for_each?

It stays one zone, with the multiplicity stated. When the for_each source is resolvable from tfvars, the real count per environment is shown rather than a generic label.

Can the diagram live in the repository README?

Yes. The linked project exposes a live embed image URL; one markdown image line in the README renders the current diagram and picks up every sync. Viewers need no account.