Guide

Connect AWS

About 5 minutes in the AWS console. VizTopo signs in to your account as a dedicated IAM user whose policy can only describe EC2 resources, read CloudWatch CPU metrics and look up prices. You paste its access key into VizTopo once: it's stored encrypted on the server and never sent back to your browser.

1. Create the VizTopoReadOnly policy

In the IAM console: Policies → Create policy → JSON. Replace everything in the editor with this policy, choose Next, name it VizTopoReadOnly and choose Create policy.

IAM policy (JSON)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VizTopoInventory",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceStatus",
        "ec2:DescribeInstanceTypes",
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeSecurityGroupRules",
        "ec2:DescribeNetworkInterfaces",
        "ec2:DescribeVolumes",
        "ec2:DescribeRegions",
        "cloudwatch:GetMetricData",
        "pricing:GetProducts",
        "ec2:DescribeAddresses",
        "ec2:DescribeNatGateways",
        "ec2:DescribeSnapshots",
        "elasticloadbalancing:DescribeLoadBalancers",
        "s3:ListAllMyBuckets",
        "ec2:DescribeRouteTables",
        "ec2:DescribeNetworkAcls",
        "ec2:DescribeVpcEndpoints"
      ],
      "Resource": "*"
    }
  ]
}

To compare VizTopo's estimates with what AWS actually billed, add Cost Explorer: one more statement allowing ce:GetCostAndUsage.

Or with the AWS CLI (an admin profile)

cat > viztopo-readonly.json <<'JSON'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VizTopoInventory",
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ec2:DescribeInstanceStatus",
        "ec2:DescribeInstanceTypes",
        "ec2:DescribeVpcs",
        "ec2:DescribeSubnets",
        "ec2:DescribeSecurityGroups",
        "ec2:DescribeSecurityGroupRules",
        "ec2:DescribeNetworkInterfaces",
        "ec2:DescribeVolumes",
        "ec2:DescribeRegions",
        "cloudwatch:GetMetricData",
        "pricing:GetProducts",
        "ec2:DescribeAddresses",
        "ec2:DescribeNatGateways",
        "ec2:DescribeSnapshots",
        "elasticloadbalancing:DescribeLoadBalancers",
        "s3:ListAllMyBuckets",
        "ec2:DescribeRouteTables",
        "ec2:DescribeNetworkAcls",
        "ec2:DescribeVpcEndpoints"
      ],
      "Resource": "*"
    }
  ]
}
JSON
aws iam create-policy --policy-name VizTopoReadOnly --policy-document file://viztopo-readonly.json

2. Create the IAM user viztopo and its access key

Users → Create user. User name viztopo, console access off, Next. Choose Attach policies directly, tick VizTopoReadOnly, Next → Create user.

Then open the user → Security credentials → Create access key, use case Application running outside AWS. AWS shows the secret only once: paste it into VizTopo in the next step, and nowhere else.

Or with the AWS CLI

aws iam create-user --user-name viztopo
aws iam attach-user-policy --user-name viztopo \
  --policy-arn "arn:aws:iam::$(aws sts get-caller-identity --query Account --output text):policy/VizTopoReadOnly"
aws iam create-access-key --user-name viztopo   # prints AccessKeyId and SecretAccessKey once

3. Add the connection

In VizTopo: Connections → Add connection → Amazon Web Services → Guide me. Paste the access key ID and secret, pick the regions to read, and Test connection: it checks every permission, and fails on root account keys. Nothing is saved until you choose Save connection.

4. Optional: allow changes on tagged resources

This policy allows start, stop and reboot, security group rules, changing an instance's groups and creating groups, only on resources tagged viztopo-control = true. Attach it to the same user, tag what VizTopo may change, then turn on write mode for the connection by typing its name.

Control policy (JSON)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VizTopoPowerTaggedOnly",
      "Effect": "Allow",
      "Action": [
        "ec2:StartInstances",
        "ec2:StopInstances",
        "ec2:RebootInstances"
      ],
      "Resource": "arn:aws:ec2:*:*:instance/*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/viztopo-control": "true"
        }
      }
    },
    {
      "Sid": "VizTopoPortsTaggedOnly",
      "Effect": "Allow",
      "Action": [
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:RevokeSecurityGroupIngress",
        "ec2:AuthorizeSecurityGroupEgress",
        "ec2:RevokeSecurityGroupEgress"
      ],
      "Resource": "arn:aws:ec2:*:*:security-group/*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/viztopo-control": "true"
        }
      }
    },
    {
      "Sid": "VizTopoInstanceGroupsTaggedOnly",
      "Effect": "Allow",
      "Action": "ec2:ModifyInstanceAttribute",
      "Resource": [
        "arn:aws:ec2:*:*:instance/*",
        "arn:aws:ec2:*:*:security-group/*"
      ],
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/viztopo-control": "true"
        }
      }
    },
    {
      "Sid": "VizTopoNewGroupsInTaggedVpcs",
      "Effect": "Allow",
      "Action": "ec2:CreateSecurityGroup",
      "Resource": "arn:aws:ec2:*:*:vpc/*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/viztopo-control": "true"
        }
      }
    },
    {
      "Sid": "VizTopoNewGroupsAreTagged",
      "Effect": "Allow",
      "Action": "ec2:CreateSecurityGroup",
      "Resource": "arn:aws:ec2:*:*:security-group/*",
      "Condition": {
        "StringEquals": {
          "aws:RequestTag/viztopo-control": "true"
        }
      }
    },
    {
      "Sid": "VizTopoTagOnlyWhenCreating",
      "Effect": "Allow",
      "Action": "ec2:CreateTags",
      "Resource": "arn:aws:ec2:*:*:security-group/*",
      "Condition": {
        "StringEquals": {
          "ec2:CreateAction": "CreateSecurityGroup"
        }
      }
    }
  ]
}

5. Optional: SSH without a key

VizTopo can open a terminal to an instance the way EC2 Instance Connect does: it uploads a one-time public key that the instance accepts for 60 seconds. It needs this policy, the instance tagged viztopo-control = true, the EC2 Instance Connect agent on the instance, and its SSH port open to VizTopo's server address.

Instance Connect policy (JSON)

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VizTopoInstanceConnectTaggedOnly",
      "Effect": "Allow",
      "Action": "ec2-instance-connect:SendSSHPublicKey",
      "Resource": "arn:aws:ec2:*:*:instance/*",
      "Condition": {
        "StringEquals": {
          "aws:ResourceTag/viztopo-control": "true"
        }
      }
    }
  ]
}

Questions

Why an IAM user and not a role?

viztopo.com signs in from outside your account, so on viztopo.com VizTopo uses a dedicated IAM user's access key. Its policy only reads, and you can deactivate the key in IAM at any time.

Does VizTopo keep my secret access key?

Yes, encrypted with AES-256-GCM on the server, so it can keep reading. It's never sent back to your browser and never logged. Remove the connection or deactivate the key to stop it.

Can VizTopo terminate instances?

No. None of these policies allow it, and VizTopo has no such action.

Updated October 21, 2026