Fixing the EKS 'Unauthorized' Error: Kubeconfig and IAM Troubleshooting

The Error Message

You are mid-workflow, ready to check your pods or deploy a service, when your terminal throws a curveball. You run a standard kubectl command and get hit with this:

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

Why is this happening?

The 'Unauthorized' error is notoriously stingy with details. In the world of Amazon EKS, it rarely means you lack permissions. Instead, it usually means the cluster doesn't recognize who you are. This typically happens for four reasons:

• Expired AWS Credentials: Your SSO session timed out or your temporary IAM tokens expired. SSO sessions often default to an 8 or 12-hour limit.
• Profile Mismatch: Your AWS CLI is pointed at your 'staging' profile, but your kubeconfig is hunting for 'production'.
• IAM Role Mapping: Your IAM identity hasn't been added to the cluster's internal guest list. This is handled by the aws-auth ConfigMap or EKS Access Entries.
• Outdated Kubeconfig: Your ~/.kube/config is trying to use an obsolete authentication API that EKS no longer supports.

Step 1: Verify your AWS Identity

The first step isn't actually a Kubernetes command. You need to confirm exactly who you are in the eyes of AWS. Run this command:

aws sts get-caller-identity

Look closely at the Arn in the output. Does it match the IAM role or user that has cluster access? If you use AWS SSO, your session might have silently expired. Run aws sso login to be sure.

Managing multiple environments? Ensure you have exported the correct profile for your current terminal session:

export AWS_PROFILE=my-eks-profile
aws sts get-caller-identity

Step 2: Refresh your Kubeconfig

Kubeconfig files can become stale. This happens often if the cluster was recently updated or if you've modified your local AWS config. Wiping the slate clean and regenerating the file is usually the quickest fix.

Run the following command, replacing the region and cluster name:

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

If you rely on a specific profile, append it to the command to ensure the config uses the right credentials:

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

This command updates your ~/.kube/config. It sets up the aws eks get-token command to handle your authentication automatically.

Step 3: Check IAM Mapping in EKS

Even with valid AWS credentials, the cluster might still reject you. By default, EKS only grants access to the specific IAM entity that originally created the cluster.

Method A: EKS Access Entries (Recommended for EKS 1.23+)

Modern clusters use Access Entries. Check the AWS Console under EKS > Clusters > [Your Cluster] > Access. Verify that your IAM Role or User is listed. It should have a policy like AmazonEKSClusterAdminPolicy attached.

Method B: The aws-auth ConfigMap

Older clusters rely on the aws-auth ConfigMap. Since you are currently 'Unauthorized', you cannot check this yourself. You will need the cluster creator or an admin to run this:

kubectl get configmap aws-auth -n kube-system -o yaml

The output should include your role ARN in the mapRoles section:

mapRoles: |
  - groups:
    - system:masters
    rolearn: arn:aws:iam::123456789012:role/my-admin-role
    username: my-admin-role

If your role is missing from this list, you will remain unauthorized regardless of your AWS permissions.

Step 4: Debugging the Exec Plugin

Open your ~/.kube/config and find the users: section. It should look like this:

users:
- name: my-cluster-user
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1beta1
      command: aws
      args: ["eks", "get-token", "--cluster-name", "my-cluster"]

If you see aws-iam-authenticator as the command, switch to aws. The AWS CLI v2 has native EKS token support. It is significantly faster and more stable than the older authenticator tool.

Verification

Once you have refreshed your credentials and config, test your connection with a simple authorization check:

kubectl auth can-i '*' '*'

If it returns yes, you are fully authenticated. If it returns no, the 'Unauthorized' error is gone, but your IAM role lacks the necessary RBAC permissions inside the cluster.

Finally, list your pods to confirm everything is working:

kubectl get pods -A

Quick Tips

• Clock Skew: AWS requests fail if your system clock is off by more than 300 seconds (5 minutes). Sync your clock via NTP.
• Environment Overrides: Variables like AWS_ACCESS_KEY_ID override your ~/.aws/credentials file. Unset them if you suspect a conflict.
• Version Parity: Ensure your AWS CLI is version 2.10 or higher. Your kubectl version should be within one minor version of the cluster (e.g., use 1.29 for a 1.30 cluster).