Configuration

VPC Atlas is configured with command line options and environment variables. The command line tools (discover, inventory, diagram) take options. The dashboard (vpcatlas serve) takes the same scan options, plus a set of VPCATLAS_* environment variables that suit containers, where you set an environment and not a command line.

Precedence

From strongest to weakest:

1. A command line option.
2. The environment variable of that setting, where it has one.
3. The default.

Only a few options read an environment variable on every command. The rest of the variables below are read by the dashboard only, and by vpcatlas serve, which builds the dashboard settings from the environment and then applies the options you gave on top of them.

Invalid values are rejected at start-up with a message that names the variable, for example VPCATLAS_ROLE_ARN must hold IAM role ARNs or VPCATLAS_CONCURRENCY must be an integer. The dashboard does not start with a bad setting.

Value types in the tables:

• list: comma separated, blanks and repeats ignored, order kept.
• int: a whole number within the range shown.
• bool: 1, true, yes, on or 0, false, no, off, in any case.
• string: taken as is after trimming blanks. An empty value counts as unset.

Variables read by every command that reaches AWS

These three back the options of the same name on discover, inventory, diagram and serve.

Variable	Option	Type	Default	Meaning
VPCATLAS_EXTERNAL_ID	--external-id	string	none	ExternalId sent when assuming a role.
VPCATLAS_SESSION_DURATION	--session-duration	int, 900 to 43200	3600	Seconds an assumed-role session lasts.
VPCATLAS_ROLE_SESSION_NAME	--role-session-name	string, 2 to 64 characters from letters, digits and + = , . @ _ -	vpcatlas	RoleSessionName used when assuming a role.

Dashboard variables

Read by vpcatlas serve and by the dashboard app when it runs directly (uvicorn vpcatlas.dashboard.app:app, the Lambda handler). Every variable is optional.

Credentials and scope

Variable	Option	Type	Default	Meaning
VPCATLAS_PROFILE	--profile	list	the default credential chain	Profile(s) to read. With VPCATLAS_ROLE_ARN, the first profile is the identity that assumes the roles.
VPCATLAS_ROLE_ARN	--role-arn	list of IAM role ARNs	none	Roles to assume. One audited account per role; the graphs are merged.
VPCATLAS_REGIONS	--regions	list, or all	see below	Regions to scan.
VPCATLAS_EXCLUDE_REGIONS	--exclude-regions	list	none	Regions to leave out.
VPCATLAS_CONCURRENCY	--concurrency	int, 1 to 32	8	Worker threads of one scan.
VPCATLAS_GRAPH_FILE	--cache	path	none	A vpcatlas-graph.json written by discover. The dashboard serves it and never calls AWS.
VPCATLAS_ACCOUNT_NAMES_FILE	--account-names	path	none	JSON object that maps account ids to labels, for accounts the API cannot name.

VPCATLAS_REGIONS is resolved in this order: the variable, if set (all or * means every enabled region); else AWS_REGION; else AWS_DEFAULT_REGION; else every region enabled for the account. This is why a container that sets AWS_REGION scans that one region unless you also set VPCATLAS_REGIONS=all. On the command line discover, inventory and diagram do not look at AWS_REGION for this: without --regions they scan every enabled region.

Refresh and history

Variable	Option	Type	Default	Meaning
VPCATLAS_REFRESH_SECONDS	--refresh-seconds	int, 0 or more	0 in the dashboard; 300 for vpcatlas serve when neither the option nor the variable is set; 0 in the Docker image	Seconds between automatic scans. 0 means one scan at start and manual refreshes after that.
VPCATLAS_MIN_REFRESH_SECONDS	none	int, 0 or more	300	Floor of the automatic interval and of manual refreshes. A smaller VPCATLAS_REFRESH_SECONDS is raised to it and a warning is logged.
VPCATLAS_REFRESH_MODE	none	background or lazy	background; lazy inside AWS Lambda	background scans in a loop inside the process. lazy scans when a request finds the data stale, for platforms with no background tasks.
VPCATLAS_SCAN_ON_REQUEST	none	bool	true	In lazy mode, let a request start a scan. Set false when a separate scheduled invocation does the scanning.
VPCATLAS_SNAPSHOT_URI	none	s3://bucket/prefix or file:///absolute/path	none (memory only)	Where the last snapshot and the history are kept, so restarts and Lambda cold starts serve data without a new scan, and several instances share one history.
VPCATLAS_HISTORY_KEEP	none	int, 1 or more	30	Snapshots kept in the history; the oldest are deleted.
VPCATLAS_HISTORY_MIN_INTERVAL_SECONDS	none	int, 0 or more	0	A scan identical to the previous one and newer than this is not added to the history. A scan that differs is always kept. 0 keeps every scan.

Serving

Variable	Option	Type	Default	Meaning
VPCATLAS_BASE_PATH	none	string	empty	URL prefix when the dashboard is served below a path, for example /atlas. Leading and trailing slashes are normalised.
VPCATLAS_VIEWER_URL	none	https:// URL or absolute path	https://viewer.diagrams.net/js/viewer-static.min.js	The diagrams.net viewer script the pages load. Point it at a self-hosted copy for a network with no internet access.
VPCATLAS_AUTH_USER	none	string	atlas	User name of the optional HTTP Basic protection.
VPCATLAS_AUTH_PASSWORD	none	string	none (no authentication)	When set, every page, API route, download and POST /refresh asks for HTTP Basic credentials; /healthz, /static/ and the API description stay open.
VPCATLAS_LOG_LEVEL	none	DEBUG, INFO, WARNING, ERROR, CRITICAL	INFO	Level of the vpcatlas loggers.

