Docs & Code Guide

A living diagram from Terraform: regenerate the infrastructure view on every merge instead of redrawing it

The question people actually type is "is there an AI that can read Terraform scripts and generate infrastructure diagrams for our wiki". The answer is yes, and the good version is not a one-off: an agent reads what Terraform already exports, draws the diagram once, and then re-runs the same read after every apply so the wiki view never falls behind the code. This page covers which Terraform artifacts to feed it, and how to wire the loop.

Try it free
8 min readFor platform teams whose Terraform is the only accurate map of production

See it as a diagram

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

212/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Two machine-readable views Terraform already maintains

You never need to parse HCL to diagram Terraform. The toolchain exports two structured views for free. terraform show -json prints the current state as JSON: every deployed resource with its type, name, provider, and the module it belongs to. terraform graph prints the dependency graph of the configuration in Graphviz DOT, which is the shape of the wiring rather than the inventory.

Both are plain text, which matters for the first generation too: Datadef's AI import accepts pasted Terraform-style text as the prompt, so a trimmed show -json output or a graph dump is a working starting point. For the pure "turn this .tf into a picture" intent, the Terraform diagram generator page is the shorter path; this page is about what happens on merge two, and twenty.

# After apply: the deployed reality, machine readable
terraform show -json > infra.json

# The dependency graph of the configuration, as Graphviz DOT
terraform graph | dot -Tsvg > graph.svg

State or config: pick what the diagram should tell the truth about

The .tf files are intent; the state is what actually exists. They differ whenever an apply partially failed, a workspace has not caught up, or someone changed a resource outside Terraform. A wiki diagram that claims to show production should follow state, which means regenerating from terraform show -json after apply, not from the files at review time.

Module boundaries are the natural zones. Every resource address in state carries its module path, module.network.aws_subnet.private and so on, so the agent can group the diagram by module without any manual tagging. If your modules map to teams or layers, the diagram inherits that structure for free, which is exactly what a reader wants from a wiki view.

The regeneration loop: one command after apply, not a watcher

Datadef ships an MCP server, registry name io.datadef/mcp. An agent connected to it, Claude Code or Cursor, can read the exported state and update the existing diagram: add the new SQS queue, drop the decommissioned instance, keep the module zones intact. Connecting an agent needs an API key, available on paid plans; the setup is covered in the MCP diagram server guide.

To be precise about what this is not: Datadef does not watch your repository, and nothing detects a merge by itself. The loop is CI-invoked or agent-invoked. In practice that is one step appended to the pipeline job that already runs terraform apply, or one sentence to the agent that just wrote the change.

# In the pipeline job that runs terraform apply
- name: Export deployed state as JSON
  run: terraform show -json > infra.json

- name: Update the diagram
  run: |
    claude -p "Read infra.json and update the 'Platform infrastructure'
    diagram in Datadef via MCP. Group resources by Terraform module,
    remove anything no longer in state."

Let the wiki page update itself

The other half of the loop is the display. A Datadef project shared public gets a permanent image URL, https://datadef.io/api/embed/your-slug, that any wiki renders like a normal image. The image is served with an ETag derived from the diagram's last edit and a five minute cache lifetime, so when the CI step updates the diagram, the Confluence or Notion page showing it follows within minutes with nobody touching the page. The Confluence specifics, macros included, are in embed diagrams in Confluence.

That closes the circuit: merge changes the infrastructure, the pipeline regenerates the diagram, the embed refreshes the wiki. The only human act left is reviewing the diagram change, which is the part worth keeping human.

Where the Terraform view stops

Three things to concede. First, the embed URLs exist only for projects shared public; flip the project private and the image 404s, so confidential infrastructure diagrams need the export-and-upload fallback. Second, raw state can contain sensitive attribute values. The diagram needs resource addresses, types, and dependencies, not attributes, so filter the JSON before handing it to any AI tool, yours or anyone's. Third, this loop redraws architecture; it does not write or sync your prose runbooks, which is a different problem with different tools. The broader Terraform documentation workflow is covered in keeping infrastructure docs in sync with Terraform.

Feed addresses, not attributes

A diagram needs resource types, names, modules, and edges. Strip attribute values from terraform show -json output before passing it to an agent, and the sensitive-data question mostly disappears.

FAQ

Is there an AI that can read Terraform scripts and generate infrastructure diagrams?

Yes. An AI agent such as Claude Code or Cursor connected to Datadef's MCP server can read Terraform output, terraform show -json for deployed state or terraform graph for the dependency graph, and generate or update an infrastructure diagram from it. You can also paste Terraform-style text directly as a prompt for a first generation. The update path is agent- or CI-invoked; nothing watches the repo by itself.

Should the diagram come from Terraform state or from the .tf files?

From state, if the diagram claims to show what is deployed. The .tf files are intent and can be ahead of or behind reality after failed applies or out-of-band changes. Regenerating from terraform show -json after apply means the diagram always matches what the apply actually produced.

Does the diagram update automatically when the Terraform code changes?

Not by itself. Datadef does not watch repositories and there is no GitHub App detecting merges. The regeneration is one command in the pipeline that runs terraform apply, or one request to the coding agent that made the change. After that command runs, wiki pages embedding the diagram refresh within minutes on their own.

How do Terraform modules show up in the diagram?

As zones. Every resource address in state includes its module path, so an agent generating the diagram can group resources by module without manual tagging. If modules map to layers like network, compute, and data, the diagram inherits that structure.

Is it safe to feed Terraform state to an AI tool?

Raw state can contain sensitive attribute values, so do not paste it wholesale anywhere. A diagram only needs resource addresses, types, and dependency edges. Filter terraform show -json down to those fields first, with jq or a small script, and the exposure question mostly goes away.