Connect an Amazon EKS cluster to Roam

Sign in to AWS from Roam, pick one of your EKS clusters, and manage it from your iPhone, Android phone or desktop. No kubeconfig and no AWS CLI on the phone.

Before you start

You need an AWS identity — an IAM user or an IAM Identity Center (SSO) role — that can do two things:

1. Find the cluster: call eks:ListClusters and eks:DescribeCluster in the cluster's region. Roam uses them to list your clusters and read each one's endpoint and certificate.
2. Get into the cluster: be granted access to its Kubernetes API, through an EKS access entry (recommended) or the older aws-auth ConfigMap.

A minimal IAM policy for the first part:

{
  "Version": "2012-10-17",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["eks:ListClusters", "eks:DescribeCluster"],
    "Resource": "*"
  }]
}

And an access entry for the second, here read-only across the cluster (use AmazonEKSClusterAdminPolicy or AmazonEKSEditPolicy to make changes from Roam):

aws eks create-access-entry --cluster-name prod \
  --principal-arn arn:aws:iam::111122223333:user/roam

aws eks associate-access-policy --cluster-name prod \
  --principal-arn arn:aws:iam::111122223333:user/roam \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy \
  --access-scope type=cluster

Sign in with an IAM user

1. In Roam, tap Add Cluster and choose Amazon EKS, then IAM User.
2. Pick the Region and enter the Access Key ID and Secret Access Key.
3. Choose how Roam gets the session:
   • No MFA uses the keys directly.
   • Use MFA: enter the MFA device ARN and a current code. Roam gets a temporary session with it; when that session expires, add the cluster again with a fresh code.
   • Temp Session: paste a session token you already have (for example from aws sts get-session-token), with the temporary key pair that came with it.
4. Optionally enter a Role ARN to Assume — for example a cluster-admin role — and Roam assumes it on top of that session.
5. Tap Discover Clusters, choose the cluster, then Connect Cluster.

Sign in with AWS IAM Identity Center (SSO)

1. Tap Add Cluster, choose Amazon EKS, then AWS SSO.
2. Enter the Region, your AWS SSO Start URL (like https://my-company.awsapps.com/start), the AWS Account ID and the Role Name of your permission set.
3. Tap Generate Login Code, open the link Roam shows, enter the code and approve the sign-in in your browser.
4. Back in Roam, sign in and look up your clusters, choose one, and tap Connect Cluster.

The role behind the permission set needs the same two permissions as above: the EKS API calls and an access entry.

On the desktop app

The desktop app downloaded from GitHub or the Microsoft Store can also use your ~/.kube/config as it is: choose Use kubeconfig from this computer, and Roam runs aws eks get-token the way kubectl does. Versions that run in a store sandbox can't start other programs; there, Roam offers the EKS sign-in instead, filled in from your kubeconfig.

Troubleshooting

• "No EKS clusters found in this region": check the region, and that the identity can call eks:ListClusters there.
• Connected, but everything is Unauthorized or Forbidden: the identity can see the cluster but has no access entry (or aws-auth mapping), or its access policy doesn't cover what you opened.
• Worked yesterday, fails today with MFA: the temporary session expired. Add the cluster again with a new MFA code.
• Times out: the endpoint is private, or its public access is limited to certain IP ranges. Use an SSH bastion, or allow your network.

Your keys never leave the device: they are encrypted in the Keychain or Keystore and sent only to AWS and to your cluster. For a phone, a dedicated IAM user with read-only access, or SSO, is a good default.