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 nodesCommon 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
| Option | Purpose |
|---|---|
| --name | Required EKS cluster name |
| --region | Cluster region |
| --kubeconfig | Target kubeconfig file |
| --alias | Name for the kubeconfig context |
| --role-arn | Assume a role for cluster auth |
Using this in CI
Cloud CLIs behave differently on a runner than on your laptop. They assume no interactive terminal, no cached credentials, and no browser for device-code flows, so the same command that works locally can hang or fail on a runner.
- Authenticate with a short-lived OIDC token rather than a long-lived static key. GitHub Actions can exchange
id-token: writefor cloud credentials with no stored secret. - Always pass the non-interactive flag. Most cloud CLIs will otherwise prompt and hang until the job times out.
- Pin the CLI version. Cloud CLIs change output formats between minor releases, and any script parsing that output will break silently.
- Set the output format explicitly (
--output json) rather than relying on the default, which can differ by version and configuration profile.