kubeconfig & update-kubeconfig

Point kubectl at your cluster by generating a kubeconfig entry with aws eks update-kubeconfig.

Syntaxaws eks update-kubeconfig --name <cluster> --region <region>

kubectl reads a kubeconfig file (default ~/.kube/config) to know which cluster to talk to and how to authenticate. EKS generates this entry for you.

How EKS authentication works

The kubeconfig entry doesn't store a password. Instead it calls the AWS CLI to fetch a short-lived token from your AWS credentials, which EKS validates. This is why you must be logged in to AWS for kubectl to work.

Switching clusters

Each cluster is a context. Use kubectl config commands to list and switch between them.

Example

Example · bash
# Add or refresh the kubeconfig entry for a cluster
aws eks update-kubeconfig --name demo --region us-east-1

# See and switch contexts
kubectl config get-contexts
kubectl config use-context arn:aws:eks:us-east-1:111122223333:cluster/demo

# Confirm connectivity
kubectl get svc

When to use it

  • A developer runs aws eks update-kubeconfig after a new cluster is created so their local kubectl context is updated automatically.
  • A CI/CD runner calls update-kubeconfig with a specific IAM role to assume, enabling least-privilege deployments without storing long-term credentials.
  • A platform team generates cluster-specific kubeconfig files and distributes them to developers via an internal secrets manager.

More examples

Update kubeconfig for a cluster

Adds or updates the EKS cluster entry in ~/.kube/config and sets it as the current context for kubectl.

Example · bash
aws eks update-kubeconfig \
  --name my-cluster \
  --region us-east-1
kubectl config current-context
kubectl get nodes

Use a named context alias

Creates a human-friendly alias for the cluster context so you can switch between clusters with a short name.

Example · bash
aws eks update-kubeconfig \
  --name prod-cluster \
  --region us-east-1 \
  --alias prod
kubectl config use-context prod
kubectl get pods -A

Update kubeconfig with role assumption

Embeds an IAM role ARN into the kubeconfig so kubectl automatically assumes that role when authenticating to the cluster.

Example · bash
aws eks update-kubeconfig \
  --name prod \
  --region us-east-1 \
  --role-arn arn:aws:iam::123456789012:role/EKSDeployRole

Related

eks iam authenticationeks create cluster

Discussion

  • Be the first to comment on this lesson.