Complete a 3 Question Survey and Earn a re:Post Badge

Help improve AWS Support Official channel in re:Post and share your experience - complete a quick three-question survey to earn a re:Post badge!

How do I provide cluster access to other IAM users and roles after I create a cluster in Amazon EKS?

7 minute read

When I use kubectl commands to access an Amazon Elastic Kubernetes Service (Amazon EKS) cluster, I get the "error: You must be logged in to the server (Unauthorized)" error message.

Short description

If the AWS Identity and Access Management (IAM) user or role creates an Amazon EKS cluster that's different from the cluster that aws-iam-authenticator uses, then you get the Unauthorized error message. To resolve this issue, configure your Amazon EKS cluster's role-based access control (RBAC) to authorize the IAM entity. For more information about RBAC, see Using RBAC authorization on the Kubernetes website.

Only the creator of the Amazon EKS cluster has system:masters permissions to configure the cluster. There are two ways to extend system:masters permissions to other IAM users and roles:

Assume the cluster creator credentials. Then, add the IAM role in the mapRoles section of the aws-auth ConfigMap.
Use EKS access entries.

Important: It's a best practice not to add cluster_creator to the ConfigMap. If you incorrectly configure your ConfigMap, then all IAM users and roles, including cluster_creator, might permanently lose access to the Amazon EKS cluster. By default, the cluster_creator has admin access to the cluster that it created, so you don't need to add the cluster_creater to the aws-auth ConfigMap.

Note: In the following resolution, cluster_creator is the IAM entity that creates the cluster in Amazon EKS. The user who you're granting access to is designated_user.

Resolution

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Identify the IAM user or role for the cluster creator

Identify the IAM entity for the cluster creator that has primary access to configure your Amazon EKS cluster. To identify the cluster creator, search for the CreateCluster API call in AWS CloudTrail, and then check the userIdentity section of the API call.

Then, Identify the IAM entity that you're granting authorization to after you create the cluster.

Use aws-auth ConfigMap to grant cluster access when the cluster_creator is an IAM user

Complete the following steps:

Install kubectl on your local host machine. Or, if you have a dedicated Amazon Elastic Compute Cloud (Amazon EC2) instance with a kubectl package installed, use SSH to connect to the instance.
On the host machine where kubectl is installed, configure the AWS CLI with the designated_user credentials:
```
aws configure
```

Run the get-caller-identity AWS CLI command:

aws sts get-caller-identity

The output returns the IAM user details for the designated_user:

{  
    "UserId": "#####################",  
    "Account": "############",  
    "Arn": "arn:aws:iam::############:user/designated_user"  
}

List the pods that are running in the cluster of the default namespace:
```
kubectl get pods --namespace default
```
The output shows the Unauthorized error message because the designated_user doesn't have authorization to access the Amazon EKS cluster.
Configure the AWS access key ID and the AWS secret access key of the cluster_creator.
If you used the Amazon EKS console to create the cluster, then on your local host machine, configure the cluster_creator IAM user or role in the AWS CLI:
```
aws configure
```
If you used eksctl to create the cluster, then use the specified AWS CLI profile credentials to configure the AWS CLI to run kubectl commands.
Verify that the cluster_creator has access to the cluster:
```
kubectl get pods
```
You don't receive the Unauthorized error message, and the output lists all the pods that are running in the default namespace. If the output doesn't show any resources, then no pods are running in the default namespace.
To give the designated_user access to the cluster, add the mapUsers section to your aws-auth.yaml file. For more information, see Add IAM principles to your Amazon EKS cluster.
Add the designated_user to the mapUsers section of the aws-auth.yaml file, and then save the file.

Apply the new ConfigMap to the RBAC configuration of the cluster:

kubectl apply -f aws-auth.yaml

Change the AWS CLI configuration again to use the credentials of the designated_user:
```
aws configure
```
Verify that the designated_user has access to the cluster:
```
kubectl get pods
```
You don't receive the Unauthorized error message, and the output lists all the pods that are running in the default namespace. If the output doesn't show any resources, then no pods are running in the default namespace.

Use aws-auth ConfigMap to grant cluster access when the cluster_creator is an IAM role

If an IAM role created the cluster instead of an IAM user, then you can't use credentials. Instead, you must assume the IAM role that created the cluster to provide access to the designated_user.

Complete the following steps:

Run the get-caller-identity AWS CLI command to get the IAM user details of the assume_role_user:
```
aws sts get-caller-identity
```
Confirm that the assume_role_user has access to the cluster:
```
kubectl get pods
```
The output shows the Unauthorized error message because the designated_user doesn't have authorization to access the Amazon EKS cluster.

Allow the assume_role_user to assume the role of the cluster_creator:

aws sts assume-role --role-arn arn:aws:iam:11122223333:role/cluster_creator --role-session-name test

The output shows the temporary IAM credentials for the assume_role_user.

Use the temporary IAM credentials to set the AWS_ACCESS_KEY_ID, AWS_SESSION_TOKEN, and AWS_SECRET_ACCESS_KEY environment variables:

export AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE  
export AWS_SESSION_TOKEN=EXAMPLETOKEN  
export AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

The AWS CLI ranks the credentials that are set in the environment variables and uses them to make calls to AWS services.

Verify that the AWS CLI is using the assumed role for the cluster_creator:

aws sts get-caller-identity

To give the designated_user access to the cluster, add the mapUsers section to your aws-auth.yaml file.
Add the designated_user to the mapUsers section of the aws-auth.yaml file, and then save the file.

Apply the new configuration to the RBAC configuration of the Amazon EKS cluster:

kubectl apply -f aws-auth.yaml

Remove the following environment variables:

unset AWS_ACCESS_KEY_ID  
unset AWS_SESSION_TOKEN  
unset AWS_SECRET_ACCESS_KEY

Run the get-caller-identity AWS CLI command to get the IAM user details of the designated_user:
```
aws sts get-caller-identity
```
Confirm that the designated_user has access to the cluster:
```
kubectl get pods
```
You don't receive the Unauthorized error message, and the output lists all the pods that are running in the default namespace. If the output doesn't show any resources, then no pods are running in the default namespace.

Note: If you use eksctl, then see Manage IAM users and roles on the eksctl website for more information.

Use EKS access entries to grant cluster access to IAM users and roles

Amazon EKS supports three modes of authentication for access entries:

CONFIG_MAP to use only aws-auth ConfigMap.
API_AND_CONFIG_MAP to use both EKS access entry APIs and aws-auth ConfigMap. This mode prioritizes authentication through EKS access entries and is useful when you need to migrate existing aws-auth permissions to EKS access entries.
API to use only EKS access entry APIs.

For more information, see Grant IAM users and roles access to Kubernetes APIs.

To configure to your cluster with access entries, set the cluster authentication mode to EKS API or EKS API and ConfigMap.

To check the cluster's current authentication mode, complete the following steps:

Open the Amazon EKS console.
Choose the Access tab.
Under Access configuration, check the Authentication mode label.

Or, run the describe-cluster command:

aws eks describe-cluster --name example-cluster --query 'cluster.accessConfig.authenticationMode' --region exampleRegion

If the cluster's authentication mode is EKS API or EKS API and ConfigMap, then you can configure the cluster to use access entries. If not, then see Change authentication mode to use access entries.

Note: You can switch from CONFIG_MAP authentication mode to API mode, but you can't switch from API or API_AND_CONFIG_MAP to CONFIG_MAP mode. For more information, see Cluster access manager on the GitHub website.