Docs & Code Guide

Keep network diagrams up to date: diagram what the API reports, not what the console remembered

A network diagram drawn from a console tour is a photograph of one afternoon. The cloud API that provisioned every VPC, subnet and peering connection can report the topology at any moment, which means the diagram does not have to depend on anyone remembering to redraw it. The fix is to change the source: draw from the API or the IaC, and regenerate on the events that change the network.

Try it free
8 min readFor platform and network engineers whose topology diagram is always one migration behind

See it as a diagram

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

255/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Why network diagrams go stale faster than any other doc

Networks change through tickets and Terraform merges, and almost never through the person who owns the diagram. A subnet gets added for a new workload, a peering connection appears for a vendor integration, a route table gains an entry during an incident, and each change is correct, reviewed and invisible to the drawing. Within a quarter the diagram disagrees with the account on the exact details that matter during an outage: which CIDR ranges exist, what peers with what, where traffic actually egresses.

The deeper problem is the source. A diagram drawn from a console session captures what one person clicked through on one day. There is no diff between that drawing and the account, so nobody can even say how wrong it is. Documentation you cannot diff against reality decays silently, which is the general failure mode described in documentation drift.

Discovery versus intent: two sources, two different diagrams

There are two truthful sources for a network diagram and they answer different questions. Discovery is what the cloud API reports right now: every VPC, subnet, peering connection and route that actually exists, including the security group someone widened by hand during an incident. Intent is what the IaC declares: the Terraform or CloudFormation that says what should exist.

The intent diagram is the one to publish for architecture reviews, because it changes through pull requests and can be regenerated on merge. The discovery diagram is the one to generate for audits and incident retros, because it includes the manual changes the IaC does not know about. When the two disagree, that gap is not a documentation bug, it is a finding: unmanaged resources or drifted state that deserves a ticket of its own.

Pull the facts from the API, not from memory

Everything a topology diagram shows is one describe call away. The commands below dump the VPCs, subnets, peering connections and routes for an AWS account; equivalents exist for every provider. This output is the raw material: paste it into a generator, or point an agent at it, and the diagram is built from the same source of record the network runs on.

The first generation is the easy part. Paste the output, or a plain description of the topology, into the AWS network diagram generator and edit from there. For multi-cloud or on-prem segments the general network architecture diagram generator does the same job without the AWS vocabulary.

# What actually exists, from the API that provisioned it
aws ec2 describe-vpcs \
  --query 'Vpcs[].{id:VpcId,cidr:CidrBlock}' --output table

aws ec2 describe-subnets \
  --query 'Subnets[].{id:SubnetId,vpc:VpcId,cidr:CidrBlock,az:AvailabilityZone}' \
  --output table

aws ec2 describe-vpc-peering-connections \
  --query 'VpcPeeringConnections[].{id:VpcPeeringConnectionId,requester:RequesterVpcInfo.VpcId,accepter:AccepterVpcInfo.VpcId,status:Status.Code}' \
  --output table

aws ec2 describe-route-tables \
  --query 'RouteTables[].{vpc:VpcId,routes:Routes[].DestinationCidrBlock}'

Tie regeneration to the events that change the network

A diagram with a live source still needs a trigger. The reliable ones are the events that already gate network change: a merge that touches the network modules in your IaC repo, and the closing of a network change ticket. Put the diagram update inside those events and it can never fall behind by more than one change.

Datadef ships an MCP server, registry name io.datadef/mcp, so an agent such as Claude Code or Cursor connected to it can read the Terraform module or the describe output and update the Datadef diagram to match: after a merge, in a scheduled CI job, or on request during review. To be exact about the mechanics: Datadef does not watch your repository or your cloud account, and nothing detects a change by itself. The regeneration is one agent call or one CI step away, which is enough to make the network-change checklist enforceable. Connecting an agent needs an API key, available on paid plans. If Terraform is your source of record, living diagram from Terraform walks the same loop from the state side.

The trigger list that works

Regenerate on merges touching network modules, on change-ticket close, and once a quarter from discovery output to catch what the IaC missed. Three triggers, no calendar reminders.

Publishing the diagram, and the honest limit for sensitive networks

A Datadef project shared public gets a permanent image URL of the form https://datadef.io/api/embed/your-slug, which renders in a wiki, a README or a runbook and follows the source diagram: an edit shows up in the embed within minutes. That closes the last gap, where the diagram was updated but the copies pasted around the company were not.

The limit matters here more than on most pages: the embed URLs exist only for projects shared public, and a production network topology is often exactly the thing you do not publish. For those, keep the diagram private in Datadef and place dated exports in the documents that need them. The security variant of this trade-off, including what auditors expect to see, is covered in keeping security architecture docs current.

FAQ

How do I keep a network diagram up to date?

Change the source, then the trigger. Draw the diagram from what the cloud API reports or what the IaC declares rather than from a console tour, and regenerate it on the events that change the network: merges touching network modules and network change tickets. With a live source and event triggers the diagram can never be more than one change behind.

Should I diagram from the cloud API or from Terraform?

Both, for different purposes. Terraform declares intent and changes through pull requests, so the intent diagram is the one to regenerate on merge and publish for reviews. The API reports what actually exists, including manual changes, so a discovery diagram generated from describe calls is the one for audits and incident retrospectives. A disagreement between the two is a drift finding, not a documentation bug.

Why is my network diagram always out of date?

Because the people who change the network are not the people who own the diagram, and no event connects the two. Subnets, peering connections and routes change through tickets and IaC merges; a hand-drawn diagram has no source to follow and no trigger to update it, so it decays with every change. Rebuilding it from the API or the IaC gives it both.

Can a network diagram update automatically when the network changes?

Not fully automatically, and tools that claim otherwise usually mean a scheduled scan. Datadef does not watch your cloud account or repository; the update runs when an agent or a CI step invokes it, for example through the Datadef MCP server after a merge to the network modules. In practice a regeneration wired into the merge event keeps the published embed current within minutes of the diagram edit.

What should trigger a network diagram update?

Three events cover nearly everything: a merge that touches network code in the IaC repository, the closing of a network change ticket, and a periodic regeneration from cloud API output to catch changes made outside the IaC. Calendar-based reminders alone fail because they are disconnected from the changes themselves.

Is it safe to publish a live network diagram?

Only if the topology is safe to publish. Live embed URLs require the project to be shared public, and many production network diagrams are confidential by policy. For those, keep the diagram private and circulate dated exports inside restricted documents. The dating doubles as review evidence for audits.