Sev1: locked out of an EKS cluster — broken aws-auth ConfigMap or missing access entries

#Symptoms

• error: You must be logged in to the server (Unauthorized) for everyone, often right after someone edited aws-auth.
• Nodes go NotReady and stop joining (node role mapping removed from aws-auth).
• The person or role that created the cluster no longer exists.

#1. Check the cluster's authentication mode

aws eks describe-cluster --name eks-prod --query "cluster.accessConfig" --output json

#2. Enable access entries (if not already)

This is an EKS API call, so you only need IAM permissions — not cluster access:

aws eks update-cluster-config --name eks-prod --access-config authenticationMode=API_AND_CONFIG_MAP
aws eks describe-update --name eks-prod --update-id <id>

Note

You can move from CONFIG_MAP to API_AND_CONFIG_MAP to API, but not back.

#3. Grant yourself cluster admin

aws eks create-access-entry --cluster-name eks-prod \
  --principal-arn arn:aws:iam::111122223333:role/PlatformAdmin

aws eks associate-access-policy --cluster-name eks-prod \
  --principal-arn arn:aws:iam::111122223333:role/PlatformAdmin \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
  --access-scope type=cluster

aws eks update-kubeconfig --name eks-prod --role-arn arn:aws:iam::111122223333:role/PlatformAdmin
kubectl get nodes

#4. Fix nodes

If nodes stopped joining because their role mapping was removed, add an access entry of type EC2_LINUX for the node role:

aws eks create-access-entry --cluster-name eks-prod \
  --principal-arn arn:aws:iam::111122223333:role/eks-node-role --type EC2_LINUX

Managed node groups normally get this automatically when the cluster uses access entries.

#5. Repair aws-auth (if you keep it)

kubectl -n kube-system get configmap aws-auth -o yaml > aws-auth-broken.yaml
kubectl -n kube-system edit configmap aws-auth

Check YAML indentation, rolearn (role ARN without a path is required — use arn:aws:iam::<acct>:role/name even if the role has a path), and that system:bootstrappers and system:nodes groups are mapped for the node role. A single bad indent can invalidate the whole map.

#6. Last resort

If you have no IAM principal with eks:CreateAccessEntry and no cluster access at all, use the account's administrative role (or root via your break-glass process) to grant an access entry. Avoid support escalation delays by never getting here — see below.

#Prevent it next time

• Move to API mode and manage access entries in IaC; stop editing aws-auth by hand.
• At least two admin access entries (a platform role and a break-glass role).
• Restrict eks:CreateAccessEntry / eks:AssociateAccessPolicy to platform admins.