Diagrams¶

vpcatlas draws the network it reads as editable diagrams, in two formats: draw.io (.drawio) and Lucidchart (.lucid). Both formats are written from one layout, so a box sits in the same place, with the same caption, in either of them.

You get diagrams from vpcatlas discover (everything), from vpcatlas diagram (diagrams only) and from the dashboard (vpcatlas serve).

vpcatlas diagram --profile prod --output-dir out

Pages¶

A run produces three kinds of pages. Each page is its own file.

Page	What it shows	File name	Page id
Global	The whole estate on one page: the audited accounts, their regions, every VPC as a single box with its CIDR, the Transit Gateways, Direct Connect and VPN, VPC peerings, the external accounts, and the edge lane (users, Route 53, CloudFront, web ACLs, API Gateway) above the accounts.	`vpcatlas-global.<ext>`	`global`
Region	One page per region that holds at least one resource. The VPCs of the region with their Availability Zones and subnets, the gateways on their borders, the hub strip (Transit Gateway, Network Firewall), the regional service row, the edge lane of the region and the stubs of other accounts.	`vpcatlas-<region>.<ext>`, for example `vpcatlas-eu-west-1.drawio`	the region code
VPC	One page per VPC, drawn alone and in full: every workload and every interface endpoint by name, the route table and network ACL of each subnet as icons in the corner of the subnet, a card per route table (its routes and the subnets it serves) and a card per security group in use.	`vpcatlas-vpc-<id>.<ext>`	`vpc-<id>`

In the VPC file name, <id> is the start of the VPC id: the characters after vpc-, lower case, letters and digits only, cut at 12. If two VPCs would get the same name the second one gets -2 after it, the third -3, and so on. Inside the file, the page is named <VPC name> (<account alias>), or the account id when the account has no alias.

Region pages exist only for regions that hold something. --regions and --exclude-regions narrow them further. The Global page is written whenever the level is account or all.

Files go to a diagrams/ folder inside the output directory (--output-dir, default vpcatlas-out):

vpcatlas-out/
  vpcatlas-graph.json
  diagrams/
    vpcatlas-global.drawio
    vpcatlas-eu-west-1.drawio
    vpcatlas-vpc-0a1b2c3d4e5f.drawio
    vpcatlas-global.lucid
    vpcatlas-eu-west-1.lucid
    vpcatlas-vpc-0a1b2c3d4e5f.lucid

The choice of pages and formats:

Option	Values	Default
`--format`, `-f`	`drawio`, `lucid`, `all`. Repeat the option or separate values with commas. `discover` also accepts `json`, `md` and `html` for the inventory.	`all`
`--level`	`account` (Global and the region pages), `vpc` (one page per VPC) or `all`	`all`
`--output-dir`, `-o`	A directory	`vpcatlas-out`
`--cache`	A `vpcatlas-graph.json` to draw from, instead of calling AWS	none

The dashboard serves the same pages, with download names of the form vpcatlas-<account id>-<page id>.drawio. Its downloads add a multi-page .drawio that joins every page in tab order (/export/all.drawio) and a zip with everything (/export/all.zip).

What each page follows¶

The pages follow the layout of the AWS landing zone network architecture diagrams, and use the AWS Architecture Icons.

Landing zone layout. From the outside in: the page, the external column (Internet, users, on-premises), the account clouds, the Region, the VPC, an Availability Zone band, a subnet column, the icons. A resource has exactly one parent. The Internet gateway and the virtual private gateway sit on the left border of their VPC, gateway endpoints on the bottom border. Transit Gateway, Direct Connect and VPN sit outside the VPCs, between them and the on-premises side.
Subnet columns. Subnets are grouped by role in every Availability Zone band: public first, then private, isolated and the rest. The role comes from the default route: a route to an internet gateway makes a subnet public.
AWS Architecture Icons. In draw.io the icons are the mxgraph.aws4 shapes that ship with the editor, so they come with the editor and need no download. In Lucid they are the AWS 2024 library shapes. Where a Lucid class name has not been verified, the shape is drawn as a plain rectangle with its caption. Set VPCATLAS_LUCID_UNVERIFIED=class to ask for the library class instead.
Captions. The caption is the Name tag, or the id when there is no Name. A detail line under it shows the key attribute (an engine, a runtime, a task count). The full text is kept in the cell metadata when a caption is cut.
Numbered flows with a legend. Edges carry a numbered disc, one number per kind of traffic, and a number means the same on every page. A page numbers only the kinds it draws, so it may skip numbers.

Number	Traffic
1	Internet ingress
2	NAT egress
3	Transit Gateway attachment
4	Direct Connect / VPN
5	VPC peering
6	Shared prefix list / RAM
8	Internet ingress (CDN)
9	API traffic
10	Database access

