aws eks update-kubeconfig: Usage & Common CI Errors

Point kubectl at an EKS cluster by generating a kubeconfig entry.

aws eks update-kubeconfig adds (or updates) a context in your kubeconfig so kubectl can talk to an EKS cluster, using the AWS CLI as the token provider for authentication.

What it does

The command writes a cluster, user, and context into ~/.kube/config (or KUBECONFIG). The user entry invokes aws eks get-token to mint a short-lived token on each kubectl call, so authentication tracks your current AWS identity. You must pass --name (cluster) and the correct --region.

Common usage

# Configure kubectl for an EKS cluster
aws eks update-kubeconfig --name my-cluster --region us-east-1

# Write to a specific file and name the context
aws eks update-kubeconfig --name my-cluster --region us-east-1 \
  --kubeconfig ./kubeconfig --alias prod

# Verify
kubectl get nodes

Common error in CI: "couldn't get current server API group list" / Unauthorized

kubectl fails after update-kubeconfig with "error: You must be logged in to the server (Unauthorized)" or "the server has asked for the client to provide credentials". The kubeconfig is fine but the CI IAM principal is not mapped to a Kubernetes group. Fix: grant the CI role cluster access - add an EKS access entry (aws eks create-access-entry + associate-access-policy) or, on older clusters, a row in the aws-auth ConfigMap mapping the role ARN to a group. Also confirm the region matches the cluster’s.

Key options

Related guides