Amazon EKS — Kubeconfig Setup
Kubeconfig Setup
After creating an EKS cluster, you need to configure kubectl to communicate with it. This is done through a kubeconfig file that tells kubectl where the cluster is and how to authenticate.
What is Kubeconfig?
The kubeconfig file (default: ~/.kube/config) contains:
kubeconfig Structure
┌────────────────────────────────────────────┐
│ clusters: WHERE to connect │
│ - API server endpoint │
│ - Certificate authority │
│ │
│ users: HOW to authenticate │
│ - AWS IAM (via aws eks get-token) │
│ │
│ contexts: WHICH cluster + user combo │
│ - Links a cluster to a user │
│ - You can have multiple contexts │
│ │
│ current-context: ACTIVE connection │
└────────────────────────────────────────────┘
Update Kubeconfig for EKS
If you used eksctl create cluster, kubeconfig was automatically updated. Otherwise:
$ aws eks update-kubeconfig \
--name demo \
--region us-east-1
Added new context arn:aws:eks:us-east-1:123456789012:cluster/demo to /Users/you/.kube/config
Verify the Connection
# Check current context
$ kubectl config current-context
arn:aws:eks:us-east-1:123456789012:cluster/demo
# Check cluster info
$ kubectl cluster-info
Kubernetes control plane is running at https://ABCDEF1234567890.gr7.us-east-1.eks.amazonaws.com
CoreDNS is running at https://ABCDEF1234567890.gr7.us-east-1.eks.amazonaws.com/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy
# List nodes
$ kubectl get nodes
NAME STATUS ROLES AGE VERSION
ip-192-168-75-112.ec2.internal Ready <none> 10m v1.29.0-eks-...
ip-192-168-98-43.ec2.internal Ready <none> 10m v1.29.0-eks-...
Multiple Clusters
You can have multiple EKS clusters in your kubeconfig:
# Add another cluster
$ aws eks update-kubeconfig --name staging --region us-east-1 --alias staging
# List all contexts
$ kubectl config get-contexts
CURRENT NAME CLUSTER AUTHINFO
* arn:aws:eks:us-east-1:123456789012:cluster/demo arn:aws:eks:us-east-1:123456789012:cluster/demo arn:aws:eks:...
staging arn:aws:eks:us-east-1:123456789012:cluster/staging arn:aws:eks:...
# Switch context
$ kubectl config use-context staging
Switched to context "staging".
# Switch back
$ kubectl config use-context arn:aws:eks:us-east-1:123456789012:cluster/demo
Using Aliases for Cluster Names
The default context names are long. Use --alias to set friendly names:
$ aws eks update-kubeconfig --name demo --region us-east-1 --alias demo
$ aws eks update-kubeconfig --name staging --region us-east-1 --alias staging
$ aws eks update-kubeconfig --name production --region us-east-1 --alias prod
# Now switching is easy
$ kubectl config use-context demo
$ kubectl config use-context prod
How EKS Authentication Works
kubectl ──▶ kubeconfig ──▶ aws eks get-token ──▶ EKS API Server
│
├── Reads AWS credentials
├── Calls STS GetCallerIdentity
└── Returns a bearer token
│
▼
EKS verifies token
Maps IAM → K8s identity
Checks K8s RBAC
Key insight: EKS uses IAM for authentication (who are you?) and Kubernetes RBAC for authorization (what can you do?).
Common Mistakes
| Mistake | Fix |
|---|---|
| Wrong kubeconfig context | kubectl config use-context <name> |
| Expired AWS credentials | Re-authenticate or refresh credentials |
| Wrong IAM user/role | EKS maps the IAM identity that created the cluster as admin |
| Corrupted kubeconfig | Delete ~/.kube/config and re-run aws eks update-kubeconfig |
Quick Reference
# Update kubeconfig
$ aws eks update-kubeconfig --name demo --region us-east-1 --alias demo
# Check context
$ kubectl config current-context
$ kubectl config get-contexts
# Switch context
$ kubectl config use-context demo
# Test connection
$ kubectl get nodes
$ kubectl cluster-info
What’s Next?
Now let’s do a thorough verification: Verify Cluster.
