How do I resolve the "Unauthorized" error when I use kubectl commands to access my Amazon EKS cluster?

9 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

The "Unauthorized" error occurs when an AWS Identity and Access Management (IAM) user or role creates an Amazon EKS cluster that's different from the aws-iam-authenticator cluster. 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. You can assume the cluster creator credentials, and then add the IAM role in the mapRoles section of the aws-auth ConfigMap. Or, you can use Amazon 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. That means that you aren't required to add the cluster_creator 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 grant access to is the 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.

Important: The aws-auth ConfigMap is deprecated. For the recommended method to manage access to Kubernetes APIs, see Grant IAM users access to Kubernetes with EKS access entries.

Identify the IAM user or role for the cluster creator

To identify the IAM entity for the cluster creator that has primary access to configure your Amazon EKS cluster, complete the following steps:

Search for the CreateCluster API call in AWS CloudTrail.
Check the userIdentity section of the API call.
Identify the IAM entity that you grant 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, run the following command to configure the AWS CLI with the designated_user credentials:
```
aws configure
```

To verify your AWS identity, run the following get-caller-identity command:

aws sts get-caller-identity

The following example output returns the IAM user details for designated_user:

{
    "UserId": "YOUR_USER_ID",
    "Account": "YOUR_ACCOUNT_NUMBER",
    "Arn": "arn:aws:iam::YOUR_ACCOUNT_NUMBER:user/YOUR_IAM_USERNAME"
}

To list the pods running in the cluster of the default namespace, run the following command:
```
kubectl get pods --namespace default
```
Note: The output shows the "Unauthorized" error message because the designated_user doesn't have authorization to access the Amazon EKS cluster.
To configure AWS CLI credentials for the cluster_creator IAM entity, run the following command:
```
aws configure
```
Note: Configure the AWS CLI with credentials for the IAM user or role that created the cluster. By default, only the cluster creator has admin access to the Amazon EKS cluster. If you created the cluster in the Amazon EKS console, then configure the AWS CLI with the same IAM entity that you used to sign in to the console. If you created the cluster with eksctl, then configure the AWS CLI with the IAM entity that had active credentials when you ran eksctl.
To verify that the cluster_creator has access to the cluster, run the following command:
```
kubectl get pods
```
Note: 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 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 principals to your Amazon EKS cluster.
Add the designated_user to the mapUsers section of the aws-auth.yaml file, and then save the file.
To apply the new ConfigMap to the RBAC configuration of the cluster, run the following command:
```
kubectl apply -f aws-auth.yaml
```
To change the AWS CLI configuration to use the credentials of the designated_user, run the following command:
```
aws configure
```
To verify that the designated_user has access to the cluster, run the following command:
```
kubectl get pods
```
Note: 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 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:

To get the IAM user details of the assume_role_user, run the following get-caller-identity command:
```
aws sts get-caller-identity
```
To verify that the assume_role_user has access to the cluster, run the following command:
```
kubectl get pods
```
Note: The output shows the "Unauthorized" error message because the designated_user doesn't have authorization to access the Amazon EKS cluster.

To allow the assume_role_user to assume the role of the cluster_creator, run the following assume-role command:

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

Note: Replace 123456789012 with your AWS account number, cluster_creator with your role name, and test with your session name. The output returns temporary credentials:

{
    "Credentials": {
        "AccessKeyId": "YOUR_ACCESS_KEY_ID",
        "SecretAccessKey": "YOUR_SECRET_ACCESS_KEY",
        "SessionToken": "YOUR_SESSION_TOKEN",
        "Expiration": "2026-03-31T18:20:00Z"
    },
    "AssumedRoleUser": {
        "AssumedRoleId": "AROA1234567890EXAMPLE:test",
        "Arn": "arn:aws:sts::123456789012:assumed-role/cluster_creator/test"
    }
}

To use the temporary IAM credentials to set the AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN environment variables, run the following commands:

export AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY_ID
export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_ACCESS_KEY
export AWS_SESSION_TOKEN=YOUR_SESSION_TOKEN

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

To verify that the AWS CLI uses the assumed role for the cluster_creator, run the following command:
```
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.
To apply the new configuration to the RBAC configuration of the Amazon EKS cluster, run the following command:
```
kubectl apply -f aws-auth.yaml
```

To remove the environment variables, run the following commands:

unset AWS_ACCESS_KEY_ID
unset AWS_SESSION_TOKEN
unset AWS_SECRET_ACCESS_KEY

To get the IAM user details for the designated_user, run the following command:

aws sts get-caller-identity

To verify that the designated_user has access to the cluster, run the following command:
```
kubectl get pods
```
Note: 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 resources, then no pods are running in the default namespace. If you use eksctl, then see Manage IAM users and roles.

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

Note: For more information on how to use eksctl to manage access entries, see Amazon EKS access entries in the eksctl.

Create access entries

Create access entries that grant cluster access to your IAM users and roles.

Note: To access a cluster, it's a best practice to use IAM roles that have short-term credentials rather than IAM users that have long-term credentials.

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 Amazon EKS access entry APIs and aws-auth ConfigMap. Use this mode to migrate existing aws-auth permissions to Amazon EKS access entries. This mode prioritizes authentication through Amazon EKS access entries.
API to use only Amazon EKS access entry APIs.

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

Configure your cluster with access entries

To use the Amazon EKS console to configure your cluster, complete the following steps:

Open the Amazon EKS console.
Choose the Access tab.
Under Access configuration, check the current setting of Authentication mode.
Set the cluster authentication mode to EKS API or API_AND_CONFIG_MAP.

To use the AWS CLI to configure your cluster, run the describe-cluster command:

aws eks describe-cluster --name CLUSTER_NAME --query 'cluster.accessConfig.authenticationMode' --region REGION

Note: Replace CLUSTER_NAME with the name of your cluster and REGION with your AWS Region.

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

To use the AWS CLI to change the authentication mode, run the following update-cluster-config command:

aws eks update-cluster-config \
    --name CLUSTER_NAME \
    --access-config authenticationMode=API_AND_CONFIG_MAP

Note: Replace CLUSTER_NAME with the name of your cluster. If you want to turn off the ConfigMap method permanently, then replace API_AND_CONFIG_MAP with API. 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 Identity and Access Management.