Connect an Azure AKS cluster to Roam

Sign in to Azure from Roam with a device login or a service principal and manage your AKS cluster from your iPhone, Android phone or desktop — no az CLI and no kubelogin on the phone.

Before you start

• Microsoft Entra ID integration must be on for the cluster (AKS-managed Entra ID). Roam signs in with Entra ID tokens; a cluster that only has local accounts with client certificates won't accept them.
• A reachable API server: a private-only cluster has no address your phone can reach, and authorized IP ranges must include your network.
• Two roles for the identity you sign in with:
  • Azure Kubernetes Service Cluster User Role on the cluster, so Roam can read its endpoint and certificate.
  • Access inside Kubernetes: an Azure RBAC role such as Azure Kubernetes Service RBAC Reader or RBAC Writer (when Azure RBAC for Kubernetes is on), or a Kubernetes RoleBinding for your user or group.

Sign in with your Microsoft account (device login)

1. Tap Add Cluster, choose Azure AKS, then Device Login.
2. Enter your Tenant ID and tap Generate Login Code. Open the Microsoft link Roam shows, enter the code and sign in.
3. Enter the Subscription ID, Resource Group and cluster name, then tap Connect Cluster.

az aks list -o table and az account show give you the names and IDs.

Sign in with a service principal

Useful for a shared on-call phone, or when device login is blocked. Create one scoped to the cluster:

CLUSTER_ID=$(az aks show -g my-rg -n prod --query id -o tsv)

az ad sp create-for-rbac --name roam \
  --role "Azure Kubernetes Service Cluster User Role" \
  --scopes "$CLUSTER_ID"

# With Azure RBAC for Kubernetes on: read-only inside the cluster
az role assignment create --assignee <appId> \
  --role "Azure Kubernetes Service RBAC Reader" \
  --scope "$CLUSTER_ID"

1. In Roam, tap Add Cluster, choose Azure AKS, then Service Principal.
2. Enter the Tenant ID, Client ID (App ID) and Client Secret from the output above, then the Subscription ID, Resource Group and cluster name.
3. Tap Connect Cluster.

On the desktop app

The desktop app downloaded from GitHub or the Microsoft Store can use your ~/.kube/config as it is, including kubelogin entries from az aks get-credentials. Versions that run in a store sandbox can't start kubelogin, and offer the AKS sign-in instead.

Troubleshooting

• "Not integrated with Microsoft Entra ID": turn on AKS-managed Entra ID for the cluster, or connect with a kubeconfig or token.
• Private cluster: the Azure sign-in can't reach a private-only API server. Connect with a service-account token through an SSH bastion inside the virtual network instead.
• Forbidden after connecting: the identity has the Cluster User Role but no Kubernetes permissions. Add an Azure RBAC role or a RoleBinding.

Secrets and refresh tokens stay on your device, encrypted in the Keychain or Keystore, and go only to Microsoft and your cluster.