Amazon EKS — kubeconfig and Access

After creating an EKS cluster, you need to configure kubectl to communicate with it. EKS uses AWS IAM for authentication, which is different from most Kubernetes setups.

---

Update kubeconfig

The simplest way to configure kubectl for EKS:

aws eks update-kubeconfig \
  --region us-east-1 \
  --name my-cluster

This adds a new context to your ~/.kube/config file with the EKS cluster details.

Specify a Custom kubeconfig Path

aws eks update-kubeconfig \
  --region us-east-1 \
  --name my-cluster \
  --kubeconfig ~/.kube/eks-config

Use a Specific IAM Role

aws eks update-kubeconfig \
  --region us-east-1 \
  --name my-cluster \
  --role-arn arn:aws:iam::123456789012:role/EKSAdminRole

---

kubeconfig Structure for EKS

After running the update-kubeconfig command, your kubeconfig will look like this:

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data: <base64-encoded-ca-cert>
    server: https://ABCDEF1234567890.gr7.us-east-1.eks.amazonaws.com
  name: arn:aws:eks:us-east-1:123456789012:cluster/my-cluster
contexts:
- context:
    cluster: arn:aws:eks:us-east-1:123456789012:cluster/my-cluster
    user: arn:aws:eks:us-east-1:123456789012:cluster/my-cluster
  name: arn:aws:eks:us-east-1:123456789012:cluster/my-cluster
current-context: arn:aws:eks:us-east-1:123456789012:cluster/my-cluster
users:
- name: arn:aws:eks:us-east-1:123456789012:cluster/my-cluster
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      args:
      - --region
      - us-east-1
      - eks
      - get-token
      - --cluster-name
      - my-cluster
      command: aws

Key insight: EKS uses the exec plugin to call aws eks get-token. This generates a short-lived token via STS — no static credentials stored in kubeconfig.

---

Managing Multiple Clusters

List Contexts

kubectl config get-contexts

Switch Context

kubectl config use-context arn:aws:eks:us-east-1:123456789012:cluster/my-cluster

Set Friendly Aliases

# Rename a context for easier use
kubectl config rename-context \
  arn:aws:eks:us-east-1:123456789012:cluster/my-cluster \
  eks-prod

Now you can switch with:

kubectl config use-context eks-prod

Use kubectx (Optional)

# Install
brew install kubectx

# Switch cluster
kubectx eks-prod

# Switch namespace
kubens kube-system

---

Verify Access

# Check cluster info
kubectl cluster-info

# List nodes
kubectl get nodes

# Check your identity
kubectl auth whoami   # K8s 1.27+

# Check what you can do
kubectl auth can-i '*' '*'

Expected output for cluster creator:

Kubernetes control plane is running at https://ABCDEF.gr7.us-east-1.eks.amazonaws.com
CoreDNS is running at https://ABCDEF.gr7.us-east-1.eks.amazonaws.com/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

---

How EKS Authentication Works

1. You run kubectl get pods
2. kubectl calls aws eks get-token --cluster-name my-cluster
3. The AWS CLI calls STS to generate a pre-signed URL token
4. kubectl sends this token to the EKS API server
5. The API server validates the token against the OIDC identity provider or aws-auth ConfigMap / access entries
6. If valid, the request proceeds with the mapped Kubernetes RBAC permissions

kubectl → aws eks get-token → STS → token
  ↓
EKS API Server → validates token → maps to K8s user/group → RBAC check

---

Troubleshooting Access Issues

“You must be logged in to the server”

# Check your AWS identity
aws sts get-caller-identity

# Make sure the region matches
aws eks update-kubeconfig --region us-east-1 --name my-cluster

# Ensure the IAM user/role has EKS access

“Unauthorized” or “Forbidden”

# The IAM identity might not be mapped in aws-auth or access entries
# Check access entries
aws eks list-access-entries --cluster-name my-cluster

# Check aws-auth ConfigMap (legacy)
kubectl get configmap aws-auth -n kube-system -o yaml

Token Issues

# Test token generation directly
aws eks get-token --cluster-name my-cluster --region us-east-1

# Check AWS CLI version (v2 required for latest features)
aws --version

Wrong Cluster Context

# Verify current context
kubectl config current-context

# Switch to correct context
kubectl config use-context <correct-context>

---

What’s Next?

Let’s look at EKS add-ons — the core components that AWS manages for you.

Next: EKS Add-ons →