Connect a Google GKE cluster to Roam

Sign in with your Google account and pick a cluster, or use a service account key, then manage it from your iPhone, Android phone or desktop — no gcloud and no auth plugin on the phone.

Sign in with your Google account

In Roam Desktop 1.3.0 and Roam 1.0.20 for iPhone and Android. Versions from the app stores get it as each store publishes the update.

1. Add a cluster, choose Google GKE, then Google account.
2. Click Sign in with Google. On the desktop, Google's page opens in your browser and Roam comes back to the front when you're done. On iPhone it opens inside Roam; on Android, Google's own sign-in sheet appears.
3. Allow Roam to see your Google Kubernetes Engine clusters and your Google Cloud projects. Both are read-only.
4. Pick the cluster from the list — each one shows its project's name and ID — and add it (Test & add on the desktop, Connect Cluster on a phone).

What you can do in the cluster is up to your account's IAM roles and Kubernetes RBAC, as with kubectl: roles/container.viewer to look around, roles/container.developer to scale, restart, edit and delete. The read-only sign-in doesn't narrow that.

Or use a service account key

For a shared or automated setup, or if you'd rather not sign in. You need a service account in the cluster's project with:

• A Kubernetes Engine role: roles/container.viewer to look around, or roles/container.developer to scale, restart, edit and delete. Either one also lets Roam read the cluster's endpoint and certificate.
• Or, for finer control, roles/container.clusterViewer plus Kubernetes RBAC bound to the service account's email address.

Create one and download a JSON key with gcloud:

gcloud iam service-accounts create roam --display-name "Roam"

gcloud projects add-iam-policy-binding PROJECT_ID \
  --member "serviceAccount:roam@PROJECT_ID.iam.gserviceaccount.com" \
  --role roles/container.viewer

gcloud iam service-accounts keys create roam-key.json \
  --iam-account roam@PROJECT_ID.iam.gserviceaccount.com

Connect with the key

1. Tap Add Cluster, choose Google GKE, then Service Account Key.
2. Paste the contents of the key file into Service Account JSON. Getting it onto your phone through a password manager or AirDrop beats emailing it to yourself.
3. Enter the GKE Cluster Name and its Location — the region or zone, like us-central1 or europe-west1-b. The Project ID defaults to the project in the key; fill it in if the cluster lives elsewhere.
4. Tap Connect Cluster. Roam reads the endpoint and certificate from Google Cloud, checks access, and opens the cluster.

Not sure of the name and location? gcloud container clusters list shows both.

On the desktop app

The desktop app downloaded from GitHub or the Microsoft Store can use your ~/.kube/config as it is, including the gke-gcloud-auth-plugin entries gcloud container clusters get-credentials writes. Versions that run in a store sandbox can't start that plugin, and offer the GKE sign-in instead.

Troubleshooting

• No clusters after signing in: your account has no Kubernetes Engine role in the projects it can see, or those projects don't have the Kubernetes Engine API turned on.
• Asked to sign in with Google again: the sign-in was removed from your Google Account, went unused for a long time, or your organization requires signing in again from time to time.
• Permission denied while looking up the cluster: the account has no Kubernetes Engine role in that project, or the Project ID points at another project.
• Connected, but lists are empty or Forbidden: the role doesn't cover those resources. Grant roles/container.developer, or bind Kubernetes RBAC to the account.
• Only a private endpoint: turn on the cluster's DNS-based endpoint with gcloud container clusters update CLUSTER --enable-dns-access, and Roam can reach it from anywhere.
• Times out: the cluster is private, or its control plane only accepts authorized networks. Allow your network, or reach it through an SSH bastion.

The key stays on your device, encrypted in the Keychain or Keystore, and is used only to get short-lived tokens from Google. Delete the key in Google Cloud whenever you stop using it.