A living diagram from Pulumi: the stack export is the reliable source when programs build resources dynamically

With HCL-style declarative tools, the config file enumerates the resources. With Pulumi, the program computes them: resources appear inside loops, behind conditionals, and from component classes that expand into many children at runtime. Two runs of the same program with different stack config produce different infrastructures, on purpose. Any diagram generated by reading the .ts or .py files is a guess about what the code would do, not a record of what it did.

The engine, meanwhile, keeps a complete record. Every resource Pulumi manages lands in the stack's checkpoint with its URN, type, parent, and dependencies. Diagramming Pulumi well means diagramming that record.

pulumi stack export writes the full checkpoint as JSON: the resource list with URNs, types, parent relationships, and dependency edges, everything a diagram needs and nothing it has to infer. pulumi preview --json is the forward-looking version, the planned creates, updates, and deletes before a deploy, useful when you want the diagram change reviewed alongside the code change. And pulumi stack graph writes the stack's dependency graph as Graphviz DOT if you want the raw shape.

One security note that works in Pulumi's favor: secret outputs in the export stay encrypted by the stack's secrets provider unless you explicitly pass --show-secrets. A default export is therefore a reasonably safe artifact to hand to an agent, since the topology is plaintext and the secrets are not.

# The full checkpoint: every resource, URN, parent, dependencies
pulumi stack export --file stack.json

# Planned changes before deploy, machine readable
pulumi preview --json

# The dependency graph as Graphviz DOT
pulumi stack graph deps.dot

The Pulumi convention of a stack per environment, dev, staging, prod, settles a question other tools leave open: which environment does the wiki diagram show? Pick the stack, usually prod, export it, and label the diagram with the stack name. When staging genuinely differs, that bastion host again, the difference is visible by exporting both stacks rather than assumed from reading the code.

Parent relationships in the export give the grouping. Component resources, the classes your team wrote to bundle a service with its bucket and its alerts, appear as parents of their children, so the diagram can draw each component as a zone and match the abstractions the program authors actually meant.

The loop is one step after the deploy: pulumi up, then pulumi stack export, then an agent connected to Datadef's MCP server (registry io.datadef/mcp) reads the export and updates the diagram, new resources added, destroyed ones removed, component zones intact. The agent connection needs an API key, available on paid plans; setup lives in the MCP diagram server guide.

Datadef does not watch the repo or the Pulumi service, and nothing triggers on its own. The regeneration is one command next to the one you already run. For the first diagram, before there is anything to update, the infrastructure-as-code diagram generator takes a pasted export or a plain-English description and gives you the editable starting point.

With the diagram public, the wiki side is automatic: the embed image serves with a five minute cache lifetime, so a diagram updated by the pipeline shows up in the docs within minutes.

The Pulumi Cloud console already lists every resource in a stack, and for inspecting one deployment right after it runs, that list is the fastest tool. What it is not is a curated architecture view at the altitude a wiki needs, drawn once and embedded where the team reads.

The Datadef embed exists only for projects shared public; private projects have no embed URL, so confidential stacks fall back to exported images. And the loop covers the diagram, not the prose: runbooks and per-stack README files are out of scope, a different discipline with different tooling.

• A living diagram from Terraform
• A living diagram from AWS CDK
• Infrastructure-as-code diagram generator
• The MCP diagram server