Accessing an Amazon EKS cluster involves two separate layers of authorization. First, the AWS identity used by the operator needs permission to describe and connect to the EKS cluster. Then, that IAM user or role must be recognized and authorized inside Kubernetes itself.
Compared with Alibaba Cloud ACK, the process can feel more involved, but the separation is deliberate: AWS controls access to the managed cluster endpoint, while Kubernetes controls what an authenticated identity is allowed to do after connecting.
Set up the AWS CLI
Install the AWS CLI on a trusted machine. Ubuntu repositories often provide an older AWS CLI v1 package, so AWS CLI v2 is generally preferable in production. The official installation instructions are included in the original command comment below.
# Ubuntu（推荐安装 AWS CLI v2：https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html ）
# apt 源中的 awscli 多为较旧的 v1，生产环境建议用官方安装包安装 CLI v2
$ apt install awscli
# Centos
$ yum install awscli
# Alpine
$ apk add aws-cli
After installation, configure the credentials, default region, and output format. JSON is a practical choice for command-line output.
$ aws configure
The configured identity can be checked with AWS Security Token Service:
$ aws sts get-caller-identity
{
"UserId": "AIDA22TMKIAK23NRY7I2U",
"Account": "74433**59173",
"Arn": "arn:aws:iam::74433**59173:user/[email protected]"
}
Keep the returned ARN. The IAM user or role represented by this ARN will need to be authorized in the cluster later.
Grant permission to describe the EKS cluster
The AWS identity must first be allowed to access the EKS cluster through IAM. Without permission to call eks:DescribeCluster, the kubeconfig command cannot obtain the cluster connection details. A typical failure looks like this:
An error occurred (AccessDeniedException) when calling the DescribeCluster operation: User: arn:aws:sts::74433**59173:assumed-role/dev_ec2_role/i-05a47d36f6ce1b8a0 is not authorized to perform: eks:DescribeCluster on resource: arn:aws:eks:us-east-1:74433**59173:cluster/my-eks-name
An administrator must grant the relevant IAM user or role permission to describe the target cluster. This AWS-level permission is necessary, but it does not by itself grant permission to list pods or perform other Kubernetes operations.
Generate the kubeconfig entry
Once the IAM identity can describe the cluster, use the AWS CLI to create or update the local kubeconfig file:
$ aws eks update-kubeconfig --region us-east-1 --name my-eks-name
Updated context arn:aws:eks:us-east-1:74433**59173:cluster/my-eks-name in /home/ubuntu/.kube/config
The command adds an EKS context to the kubeconfig file, normally under the current user's .kube directory. It does not automatically make the IAM identity a Kubernetes administrator.
Check the client and server versions
Run a basic version check before troubleshooting permissions:
$ kubectl version
If the Kubernetes client and EKS server versions are incompatible, the exec authentication plugin may fail with an error such as:
error: exec plugin: invalid apiVersion “client.authentication.k8s.io/v1alpha1
A version mismatch is not the only possible cause. If the versions appear suitable, the local machine, installed AWS CLI, authentication plugin, or other environment details may still be responsible. Testing from another machine can help isolate that kind of problem.
Distinguish authentication from Kubernetes authorization
When the client can reach the cluster but the IAM identity has not been recognized inside Kubernetes, commands such as the following return credential-related errors:
$ kubectl get pods
E1213 06:53:38.816495 3836 memcache.go:265] couldn't get current server API group list: the server has asked for the client to provide credentials
E1213 06:53:43.183670 3836 memcache.go:265] couldn't get current server API group list: the server has asked for the client to provide credentials
E1213 06:53:47.280917 3836 memcache.go:265] couldn't get current server API group list: the server has asked for the client to provide credentials
E1213 06:53:51.386354 3836 memcache.go:265] couldn't get current server API group list: the server has asked for the client to provide credentials
E1213 06:53:55.207002 3836 memcache.go:265] couldn't get current server API group list: the server has asked for the client to provide credentials
error: You must be logged in to the server (the server has asked the client to provide credentials)
For more diagnostic detail, run:
$ kubectl cluster-info dump
An unauthorized response may include an HTTP 401 status and confirm that the server expects credentials from a client that has not yet been accepted:
E1213 06:57:34.495458 3960 memcache.go:265] couldn't get current server API group list: the server has asked the client to provide credentials
I1213 06:57:34.495470 3960 cached_discovery.go:120] skipped caching discovery info due to the server has asked the client to provide credentials
To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.
I1213 06:57:34.495648 3960 helpers.go:246] server response object: [{
"metadata": {},
"status": "Failure",
"message": "the server has asked the client to provide credentials",
"reason": "Unauthorized",
"details": {
"causes": [
{
"reason": "UnexpectedServerResponse",
"message": "unknown"
}
]
},
"code": 401
}]
error: You must be logged in to the server (the server has asked the client to provide credentials)
At this point, the kubeconfig may be present and the AWS identity may be valid, but the identity still needs a Kubernetes-side mapping and authorization.
Map the IAM identity into the cluster
Ask a cluster administrator to edit the aws-auth ConfigMap:
$ kubectl edit configmap aws-auth -n kube-system
The administrator can add the IAM user or role to the relevant section. The following example contains both a node role and an additional role and user mapping; replace the example values with the identities that should be granted access.
apiVersion: v1
data:
mapRoles: |
- groups:
- system:bootstrappers
- system:nodes
rolearn: arn:aws:iam::81420**88517:role/eksctl-custom-cluster-nodegroup-ng-NodeInstanceRole-ieXb6Zk7Og64
username: system:node:{{EC2PrivateDNSName}}
- rolearn: arn:aws:iam::81420**88517:role/test-role
username: test-role
groups:
- system:masters
mapUsers: |
- userarn: arn:aws:iam::74433**59173:user/[email protected]
username: [email protected]
groups:
- system:masters
kind: ConfigMap
metadata:
name: aws-auth
namespace: kube-system
The system:masters group provides broad administrative privileges. It is useful for testing, but production clusters should generally grant narrower permissions instead of placing ordinary users or roles in this group.
Newer EKS environments increasingly use EKS Access Entries to manage IAM principals that can access a cluster. The aws-auth ConfigMap remains common on existing clusters, so the correct method depends on how the cluster is configured and managed.
After the administrator makes the change, an identity mapping can be inspected with eksctl:
$ eksctl get iamidentitymapping --cluster custom-cluster-name --region us-east-1
Verify access with kubectl
Once both AWS-level access and Kubernetes-level authorization are in place, check the client and server versions again:
$ kubectl version
Client Version: v1.28.4
Kustomize Version: v5.0.4-0.20230601165947-6ce0bf390ce3
Server Version: v1.28.4-eks-8cb36c9
A simple pod creation test can confirm that the mapped identity has the required Kubernetes permissions:
$ kubectl run test-pod --image=nginx --restart=Never
pod/test-pod created
$ kubectl get pods
NAME READY STATUS RESTARTS AGE
test-pod 1/1 Running 0 15s
If kubeconfig generation succeeds but Kubernetes commands still return Unauthorized, check the IAM permission for eks:DescribeCluster, confirm that the kubeconfig is using the intended AWS identity, and verify the corresponding user or role mapping and group permissions inside the cluster.