vpcatlas diagram

vpcatlas [GLOBAL OPTIONS] diagram [OPTIONS]

What it does

Writes only the diagrams: the account level (a global view and a page per region) and the VPC level (a page per VPC). Every page is written twice, as an editable draw.io file and as a Lucidchart file, named vpcatlas-<page id>. --level picks one level or both. It scans like discover but writes no inventory.

Credentials come from the standard chain or from the options below; see credentials. The paths of the files written go to standard output, one per line; the "Discovery summary" table, with the number of account-level and VPC-level pages, goes to standard error.

Pages are drawn only for regions that hold at least one resource, narrowed by --regions and --exclude-regions. This also holds with --cache. The dashboard draws its pages with the same code, so the files here and its downloads are the same.

Options

Flag	Environment variable	Default	Description
--profile, -p	none	standard credential chain	AWS profile. Repeat it to scan several accounts into one graph.
--role-arn	none	none	Role to assume (ARN). Repeat it to scan several accounts.
--external-id	VPCATLAS_EXTERNAL_ID	none	ExternalId required by the role.
--mfa-serial	none	none	MFA device serial or ARN, when the role requires MFA.
--mfa-token	none	none	Current MFA code. Used together with --mfa-serial.
--session-duration	VPCATLAS_SESSION_DURATION	3600	Duration of the assumed-role session, in seconds (900 to 43200).
--role-session-name	VPCATLAS_ROLE_SESSION_NAME	vpcatlas	RoleSessionName used when assuming the role.
--regions, -r	none	every enabled region	Regions to scan, comma separated. Default: every enabled region.
--exclude-regions	none	none	Regions to leave out, comma separated.
--concurrency, -c	none	8	Regions scanned in parallel (1 to 32).
--cache	none	none	Read this graph file (vpcatlas-graph.json) instead of calling AWS. The file must exist.
--output-dir, -o	none	vpcatlas-out	Directory for the generated files. Created when missing.
--format, -f	none	all	drawio, lucid or all. Repeat or separate with commas.
--account-names	none	none	JSON file that maps account ids to labels, for accounts the API cannot name. The file must exist.
--strict	none	off	Exit with code 4 when discovery recorded issues (denied, errors).
--level	none	all	Diagram level: account (global view, one page per region), vpc (one page per VPC) or all.

all is both diagram formats. An inventory format (json, md, html) is a usage error here; use inventory or discover for those.

Files it writes

Under the output directory (vpcatlas-out unless --output-dir says otherwise):

File	When
vpcatlas-graph.json	The data came from AWS. Not written with --cache.
diagrams/vpcatlas-global.drawio and diagrams/vpcatlas-global.lucid	Level account or all.
diagrams/vpcatlas-<region>.drawio and .lucid (for example vpcatlas-eu-west-1.drawio)	One per drawn region, level account or all.
diagrams/vpcatlas-vpc-<id>.drawio and .lucid	One per VPC, level vpc or all.

Format: diagrams, graph.

Examples

A local profile, only the draw.io files of the account level:

vpcatlas diagram --profile audit --regions eu-west-1 --format drawio --level account

An assumed role with an external id, one page per VPC, for a role that requires MFA. The code is a one-time code from the device, not a secret key:

export VPCATLAS_EXTERNAL_ID=my-external-id
vpcatlas diagram \
  --role-arn arn:aws:iam::111122223333:role/VpcAtlasAuditor \
  --mfa-serial arn:aws:iam::999988887777:mfa/ana --mfa-token 123456 \
  --level vpc --output-dir ./atlas

Docker, drawing again from a graph saved by an earlier run, so it needs no credentials:

docker run --rm -v "$PWD/vpcatlas-out:/data" \
  vpcatlas/vpcatlas diagram --cache /data/vpcatlas-graph.json --output-dir /data

On Linux add --user "$(id -u):$(id -g)" so the container can write to the folder. To scan from the container instead, mount ~/.aws read-only (-v "$HOME/.aws:/home/atlas/.aws:ro") and add --profile audit.

Exit codes

Code	When
0	The files were written.
1	Unexpected failure: an AWS error that is not about credentials, a file that cannot be read or written, or a malformed --cache or --account-names file.
2	Bad usage: an unknown option or value (including an inventory format or a --level other than account, vpc, all), a missing --cache or --account-names file, and the checks listed on the index.
3	AWS credentials or access: none found, expired, rejected, or the role cannot be assumed.
4	The scan recorded issues while --strict is set. The files are written first.

Details and typical causes: exit codes.