Connect a Google GKE cluster to Roam

Connect Roam to Google Kubernetes Engine with a service account key, then manage the cluster from your iPhone, Android phone or desktop — no gcloud and no auth plugin on the phone.

Before you start

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 in Roam

1. Tap Add Cluster and choose Google GKE.
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

• Permission denied while looking up the cluster: the service 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 service account.
• 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.