Skip to content

Quickstart

From nothing to diagrams and a dashboard. About ten minutes, most of it spent on IAM. You need an AWS account you may read, and the AWS CLI or console access to create an IAM role or user.

1. Install

curl -fsSL https://vpcatlas.com/install.sh | sh
vpcatlas --version

Other channels (pipx install git+https://github.com/vpcatlas/vpcatlas, docker pull vpcatlas/vpcatlas) are on the Install page.

2. Print the auditor policy

VPC Atlas needs read access and nothing more. Print the policy it is built against:

vpcatlas iam-policy > auditor-policy.json

That is the full policy: the networking reads the diagrams need (Core* statements) plus the optional reads for load balancers, DNS, edge services, compute, data stores and account services (Optional* statements). For the diagrams alone, print only the core statements:

vpcatlas iam-policy --core-only --output auditor-core.json

You can also skip the custom policy and attach the AWS managed policy ReadOnlyAccess. See IAM permissions.

3. Attach it

Create a role (or use an existing user or role) for the auditor and attach the policy. With the AWS CLI, as an inline policy of a role called AtlasAuditor:

aws iam put-role-policy \
  --role-name AtlasAuditor \
  --policy-name VpcAtlasAuditor \
  --policy-document file://auditor-policy.json

The full policy is longer than the 6,144 characters IAM allows for a customer managed policy, so attach it inline to a role, or use --core-only (about 2,200 characters) when you need a managed policy.

The role needs a trust policy for whoever will assume it. A role in another account, with an external ID, is shown in Credentials. If you run VPC Atlas with your own credentials in the same account, attach the policy to your user or role instead.

4. Discover

Pick the credentials the way you would for the AWS CLI. A profile called audit:

vpcatlas discover --profile audit --regions eu-west-1,us-east-1

Or the role from step 3, assumed from your current credentials:

vpcatlas discover --role-arn arn:aws:iam::111122223333:role/AtlasAuditor --regions eu-west-1,us-east-1

Without --regions every region enabled for the account is scanned. A progress bar runs while the collectors work, then a summary table prints the audited accounts, external accounts, regions, resources, cross-account links, issues and the number of diagram pages. Access denied on one service is recorded as an issue and skipped, so the rest still runs. Add --strict if you want a non-zero exit code (4) when there are issues.

Everything lands in ./vpcatlas-out (change it with --output-dir):

vpcatlas-out/
  vpcatlas-graph.json
  vpcatlas-inventory.json
  vpcatlas-inventory.md
  vpcatlas-inventory.html
  diagrams/
    vpcatlas-global.drawio
    vpcatlas-global.lucid
    vpcatlas-eu-west-1.drawio
    vpcatlas-eu-west-1.lucid
    vpcatlas-vpc-0a1b2c3d4e5f67890.drawio
    vpcatlas-vpc-0a1b2c3d4e5f67890.lucid
    ...

The Global page and the regional pages are the account level; each vpcatlas-vpc-<id> file is one VPC in detail. The region and VPC ids above are examples: you get one file per region that holds resources and one per VPC.

5. Open the diagrams

  • draw.io: open any .drawio file in diagrams.net or the desktop app. Everything is editable.
  • Lucidchart: in Lucidchart choose Import, then Lucid Standard Import, and pick a .lucid file.
  • Inventory: open vpcatlas-inventory.html in a browser, or read vpcatlas-inventory.md.

Start with vpcatlas-global.drawio: it shows the whole estate on one page. See Diagrams for what each page contains and how to read the numbered flows.

6. Serve the dashboard

Show the scan you just made, without calling AWS:

vpcatlas serve --cache vpcatlas-out/vpcatlas-graph.json

Open http://127.0.0.1:8080. Or let the dashboard read AWS itself and rescan every 15 minutes:

vpcatlas serve --profile audit --regions eu-west-1,us-east-1 --refresh-seconds 900

The dashboard lists the diagrams, keeps a history of scans, draws the difference between two of them and offers every page for download in draw.io and Lucid format. See Dashboard.

Redraw without calling AWS

The graph file is the saved result of a scan. Use it to produce other outputs later, on another machine or in CI:

vpcatlas inventory --cache vpcatlas-out/vpcatlas-graph.json --format md
vpcatlas diagram --cache vpcatlas-out/vpcatlas-graph.json --format lucid --level vpc

Next