Amazon ECS (Fargate)¶

deploy/ecs/task-definition.json is a Fargate task for the dashboard, and deploy/ecs/README.md has the short version of this page. The task definition is the source of truth.

One task is enough: the snapshot lives in the memory of the task, unless you add snapshot storage (below).

The task definition¶

Field	Value in the file	Notes
`family`	`vpcatlas`
`networkMode`, `requiresCompatibilities`	`awsvpc`, `FARGATE`
`cpu`, `memory`	`512`, `1024`	Enough for a typical account. If a scan of a very large estate is killed (exit code 137), use `1024` and `2048`.
`runtimePlatform`	`X86_64`, `LINUX`	For Arm, set `"cpuArchitecture": "ARM64"`. The release image is multi-architecture.
`executionRoleArn`	`...:role/vpcatlas-execution`	Replace the account id `123456789012`.
`taskRoleArn`	`...:role/vpcatlas-auditor`	The identity the dashboard uses to read AWS.
container `name`	`vpcatlas`
`image`	`vpcatlas/vpcatlas:0.1.0`	Pin a release tag.
`user`, `readonlyRootFilesystem`	`10001:10001`, `true`	`/tmp` is a writable volume named `tmp`.
`portMappings`	`8080/tcp`
`environment`	`VPCATLAS_REFRESH_SECONDS=900`, `VPCATLAS_REGIONS=all`	The image command is already `serve --host 0.0.0.0 --port 8080`, so the file sets no `command`.
`healthCheck`	`python -m vpcatlas.dashboard.healthcheck`, every 30 s	Requests `/healthz` on the loopback address.
`logConfiguration`	`awslogs`, group `/ecs/vpcatlas`, Region `eu-west-1`	Create the log group first, and change the Region to yours.

Roles¶

Role	Purpose	Permissions
Task role (`vpcatlas-auditor`)	What the dashboard uses to read AWS.	The auditor policy in `deploy/iam/auditor-policy.json`, also printed by `vpcatlas iam-policy`, or the managed `ReadOnlyAccess`.
Execution role (`vpcatlas-execution`)	What ECS uses to start the task.	The managed policy `AmazonECSTaskExecutionRolePolicy`: log delivery, and image pull if the image is private. Add `secretsmanager:GetSecretValue` on the secret if you use the `secrets` block below.

The container never needs access keys: the SDK reads the task role through the container credentials endpoint that ECS provides. To audit other accounts, give the task role sts:AssumeRole on their auditor roles and add VPCATLAS_ROLE_ARN (comma separated) to environment, plus VPCATLAS_EXTERNAL_ID when their trust policies have one. The trust policy to put on those roles is in iam.md.

Deploy¶

aws logs create-log-group --log-group-name /ecs/vpcatlas --region eu-west-1

aws ecs register-task-definition --cli-input-json file://deploy/ecs/task-definition.json --region eu-west-1

aws ecs create-service \
  --cluster my-cluster \
  --service-name vpcatlas \
  --task-definition vpcatlas \
  --desired-count 1 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-aaaa,subnet-bbbb],securityGroups=[sg-cccc],assignPublicIp=DISABLED}" \
  --load-balancers "targetGroupArn=arn:aws:elasticloadbalancing:eu-west-1:123456789012:targetgroup/atlas/abc123,containerName=vpcatlas,containerPort=8080" \
  --region eu-west-1

containerName must be the name of the container in the task definition, vpcatlas.

Load balancer and network¶

Target group: protocol HTTP, port 8080, target type ip, health check path /healthz.
Use an internal Application Load Balancer, or an internet-facing one with OIDC or Cognito authentication on the listener. The dashboard shows your network topology, so do not leave it open. As a minimum set VPCATLAS_AUTH_PASSWORD (HTTP Basic) from Secrets Manager. Add this to the container definition and let the execution role read the secret:

"secrets": [
  { "name": "VPCATLAS_AUTH_PASSWORD", "valueFrom": "arn:aws:secretsmanager:eu-west-1:123456789012:secret:atlas-auth-AbCdEf" }
]

The security group of the task needs inbound 8080 from the load balancer, and outbound 443 to the AWS APIs (a NAT gateway or VPC endpoints for EC2, STS, ELB, Network Firewall, Route 53 Resolver, RAM, Direct Connect and S3).
If the load balancer serves the dashboard under a path, set VPCATLAS_BASE_PATH; see the dashboard page.

Snapshot storage and more than one task¶

With the files as shipped, a restart of the task loses the history and every task scans on its own. To keep the history and let tasks share the last snapshot, set VPCATLAS_SNAPSHOT_URI=s3://bucket/prefix and add to the task role:

s3:GetObject, s3:PutObject, s3:DeleteObject on arn:aws:s3:::bucket/prefix/*;
s3:ListBucket on arn:aws:s3:::bucket, with the condition s3:prefix = prefix/* (the history of the scans lives under that prefix, and without ListBucket a missing object is reported as a read error).

Only one writer is assumed. Several tasks that all scan would overwrite each other's history, so with more than one task let a single scheduled task scan, or set VPCATLAS_REFRESH_MODE=lazy, VPCATLAS_SCAN_ON_REQUEST=false and a VPCATLAS_REFRESH_SECONDS above 0 on the others, so that they only read the snapshot the scanning task stored. The keys written are listed in the dashboard page.

Notes¶

VPCATLAS_REFRESH_SECONDS is the interval between scans; the floor is VPCATLAS_MIN_REFRESH_SECONDS (300).
VPCATLAS_REGIONS takes a list or all.
Every VPCATLAS_* variable is in the dashboard page, taken from settings.py.