Architecture Maps
Mapping Reference: Commands, Permissions, Coverage
Every command and flag, the exact read-only commands that are run, the permissions to grant for each source, and everything that is drawn.
10 min read
Every command takes --json for scripts (messages go to stderr), --yes to answer confirmations, and --help with examples.
viewert graph map aws|gcp|azure|k8s- What it does
- Read an environment (or a file, with
--from-snapshot), build the Graph, save it private
viewert graph map terraform <file|->- What it does
- Draw a Terraform state or plan
viewert graph snapshot aws|gcp|azure|k8s- What it does
- Read an environment into a snapshot file; nothing is uploaded
viewert graph build <file>- What it does
- Turn a snapshot, an export, an inventory, manifests, a template or a Terraform file into a Graph file, offline
viewert graph import <file>- What it does
- Save a VGF file (or anything
buildreads) as a private Graph
viewert graph export <id> [--format inventory]- What it does
- Export a Graph as VGF or as a cloud inventory
viewert graph diff <earlier> <later>- What it does
- What was added, removed and changed between two maps
| Command | What it does |
|---|---|
viewert graph map aws|gcp|azure|k8s | Read an environment (or a file, with --from-snapshot), build the Graph, save it private |
viewert graph map terraform <file|-> | Draw a Terraform state or plan |
viewert graph snapshot aws|gcp|azure|k8s | Read an environment into a snapshot file; nothing is uploaded |
viewert graph build <file> | Turn a snapshot, an export, an inventory, manifests, a template or a Terraform file into a Graph file, offline |
viewert graph import <file> | Save a VGF file (or anything build reads) as a private Graph |
viewert graph export <id> [--format inventory] | Export a Graph as VGF or as a cloud inventory |
viewert graph diff <earlier> <later> | What was added, removed and changed between two maps |
The ones that choose what is read, and what happens to it.
--profile, --region/-r, --all-regions- Applies to
- aws
- Meaning
- Which AWS profile and Regions (repeat
--region)
--project/-p- Applies to
- gcp
- Meaning
- The Google Cloud project id
--subscription, --resource-group/-g- Applies to
- azure
- Meaning
- Subscription ids and resource groups (repeatable)
--context, --namespace/-n- Applies to
- k8s
- Meaning
- The kubeconfig context and namespaces (repeatable)
--only, --skip- Applies to
- aws, gcp, k8s
- Meaning
- Services (aws, gcp) or groups (k8s: namespaces, workloads, network, storage) to read or leave out
--account, --region, --project, --subscription, --namespace- Applies to
- with
--from-snapshot - Meaning
- Choose which part of a file that holds several
--from-snapshot <file>- Applies to
- all
- Meaning
- Read a file instead of the environment: nothing is contacted
--snapshot-out <file>- Applies to
- all
- Meaning
- Also keep the raw, secret-stripped answers
--out/-o <file>, --no-upload- Applies to
- all
- Meaning
- Write the Graph to a file; do not save it to Viewert
--dry-run- Applies to
- all
- Meaning
- Show what would be run and built; call nothing, create nothing
--open, --title- Applies to
- all
- Meaning
- Open the Graph when saved; set its title
--replace <id>- Applies to
- all
- Meaning
- Replace the contents of an existing Graph (asks first;
--yesin scripts)
--save, --fail-on-change- Applies to
- diff
- Meaning
- Save the marked Graph; exit with an error when the maps differ
| Flag | Applies to | Meaning |
|---|---|---|
--profile, --region/-r, --all-regions | aws | Which AWS profile and Regions (repeat --region) |
--project/-p | gcp | The Google Cloud project id |
--subscription, --resource-group/-g | azure | Subscription ids and resource groups (repeatable) |
--context, --namespace/-n | k8s | The kubeconfig context and namespaces (repeatable) |
--only, --skip | aws, gcp, k8s | Services (aws, gcp) or groups (k8s: namespaces, workloads, network, storage) to read or leave out |
--account, --region, --project, --subscription, --namespace | with --from-snapshot | Choose which part of a file that holds several |
--from-snapshot <file> | all | Read a file instead of the environment: nothing is contacted |
--snapshot-out <file> | all | Also keep the raw, secret-stripped answers |
--out/-o <file>, --no-upload | all | Write the Graph to a file; do not save it to Viewert |
--dry-run | all | Show what would be run and built; call nothing, create nothing |
--open, --title | all | Open the Graph when saved; set its title |
--replace <id> | all | Replace the contents of an existing Graph (asks first; --yes in scripts) |
--save, --fail-on-change | diff | Save the marked Graph; exit with an error when the maps differ |
These are the whole of what is ever asked of a provider, enforced where each command line is built: anything else is refused before it runs. --dry-run prints the ones a map starts with.
AWS (49)
- Commands
sts get-caller-identity,iam list-account-aliases;ec2describe-regions, -vpcs, -subnets, -route-tables, -instances, -security-groups;autoscaling describe-auto-scaling-groups;elbv2describe-load-balancers, -target-groups, -listeners, -target-health;elb describe-load-balancers;rdsdescribe-db-instances, -db-clusters;elasticachedescribe-cache-clusters, -replication-groups, -cache-subnet-groups;lambdalist-functions, list-event-source-mappings, list-function-url-configs;sqs list-queues;snslist-topics, list-subscriptions;dynamodb list-tables;kinesis list-streams;ecslist-clusters, list-services, describe-services;ekslist-clusters, describe-cluster;apigatewayv2get-apis, get-integrations;apigatewayget-rest-apis, get-resources;stepfunctionslist-state-machines, describe-state-machine;opensearchlist-domain-names, describe-domains;eventslist-rules, list-targets-by-rule;efs describe-file-systems;kafka list-clusters-v2;s3apilist-buckets, get-bucket-location;cloudfront list-distributions;route53list-hosted-zones, list-resource-record-sets
Google Cloud (22)
- Commands
projects describe;computenetworks list, networks subnets list, instances list, firewall-rules list, instance-groups managed list, network-endpoint-groups list, forwarding-rules list, target-http-proxies list, target-https-proxies list, url-maps list, backend-services list;container clusters list;sql instances list;run services list;functions list;storage buckets list;pubsubtopics list, subscriptions list;dnsmanaged-zones list, record-sets list;asset search-all-resources
Azure (3)
- Commands
az account show;az graph querywith one of two fixed queries: every resource with its properties (optionally filtered to resource groups whose names have been checked), and the subscriptions and resource groups
Kubernetes (10)
- Commands
kubectl config current-context;kubectl getnamespaces, deployments, statefulsets, daemonsets, cronjobs, services, ingresses, horizontalpodautoscalers, persistentvolumeclaims (never secrets, configmaps or pods)
| Source | Commands |
|---|---|
| AWS (49) | sts get-caller-identity, iam list-account-aliases; ec2 describe-regions, -vpcs, -subnets, -route-tables, -instances, -security-groups; autoscaling describe-auto-scaling-groups; elbv2 describe-load-balancers, -target-groups, -listeners, -target-health; elb describe-load-balancers; rds describe-db-instances, -db-clusters; elasticache describe-cache-clusters, -replication-groups, -cache-subnet-groups; lambda list-functions, list-event-source-mappings, list-function-url-configs; sqs list-queues; sns list-topics, list-subscriptions; dynamodb list-tables; kinesis list-streams; ecs list-clusters, list-services, describe-services; eks list-clusters, describe-cluster; apigatewayv2 get-apis, get-integrations; apigateway get-rest-apis, get-resources; stepfunctions list-state-machines, describe-state-machine; opensearch list-domain-names, describe-domains; events list-rules, list-targets-by-rule; efs describe-file-systems; kafka list-clusters-v2; s3api list-buckets, get-bucket-location; cloudfront list-distributions; route53 list-hosted-zones, list-resource-record-sets |
| Google Cloud (22) | projects describe; compute networks list, networks subnets list, instances list, firewall-rules list, instance-groups managed list, network-endpoint-groups list, forwarding-rules list, target-http-proxies list, target-https-proxies list, url-maps list, backend-services list; container clusters list; sql instances list; run services list; functions list; storage buckets list; pubsub topics list, subscriptions list; dns managed-zones list, record-sets list; asset search-all-resources |
| Azure (3) | az account show; az graph query with one of two fixed queries: every resource with its properties (optionally filtered to resource groups whose names have been checked), and the subscriptions and resource groups |
| Kubernetes (10) | kubectl config current-context; kubectl get namespaces, deployments, statefulsets, daemonsets, cronjobs, services, ingresses, horizontalpodautoscalers, persistentvolumeclaims (never secrets, configmaps or pods) |
Give the identity that runs a map exactly this, and nothing more.
json
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ViewertReadOnlyMap",
"Effect": "Allow",
"Action": [
"apigateway:GET",
"autoscaling:DescribeAutoScalingGroups",
"cloudfront:ListDistributions",
"dynamodb:ListTables",
"ec2:DescribeInstances",
"ec2:DescribeRegions",
"ec2:DescribeRouteTables",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSubnets",
"ec2:DescribeVpcs",
"ecs:DescribeServices",
"ecs:ListClusters",
"ecs:ListServices",
"eks:DescribeCluster",
"eks:ListClusters",
"elasticache:DescribeCacheClusters",
"elasticache:DescribeCacheSubnetGroups",
"elasticache:DescribeReplicationGroups",
"elasticfilesystem:DescribeFileSystems",
"elasticloadbalancing:DescribeListeners",
"elasticloadbalancing:DescribeLoadBalancers",
"elasticloadbalancing:DescribeTargetGroups",
"elasticloadbalancing:DescribeTargetHealth",
"es:DescribeDomains",
"es:ListDomainNames",
"events:ListRules",
"events:ListTargetsByRule",
"iam:ListAccountAliases",
"kafka:ListClustersV2",
"kinesis:ListStreams",
"lambda:ListEventSourceMappings",
"lambda:ListFunctionUrlConfigs",
"lambda:ListFunctions",
"rds:DescribeDBClusters",
"rds:DescribeDBInstances",
"route53:ListHostedZones",
"route53:ListResourceRecordSets",
"s3:GetBucketLocation",
"s3:ListAllMyBuckets",
"sns:ListSubscriptions",
"sns:ListTopics",
"sqs:ListQueues",
"states:DescribeStateMachine",
"states:ListStateMachines"
],
"Resource": "*"
}
]
}AWS
The ReadOnlyAccess managed policy covers it. For something narrower, this policy is generated from the allowlist, so it cannot drift from what is run (sts:GetCallerIdentity needs no permission).
Roles for the other sources.
yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: viewert-map-reader
rules:
- apiGroups: [""]
resources: [namespaces, services, persistentvolumeclaims]
verbs: [get, list]
- apiGroups: ["apps"]
resources: [deployments, statefulsets, daemonsets]
verbs: [get, list]
- apiGroups: ["batch"]
resources: [cronjobs]
verbs: [get, list]
- apiGroups: ["networking.k8s.io"]
resources: [ingresses]
verbs: [get, list]
- apiGroups: ["autoscaling"]
resources: [horizontalpodautoscalers]
verbs: [get, list]Google Cloud
- Grant
roles/vieweron the project, plusroles/cloudasset.viewerfor what is read through the Asset Inventory- Notes
- The Cloud Asset API must be enabled for those products
Azure
- Grant
Readeron each subscription (or on a management group)- Notes
- Resource Graph returns only what the identity may read. The Azure CLI needs the extension:
az extension add --name resource-graph
Kubernetes
- Grant
- The ClusterRole below, bound to the user or group your kubeconfig uses
- Notes
kubectl getacross namespaces needslist; no Secrets, ConfigMaps or Pods are included
| Source | Grant | Notes |
|---|---|---|
| Google Cloud | roles/viewer on the project, plus roles/cloudasset.viewer for what is read through the Asset Inventory | The Cloud Asset API must be enabled for those products |
| Azure | Reader on each subscription (or on a management group) | Resource Graph returns only what the identity may read. The Azure CLI needs the extension: az extension add --name resource-graph |
| Kubernetes | The ClusterRole below, bound to the user or group your kubeconfig uses | kubectl get across namespaces needs list; no Secrets, ConfigMaps or Pods are included |
How each resource type is drawn. “Fact” means it is read and shown on the resources it belongs to, not as a box.
AWS
- Drawn as boxes
- EC2, Auto Scaling, ECS, EKS, Lambda, Step Functions, ALB/NLB/CLB, API Gateway, CloudFront, Route 53, RDS/Aurora, ElastiCache, OpenSearch, DynamoDB, S3, EFS, SQS, SNS, Kinesis, EventBridge, MSK
- Read as facts and lines
- Security groups, route tables and subnets (tiers, exposure, inferred lines), listeners, target groups, subscriptions, event-source mappings, function URLs
Google Cloud
- Drawn as boxes
- Compute Engine, managed instance groups, GKE, Cloud Run, Cloud Functions, Cloud SQL, Cloud Storage, Pub/Sub, Cloud Load Balancing, Cloud DNS, Memorystore, Spanner, Bigtable, BigQuery, AlloyDB, Filestore, Vertex AI
- Read as facts and lines
- Firewall rules, networks, subscriptions
Azure
- Drawn as boxes
- Virtual machines, scale sets, AKS, Container Apps and Instances, App Service, Functions, Load Balancer, Application Gateway, Front Door and CDN, Traffic Manager, Firewall, Bastion, VPN gateways, NAT, Private endpoints, DNS, API Management, SQL, PostgreSQL, MySQL, Cosmos DB, Redis, Storage, Key Vault, Container Registry, AI Search, Service Bus, Event Hubs, Event Grid, SignalR, Synapse, Databricks, Data Factory, Machine Learning, Logic Apps
- Read as facts and lines
- Network interfaces, public IPs, NSGs, route tables, App Service plans, databases of a server, record sets, origins, event subscriptions
Kubernetes
- Drawn as boxes
- Deployments, StatefulSets, DaemonSets, CronJobs, LoadBalancer and NodePort Services, Ingresses, volume claims
- Read as facts and lines
- ClusterIP Services, selectors, autoscalers, environment-variable hosts
Terraform
- Drawn as boxes
- The AWS,
google_*andazurerm_*types above, plus ECR, internet and NAT gateways, Neptune, Artifact Registry - Read as facts and lines
- Everything that wires them: rules, associations, attachments, policies' targets
| Provider | Drawn as boxes | Read as facts and lines |
|---|---|---|
| AWS | EC2, Auto Scaling, ECS, EKS, Lambda, Step Functions, ALB/NLB/CLB, API Gateway, CloudFront, Route 53, RDS/Aurora, ElastiCache, OpenSearch, DynamoDB, S3, EFS, SQS, SNS, Kinesis, EventBridge, MSK | Security groups, route tables and subnets (tiers, exposure, inferred lines), listeners, target groups, subscriptions, event-source mappings, function URLs |
| Google Cloud | Compute Engine, managed instance groups, GKE, Cloud Run, Cloud Functions, Cloud SQL, Cloud Storage, Pub/Sub, Cloud Load Balancing, Cloud DNS, Memorystore, Spanner, Bigtable, BigQuery, AlloyDB, Filestore, Vertex AI | Firewall rules, networks, subscriptions |
| Azure | Virtual machines, scale sets, AKS, Container Apps and Instances, App Service, Functions, Load Balancer, Application Gateway, Front Door and CDN, Traffic Manager, Firewall, Bastion, VPN gateways, NAT, Private endpoints, DNS, API Management, SQL, PostgreSQL, MySQL, Cosmos DB, Redis, Storage, Key Vault, Container Registry, AI Search, Service Bus, Event Hubs, Event Grid, SignalR, Synapse, Databricks, Data Factory, Machine Learning, Logic Apps | Network interfaces, public IPs, NSGs, route tables, App Service plans, databases of a server, record sets, origins, event subscriptions |
| Kubernetes | Deployments, StatefulSets, DaemonSets, CronJobs, LoadBalancer and NodePort Services, Ingresses, volume claims | ClusterIP Services, selectors, autoscalers, environment-variable hosts |
| Terraform | The AWS, google_* and azurerm_* types above, plus ECR, internet and NAT gateways, Neptune, Artifact Registry | Everything that wires them: rules, associations, attachments, policies' targets |
The words the maps use.
Declared
A relationship written down in the configuration, with the line that says where.
Inferred
A relationship concluded from configuration (a security group or firewall rule, an environment variable), drawn dotted.
Evidence
The description on every connection: what in the configuration shows it.
Layer
Edge, Compute, Data, Messaging, and Network access: families a viewer switches on and off.
Exposure
What a resource's own configuration says about the internet reaching it. A fact, not a verdict.
Snapshot
The raw, secret-stripped answers of a read, as a file. Anyone can build a Graph from it.
Inventory
A description of a Graph as resources, boundaries and connections, for reviews, diffs and other tools.
VGF
Viewert's open Graph format; see the VGF guide.