The dashboard shows your network topology. Set VPCATLAS_AUTH_PASSWORD whenever it is reachable by anyone but you, and put it behind TLS: HTTP Basic sends the password in every request.

Other variables

Variable	Read by	Type	Default	Meaning
VPCATLAS_LUCID_UNVERIFIED	the Lucid exporter: discover and diagram with --format lucid or all, and the dashboard's Lucid downloads	fallback or class	fallback	Shapes whose AWS class name is not verified are drawn as plain rectangles (fallback). class uses the class name anyway.
VPCATLAS_VERSION	install.sh	string	the latest release	Version of the binary to install.
VPCATLAS_INSTALL_DIR	install.sh	path	/usr/local/bin if writable, else ~/.local/bin	Directory for the binary.
VPCATLAS_PORT	deploy/docker-compose.yml	int	8080	Port published on 127.0.0.1 by the compose file. The container still listens on 8080.
LOCAL_UID, LOCAL_GID	deploy/docker-compose.yml	int	10001	User the container runs as, so it can read ~/.aws on Linux.
PORT	the container health check	int	8080	Port the health check calls on loopback. It does not change the port vpcatlas serve listens on, which is the --port option. Change both together.

Options without a variable

These exist as options only.

Option	Command	Default
--host	serve	127.0.0.1 (the image uses 0.0.0.0)
--port	serve	8080
--mfa-serial, --mfa-token	discover, inventory, diagram	none
--output-dir, -o	discover, inventory, diagram	vpcatlas-out
--format, -f	discover, inventory, diagram	all
--level	discover, diagram	all
--strict	discover, inventory, diagram	off
--verbose, -v / --quiet, -q	all commands; written before the command name	warnings and errors

See Command line for each command.

AWS variables

VPC Atlas uses the AWS SDK for Python, so the variables the SDK honours apply. The ones you are most likely to need:

Variable	Effect
AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN	Credentials from the environment. See Credentials.
AWS_PROFILE, AWS_DEFAULT_PROFILE	Profile to use when --profile is not given.
AWS_SHARED_CREDENTIALS_FILE, AWS_CONFIG_FILE	Location of the shared credentials and config files.
AWS_ROLE_ARN, AWS_WEB_IDENTITY_TOKEN_FILE, AWS_ROLE_SESSION_NAME	Web identity credentials, as injected by EKS for IRSA.
AWS_CONTAINER_CREDENTIALS_RELATIVE_URI, AWS_CONTAINER_CREDENTIALS_FULL_URI, AWS_CONTAINER_AUTHORIZATION_TOKEN, AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE	Container credentials, as injected by ECS task roles and EKS Pod Identity.
AWS_EC2_METADATA_DISABLED	Set to true to stop the SDK from calling the instance metadata service. Useful on a laptop where those calls only add a delay.
AWS_STS_REGIONAL_ENDPOINTS	regional makes STS calls go to the regional endpoint. The Docker image sets it to regional, because session tokens from the global endpoint are not valid in opt-in Regions.
AWS_CA_BUNDLE	CA bundle for HTTPS calls, for networks with TLS inspection.

Two of the AWS variables are also read by VPC Atlas itself:

Variable	Read for
AWS_REGION, AWS_DEFAULT_REGION	The dashboard's default scan region when VPCATLAS_REGIONS is unset, and the Region of its STS calls.
AWS_LAMBDA_FUNCTION_NAME	Set by Lambda. Its presence makes the dashboard default to lazy refresh mode.

Examples

A dashboard for one account, every region, rescanned every 15 minutes, behind a password:

VPCATLAS_REGIONS=all \
VPCATLAS_REFRESH_SECONDS=900 \
VPCATLAS_AUTH_PASSWORD="$(cat /run/secrets/atlas)" \
vpcatlas serve --host 0.0.0.0 --profile audit

A dashboard that audits two accounts through roles, keeping its history in S3:

VPCATLAS_ROLE_ARN=arn:aws:iam::111122223333:role/AtlasAuditor,arn:aws:iam::444455556666:role/AtlasAuditor \
VPCATLAS_EXTERNAL_ID=my-external-id \
VPCATLAS_SNAPSHOT_URI=s3://my-bucket/vpcatlas \
VPCATLAS_HISTORY_KEEP=60 \
vpcatlas serve --host 0.0.0.0

The same settings in a container:

docker run --rm -p 127.0.0.1:8080:8080 \
  -e VPCATLAS_ROLE_ARN=arn:aws:iam::111122223333:role/AtlasAuditor \
  -e VPCATLAS_EXTERNAL_ID=my-external-id \
  -e VPCATLAS_REFRESH_SECONDS=900 \
  -e AWS_ACCESS_KEY_ID -e AWS_SECRET_ACCESS_KEY -e AWS_SESSION_TOKEN \
  vpcatlas/vpcatlas