Amazon EKS — Cluster Access Issues

“You must be logged in to the server” is the most common EKS error. It means your IAM identity can’t authenticate or authorize against the Kubernetes API server.

---

Error: “You must be logged in to the server (Unauthorized)”

Diagnosis

# Who am I?
aws sts get-caller-identity

# Output:
# {
#   "UserId": "AIDAEXAMPLE",
#   "Account": "123456789012",
#   "Arn": "arn:aws:iam::123456789012:user/john"
# }

Check if this identity has access:

# 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

Fix — Add Access Entry

aws eks create-access-entry \
  --cluster-name my-cluster \
  --principal-arn arn:aws:iam::123456789012:user/john \
  --type STANDARD

aws eks associate-access-policy \
  --cluster-name my-cluster \
  --principal-arn arn:aws:iam::123456789012:user/john \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
  --access-scope type=cluster

Fix — aws-auth ConfigMap (Legacy)

eksctl create iamidentitymapping \
  --cluster my-cluster \
  --arn arn:aws:iam::123456789012:user/john \
  --group system:masters \
  --username john

---

Error: “Unable to connect to the server”

Possible Causes

Cause	Diagnosis	Fix
Wrong kubeconfig	cat ~/.kube/config	aws eks update-kubeconfig --name my-cluster
Wrong region	Check server URL region	Add --region us-east-1
VPN/network issue	curl -v <api-server-url>	Check VPN or network ACLs
Private endpoint only	aws eks describe-cluster --name my-cluster --query 'cluster.resourcesVpcConfig'	Access from within VPC or use bastion
API server is down	aws eks describe-cluster --name my-cluster --query 'cluster.status'	Check for ongoing EKS incident

Fix — Regenerate kubeconfig

# Remove old config
rm ~/.kube/config

# Generate fresh config
aws eks update-kubeconfig --name my-cluster --region us-east-1

# Verify
kubectl cluster-info

---

Error: “error: exec plugin is configured to use API version client.authentication.k8s.io/v1alpha1”

This happens with old AWS CLI or old kubeconfig:

# Update AWS CLI
pip install --upgrade awscli
# or
brew upgrade awscli

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

---

Assuming the Wrong IAM Role

If you’re using SSO or IAM roles:

# Verify current identity
aws sts get-caller-identity

# If wrong, set the profile
export AWS_PROFILE=my-eks-profile

# Or assume the correct role
aws sts assume-role \
  --role-arn arn:aws:iam::123456789012:role/EKSAdmin \
  --role-session-name debug-session

---

Private Endpoint Access

If the cluster only has private API endpoint:

# Check endpoint configuration
aws eks describe-cluster --name my-cluster \
  --query 'cluster.resourcesVpcConfig.{PublicAccess:endpointPublicAccess,PrivateAccess:endpointPrivateAccess}'

Public	Private	Access From
true	false	Internet only
false	true	VPC only (need bastion or VPN)
true	true	Both (recommended for transition)

To access from outside VPC:

1. Bastion host in the VPC
2. SSM Session Manager to an EC2 instance in the VPC
3. AWS Client VPN or Site-to-Site VPN
4. Enable public access with CIDR restrictions:

aws eks update-cluster-config --name my-cluster \
  --resources-vpc-config endpointPublicAccess=true,publicAccessCidrs=["203.0.113.0/24"]

---

EKS Access Entry Debugging

# List all access entries
aws eks list-access-entries --cluster-name my-cluster

# Describe specific entry
aws eks describe-access-entry \
  --cluster-name my-cluster \
  --principal-arn arn:aws:iam::123456789012:role/MyRole

# List associated policies
aws eks list-associated-access-policies \
  --cluster-name my-cluster \
  --principal-arn arn:aws:iam::123456789012:role/MyRole

---

Common Mistakes

1. Cluster creator has implicit access — but it’s not in aws-auth or access entries; if you lose access to the creator identity, you lose cluster access
2. SSO role ARN mismatch — SSO roles have different ARNs than what aws sts get-caller-identity shows; use the role ARN from the SSORole path
3. Stale kubeconfig — always regenerate after cluster changes
4. Wrong AWS region — the kubeconfig must match the cluster’s region

---