The numbers are derived from what an edge is, not from a route analysis. The legend, at the bottom left, lists the edge kinds in use, the subnet colours, the external-account sample, the "Traffic flows" block and a footer with the tool name and version, the account ids and the UTC time of the scan. - Lines run behind icons. An edge does not bend around an icon. The router prefers a free track and, where none exists, the line is cut at the outline of the icon so that it seems to pass behind it. An icon on a border has a white backing, and the line of the container it sits on stops at it. - Service rows and lanes. The service layer is drawn in three places. The edge lane sits under the title of each Region (above the accounts on the Global page): users, Route 53, CloudFront, web ACL, API Gateway. A WAF web ACL, Shield and an ACM certificate appear as small badges beside the service they protect or secure. The regional row sits below the lane: Lambda functions that are not in a VPC (one icon with a count), S3 buckets, DynamoDB, ECR and KMS. The account row, in the last Region frame, shows CloudTrail, GuardDuty, AWS Config and CloudWatch, each with its key attribute. - Other accounts. Anything an audited account refers to but does not own goes into its own dashed AWS Cloud group, titled External account <id>, outside the audited accounts: a Transit Gateway shared through RAM, the other side of a peering, a shared prefix list. When more than one account appears on a page, Availability Zones are labelled with the zone id (euw1-az1), because zone names do not map to the same physical zone in every account. - Cell metadata. Every cell is an object that carries type, and where they apply resource (the AWS id), account, region, arn, cidr, detail, name, sg (the security group ids on a VPC-level icon) and more. In draw.io, right-click a cell and choose Edit Data. In Lucid the same pairs are in the shape's custom data.

The colour profile is article. The aws2024 profile (the colours of the current official library) exists in the exporter library, but no command-line option selects it.

Detail levels¶

The layout has four detail levels: overview, vpc, subnet and full.

Value	Effect on a region page
`overview`	Each VPC is one box with its CIDR and its border gateways. No Availability Zone or subnet detail.
`vpc`	The same compact box as `overview`.
`subnet`	Availability Zone bands and subnet columns. This is the default.
`full`	Drawn like `subnet` in this version. The style guide reserves it for a level that adds interfaces, route tables and network ACLs; those are drawn today on the VPC-level pages.

The Global page is always drawn at overview.

The detail level is a parameter of the exporter library (vpcatlas.exporters.build_layout(..., detail=...), drawio.render(..., detail=...), lucid.render(..., detail=...), export(..., detail=...)). The vpcatlas command line does not expose it; the files it writes use subnet. For a single VPC with everything on it, use the VPC-level pages (--level vpc).

draw.io format¶

A .drawio file is an <mxfile host="vpcatlas"> document with one <diagram id=... name=...> element per page. The command line writes one page per file. The XML is plain text and not compressed, so you can read it, grep it and diff it. The page has a white background, no grid and no page frame, and its size follows the drawing.

To open and edit it:

Open app.diagrams.net or the draw.io desktop app and choose Open Existing Diagram, or drop the file on the window.
Edit as usual. Every box is a normal draw.io cell. Edges are drawn as exact orthogonal polylines.
Use File > Export as to get PNG, SVG or PDF.

The dashboard serves a .drawio page through its viewer and as a download.

Lucidchart format¶

A .lucid file is a Lucid Standard Import package: a ZIP file with document.json at its root (and images/ when icon images are used). It has one page per diagram page, absolute coordinates, nesting by geometry (a container owns the shapes inside its bounding box) and ids of at most 36 characters. The zip entries have a fixed timestamp, so the bytes do not change between runs.

To import it, use Lucid's Standard Import. Lucid documents this through its REST API: POST https://api.lucid.co/v1/documents with an OAuth 2.0 bearer token and a multipart body that holds the file with the content type x-application/vnd.lucid.standardImport, a title and product=lucidchart. vpcatlas only writes the file; it does not call the Lucid API for you.

Documented losses against draw.io: Lucid draws the corner icons of groups itself, has no rounded corners and has no dash-dot line pattern, so a cross-account link is dashed like a peering. Limits to keep in mind: document.json must stay under 2,000,000 bytes and a page under 20,000 px per side; the exporter keeps the pages inside both. Lucid warns that an unchanged import file may produce varying results over time, so treat the .lucid bytes, not the rendering, as the stable artifact.

Determinism¶

The same graph gives the same drawing. The layout has no random step, ids are made from a hash of the page and the resource, and the timestamp printed in the legend is the time of the scan stored in the graph (generated_at), not the time of the export. So:

vpcatlas diagram --cache vpcatlas-graph.json rewrites byte-identical files for the same graph.
A scan that finds a different network gives a different drawing, and only the cells that changed move.

Comparing two drawings¶

Because the draw.io XML is plain text and ids are stable, two drawings of the same page compare with an ordinary text diff:

diff vpcatlas-old/diagrams/vpcatlas-eu-west-1.drawio vpcatlas-new/diagrams/vpcatlas-eu-west-1.drawio

For a diff between two scans that is meant to be read, use the dashboard. It keeps a history of the scans and compares any two of them at /diff/{older_id}/{newer_id}. The compared diagram is drawn on the newer scan with the changes highlighted: a green frame and a NEW badge on what was added, an orange frame and a CHANGED badge on what changed, green new lines, a "Changes" block in the legend, and a dashed red card beside the legend for each removed resource. Nothing moves; the highlighted page has the geometry of the plain one. The changes are also available as JSON at /export/diff/{from_id}/{to_id}.json and as a highlighted .drawio at /export/diff/{older_id}/{newer_id}/{key}.drawio.