Kubeconfig and EKS Authentication: How aws eks get-token Works

The kubeconfig file structure

Kubeconfig is a YAML file at ~/.kube/config (or specified via KUBECONFIG env var) that tells kubectl how to connect to and authenticate with Kubernetes clusters. A single kubeconfig can contain multiple clusters, users, and contexts.

apiVersion: v1
kind: Config
current-context: production

clusters:
- name: production
  cluster:
    server: https://ABCDEF1234567890.gr7.us-east-1.eks.amazonaws.com
    certificate-authority-data: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0t...

users:
- name: arn:aws:eks:us-east-1:123456789012:cluster/production
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: aws
      args:
        - eks
        - get-token
        - --cluster-name
        - production
        - --region
        - us-east-1

contexts:
- name: production
  context:
    cluster: production
    user: arn:aws:eks:us-east-1:123456789012:cluster/production
    namespace: default

The exec credential plugin is where EKS auth differs from standard Kubernetes. Instead of a static token or client certificate, kubectl runs an external command (aws eks get-token) to get a fresh token on each request.

Generating kubeconfig for EKS

# Add cluster to kubeconfig (creates or updates ~/.kube/config)
aws eks update-kubeconfig \
  --name production \
  --region us-east-1

# With a specific IAM role (cross-account or assuming a different role for EKS access)
aws eks update-kubeconfig \
  --name production \
  --region us-east-1 \
  --role-arn arn:aws:iam::123456789012:role/EKSAdminRole

# Verify the connection
kubectl auth whoami    # Kubernetes 1.28+
kubectl get nodes

When --role-arn is specified, the kubeconfig exec section adds --role-arn to the aws eks get-token command. kubectl will assume that role via STS before generating the token.

Working with multiple clusters

Keep multiple clusters in a single kubeconfig or use separate files with KUBECONFIG:

# Switch context (cluster + user + namespace combination)
kubectl config use-context staging

# List all available contexts
kubectl config get-contexts

# Run a single command against a different context
kubectl --context=staging get pods

# Merge multiple kubeconfig files
KUBECONFIG=~/.kube/config:~/.kube/staging-config kubectl config view --merge --flatten > ~/.kube/merged-config

kubectx and kubens are commonly used wrappers for faster context and namespace switching:

# kubectx: switch cluster context
kubectx production
kubectx -   # switch back to previous context

# kubens: switch default namespace
kubens kube-system

# Associate OIDC provider with cluster
eksctl utils associate-iam-oidc-provider \
  --cluster production \
  --approve

# Create IAM role with trust policy for the service account
eksctl create iamserviceaccount \
  --name s3-reader \
  --namespace default \
  --cluster production \
  --attach-policy-arn arn:aws:iam::aws:policy/AmazonS3ReadOnlyAccess \
  --approve

data "aws_iam_openid_connect_provider" "eks" {
  url = aws_eks_cluster.main.identity[0].oidc[0].issuer
}

resource "aws_iam_role" "s3_reader" {
  name = "eks-s3-reader"
  assume_role_policy = jsonencode({
    Statement = [{
      Effect = "Allow"
      Principal = { Federated = data.aws_iam_openid_connect_provider.eks.arn }
      Action = "sts:AssumeRoleWithWebIdentity"
      Condition = {
        StringEquals = {
          "${data.aws_iam_openid_connect_provider.eks.url}:sub" = "system:serviceaccount:default:s3-reader"
        }
      }
    }]
  })
}

Debugging authentication failures

Common EKS authentication errors and their causes:

error: You must be logged in to the server (Unauthorized)

• Your IAM identity is not in aws-auth ConfigMap (or EKS access entries)
• You're assuming the wrong IAM role (check with aws sts get-caller-identity)
• The aws-auth entry has a typo in the role ARN

error: exec plugin: invalid apiVersion "client.authentication.k8s.io/v1alpha1"

• Outdated AWS CLI or aws-iam-authenticator. Update to v1beta1 and a recent AWS CLI version.

Unable to connect to the server: dial tcp: lookup ... no such host

• Private endpoint-only cluster accessed from outside VPC
• Wrong cluster name in kubeconfig

# Diagnose: what IAM identity is kubectl using?
aws sts get-caller-identity

# Diagnose: test a token directly
TOKEN=$(aws eks get-token --cluster-name production --region us-east-1 --output json | jq -r '.status.token')
curl -k -H "Authorization: Bearer $TOKEN" https://YOUR_EKS_ENDPOINT/api/v1/nodes

# View current aws-auth ConfigMap
kubectl get configmap aws-auth -n kube-system -o yaml

# View EKS access entries (new API)
aws eks list-access-entries --cluster-name production