Connect any Kubernetes cluster with a kubeconfig or token

For k3s, kind, minikube, self-managed and on-premises clusters — or any cluster you'd rather reach with a token. Import a kubeconfig, or give Roam the API server URL and a service-account token.

Import a kubeconfig

1. Tap Add Cluster and choose Import Kubeconfig.
2. Choose File to pick the file, or Paste Content to paste it. On the desktop app you can also choose Use kubeconfig from this computer to read ~/.kube/config.
3. If the file has several contexts, pick one, then tap Connect Cluster. Add the file again for each other context you want.

Roam takes the server, certificates and credentials from the kubeconfig: tokens and client certificates both work.

Local clusters: k3s, kind and minikube

Their kubeconfigs point at 127.0.0.1 — the computer the cluster runs on. On that computer, the desktop app connects as is. From a phone, 127.0.0.1 is the phone itself, so:

• Change server: to the machine's address on your network, like https://192.168.1.20:6443.
• The API server's certificate has to include that address. For k3s, start the server with --tls-san 192.168.1.20; its kubeconfig is /etc/rancher/k3s/k3s.yaml.
• kind and minikube are set up for the machine they run on — their API servers aren't exposed to your network by default — so they are easiest to use from the desktop app there.

Connect with a service-account token

A token works for any cluster, survives kubeconfig changes, and can be limited to exactly what you want to do from your phone. Create a service account and give it a role — view to look, edit to change workloads, cluster-admin for everything:

kubectl create serviceaccount roam -n kube-system

kubectl create clusterrolebinding roam-view \
  --clusterrole=view --serviceaccount=kube-system:roam

kubectl create token roam -n kube-system --duration=720h

The API server may cap how long a token lasts. For one that doesn't expire, create a kubernetes.io/service-account-token Secret for the service account and use its token.

1. Tap Add Cluster and choose Manual/Token.
2. Enter a Cluster Name, the API Server URL (kubectl cluster-info shows it) and paste the Bearer Token.
3. Under TLS Options, paste the cluster's CA certificate if it isn't signed by a public authority. Then tap Connect Cluster.

TLS options

• Cluster CA certificate: the PEM certificate that signed the API server's. It's the base64 certificate-authority-data in a kubeconfig, decoded.
• Skip TLS verification: only for a lab cluster with a self-signed certificate and no CA to give. Anyone on the network path could read the traffic.

Reach a private cluster through an SSH bastion

If the API server is only reachable inside a private network, Roam can tunnel through an SSH server there. Open Advanced Settings when adding the cluster and fill in:

• SSH Host, Port and SSH User.
• An SSH Password or an SSH Private Key (with its passphrase, if it has one).
• Optionally the Host Key Fingerprint. Left blank, Roam pins the key the bastion presents on the first connection. To check it against a known key, get it with:

ssh-keyscan -t ed25519 bastion.example.com | ssh-keygen -lf -

Everything you enter — kubeconfigs, tokens, keys and passwords — is encrypted on your device and used only to talk to your bastion and your cluster. See the features for what to do next.