Guide
Connect Google Cloud
About 5 minutes, in the Google Cloud console or Cloud Shell. VizTopo reads one project's Compute Engine (VMs, VPC networks, subnets, firewall rules, disks and IP addresses) as a service account with Google's read-only Compute Viewer role, and signs in with a read-only token, so it can't change anything with it. You give VizTopo the service account's key once: it's stored encrypted on the server and never sent back to your browser.
1. Turn on the APIs
In the project VizTopo will read, turn on the Compute Engine API and the Cloud Resource Manager API (the second lets VizTopo check its own permissions): APIs & Services → Library, find each one and choose Enable. Compute Engine needs billing on the project.
2. Create the service account and its key
IAM & Admin → Service accounts → Create service account. Name it viztopo, choose Create and continue, give it the role Compute Engine → Compute Viewer, and choose Done.
Open the new service account, then Keys → Add key → Create new key → JSON → Create. Your browser downloads the key file: you'll give it to VizTopo in the next step, and can delete it after.
Or all of it in Cloud Shell, with your project's ID:
gcloud services enable compute.googleapis.com cloudresourcemanager.googleapis.com --project=PROJECT_ID gcloud iam service-accounts create viztopo --display-name="VizTopo (read-only)" --project=PROJECT_ID gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:viztopo@PROJECT_ID.iam.gserviceaccount.com --role=roles/compute.viewer --condition=None gcloud iam service-accounts keys create viztopo-key.json --iam-account=viztopo@PROJECT_ID.iam.gserviceaccount.com
If Google won't create a key, your organization has the policy *Disable service account key creation*: an organization admin can allow it for this project.
3. Add the connection
In VizTopo: Connections → Add connection → Google Cloud. Load or paste the key file; the project ID comes from it, or type another project the service account can read. Test connection signs in, checks the Compute Engine API and the permissions; nothing is saved until you choose Save connection.
4. Optional: start and stop VMs
VizTopo can start a stopped VM and stop a running one (a graceful shutdown), with write mode on for the connection and your rules allowing it. It needs a small custom role with only those permissions, on the whole project, or on just the VMs you choose. It never deletes or resets a VM, and won't stop one with a local SSD, whose data stopping it would lose.
gcloud iam roles create vizTopoPower --project=PROJECT_ID --title="VizTopo power" --description="Start and stop VMs from VizTopo" --permissions=compute.instances.get,compute.instances.start,compute.instances.stop,compute.zoneOperations.get --stage=GA gcloud projects add-iam-policy-binding PROJECT_ID --member=serviceAccount:viztopo@PROJECT_ID.iam.gserviceaccount.com --role=projects/PROJECT_ID/roles/vizTopoPower --condition=None # Or only on some VMs, instead of the line above, for each one: # gcloud compute instances add-iam-policy-binding VM_NAME --zone=ZONE --member=serviceAccount:viztopo@PROJECT_ID.iam.gserviceaccount.com --role=projects/PROJECT_ID/roles/vizTopoPower --project=PROJECT_ID
Questions
Why a service account key?
viztopo.com signs in from outside your Google Cloud organization, so it needs a credential of its own. The key's service account has only the Compute Viewer role, VizTopo asks Google for read-only tokens with it, and you can delete the key in Google Cloud at any time.
Does VizTopo keep the key?
Yes, encrypted with AES-256-GCM on the server, so it can keep reading. Only the fields it needs are kept. It's never sent back to your browser and never logged. Remove the connection, or delete the key in Google Cloud, to stop it.
Can VizTopo delete my VMs?
No. Compute Viewer only reads, and the optional power role only starts and stops VMs. VizTopo has no delete action.
Updated