Enable an IAM User or IAM Role to access an EKS cluster

When you create an Amazon EKS cluster, the IAM principal (IAM User or IAM Role) that creates the cluster is automatically granted system:masters (cluster-admin) permissions in the cluster's role-based access control (RBAC) configuration in the Amazon EKS control plane. This post explains how to allow other IAM principals to access the EKS cluster and avoid the "Your current IAM principal doesn't have access to Kubernetes objects on this cluster." message in the EKS dashboard.

Access to your cluster using IAM principals is enabled by the AWS IAM Authenticator for Kubernetes, which runs on the Amazon EKS control plane. The authenticator gets its configuration information from the aws-auth ConfigMap in the kube-system namespace.

While we could enable access to IAM principals by editing the aws-auth ConfigMap directly, this article will use the eksctl tool's safer approach.

eksctl is a simple but powerful CLI tool for creating and managing clusters on EKS. It is used to create, modify and delete an EKS cluster on the command line interface. From eksctl version 0.40.0, users can run eksctl commands against clusters that were not created by eksctl.

Initially, just after the creation of the EKS Cluster, only the cluster creator can fully interact with the Kubernetes cluster resources. Other IAM Users or IAM Roles trying to access the EKS resources on the AWS Management Console will get a message like this:

The message says:

Your current IAM principal doesn't have access to Kubernetes objects on this cluster. This may be due to the current user or role not having Kubernetes RBAC permissions to describe cluster resources or not having an entry in the cluster’s auth config map.

Similarly, if you run a command like this (assuming your kubeconfig is correctly configured with the profile of the IAM User or IAM Role):

kubectl get pods

The result would be:

error: You must be logged in to the server (Unauthorized)

Therefore, to grant access to the required IAM Users and IAM Roles, you need to ask the cluster creator (or use that identity yourself) to perform the tasks explained below.

NOTE: If you don't already know it, you can find the identity of the EKS Cluster creator by either analyzing CloudTrail logs or, if the cluster was configured to save Amazon EKS authenticator logs, by querying CloudWatch logs. The following post explains how to do this.

Find the creator of an EKS Cluster

How to find the AWS IAM principal that created an EKS Cluster in one minute.

Javier in the CloudJavier Carrera

Connect to the EKS Cluster with the cluster creator's credentials

Assuming that <cluster-creator-profile> is the AWS CLI profile of the cluster creator, let's first configure the kubectl connection to the EKS Cluster:

aws eks update-kubeconfig --name <cluster-name> \
  --region <region-code> \
  --profile <cluster-creator-profile>

Now, we will check the contents of the aws-auth ConfigMap using the eksctl and kubectl commands (they will provide the same information).

First with the eksctl tool:

eksctl get iamidentitymapping --cluster <cluster-name> \
  --region <region-code> \
  --profile <cluster-creator-profile>

Output:

ARN                                                                                     USERNAME                            GROUPS                              ACCOUNT
arn:aws:iam::<ACCOUNT-ID>:role/node-group-1-eks-node-group-20231128122726694500000002	system:node:{{EC2PrivateDNSName}}	system:bootstrappers,system:nodes

And now, with the kubectl tool:

kubectl -n kube-system get configmaps aws-auth -o yaml

Output:

apiVersion: v1
data:
  mapRoles: |
    - groups:
      - system:bootstrappers
      - system:nodes
      rolearn: arn:aws:iam::<ACCOUNT-ID>:role/node-group-1-eks-node-group-20231128122726694500000002
      username: system:node:{{EC2PrivateDNSName}}
kind: ConfigMap
metadata:
  creationTimestamp: "2023-11-28T12:36:37Z"
  name: aws-auth
  namespace: kube-system
  resourceVersion: "948"
  uid: f9b17a8d-e82a-4b20-8a18-2ae9c676f188

Note: It is safer to just read (and not directly edit) the aws-auth ConfigMap. The eksctl is better for this.

In both outputs, the EKS managed node group IAM role is the only entity receiving permissions through the aws-auth ConfigMap.

Note: The mapping of the cluster creator IAM User or IAM Role is implicit and is not shown in the aws-auth ConfigMap.

Note: If, for whatever reason, you corrupt the aws-auth ConfigMap, the cluster creator can still access the cluster and fix it.

(Optional) Create Kubernetes (Cluster)Roles and (Cluster)RoleBindings

The EKS cluster creator gets the permissions of the system:masters group, which has a cluster role binding to the cluster-admin cluster role. The EKS managed node group IAM role gets the permissions of the system:bootstrappers and system:nodes groups.

However, instead of assigning these default privileged permissions, you should create your own permissions using (cluster)roles and (cluster)rolebindings.

Also, notice that you don't need to create the groups beforehand. Groups added to your mappings will be used "automagically."

Let's create a ClusterRole named cluster-viewer with "read" permissions:

kubectl create clusterrole cluster-viewer \
  --verb list,get --resource "*"

And now, we can create the ClusterRoleBinding to a new group named cluster-viewer-group.

kubectl create clusterrolebinding cluster-viewer-group-binding \
  --clusterrole cluster-viewer \
  --group cluster-viewer-group

Now that we've checked the initial contents of the aws-auth ConfigMap, let's see how to provide access to the cluster to an IAM User or an IAM Role.

Enable an IAM User to access the EKS Cluster

It is an IAM best practice that you require human users to use federation with an identity provider to access AWS using temporary credentials instead of using IAM users with long-term credentials. However, if you still want to allow an IAM User to access the cluster with the permissions assigned to the desired <kubernetes-groups-name> (the predefined system:masters group or a custom group such as cluster-viewer-group) you have to run:

eksctl create iamidentitymapping --cluster <cluster-name> \
    --region <region-code> \
    --arn "arn:aws:iam::<ACCOUNT-ID>:user/<user-name>" \
    --username <user-name> \
    --group <kubernetes-group-name> \
    --no-duplicate-arns \
    --profile <cluster-creator-profile>

You can then check that the new access was granted with the get iamidentitymapping command:

eksctl get iamidentitymapping --cluster <cluster-name> \
  --region <region-code> \
  --profile <cluster-creator-profile>

Enable an IAM Role to access the EKS Cluster

To allow an IAM Role to access the cluster with the permissions assigned to the desired <kubernetes-groups-name> (the predefined system:masters group or a custom group such as cluster-viewer-group) you have to run:

eksctl create iamidentitymapping --cluster <cluster-name> \
    --region <region-code> \
    --arn "arn:aws:iam::<ACCOUNT-ID>:role/<role-name>" \
    --username <kubernetes-user-name> \
    --group <kubernetes-group-name> \
    --no-duplicate-arns \
    --profile <cluster-creator-profile>

The role ARN can't include a path such as role/application_abc/component_xyz/rdsaccess. The format of the ARN must be arn:aws:iam::<ACCOUNT-ID>:role/rdsaccess. In this example, application_abc/component_xyz/ needs to be removed.

You can then check that the new access was granted with the get iamidentitymapping command:

eksctl get iamidentitymapping --cluster <cluster-name> \
  --region <region-code> \
  --profile <cluster-creator-profile>

NOTES

If you need to modify the configuration of an existing entry in the aws-auth ConfigMap, notice that you can not do that directly as there is no eksctl command to overwrite the settings of the principals. You must first delete the existing entry and then create a new modified entry. Assuming that <cluster-admin-profile> is the AWS CLI profile of an EKS cluster administrator:

eksctl get iamidentitymapping --cluster <cluster-name> \
  --region <region-code> \
  --profile <cluster-admin-profile>

eksctl delete iamidentitymapping --cluster <cluster-name> \
  --region <region-code> \
  --arn "<ARN-of-the-principal>" \ 
  --profile <cluster-admin-profile>

eksctl create iamidentitymapping --cluster <cluster-name> \
  --region <region-code> \
  --arn "<ARN-of-the-principal>" \
  --group <group-name> \
  --no-duplicate-arns \
  --username <kubernetes-user-name> \
  --profile <cluster-admin-profile>

eksctl get iamidentitymapping --cluster <cluster-name> \
  --region <region-code> \
  --profile <cluster-admin-profile>

For more information, you can refer to the following documentation:

Enabling IAM principal access to your cluster

How do I resolve the error "You must be logged in to the server (Unauthorized)" when I connect to the Amazon EKS API server?