Grant IAM Users and Roles Access to EKS

CloudOps for Kubernetes configures EKS to use the aws-auth ConfigMap for AWS Identity and Access Management (IAM) authentication. By default, only the bootstrap IAM user and the Jenkins service account role have access to the cluster. This guide explains how to grant additional IAM roles or users access so they can inspect the cluster via kubectl and the AWS Console.

Access the EKS Cluster in the AWS Console

Users will have permission to view the EKS cluster details in the Amazon EKS console when both of the below have been completed.

• Their IAM role or user has been added to the aws-auth ConfigMap, using one of the methods described below, and
• Their IAM user or role has been granted IAM permission such as the eks:DescribeCluster (or a broader policy such as ReadOnlyAccess).

Once those have been completed, then they can view the EKS cluster in the AWS Console under Elastic Kubernetes Service.

Procedure to Grant Access

Prerequisites

• kubectl access to the cluster. See Log On To the Kubernetes Cluster.
• The Amazon Resource Name (ARN) of the IAM role or user you want to grant access to.
  • Role ARNs must not contain a path. Use arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME, not arn:aws:iam::ACCOUNT_ID:role/path/to/ROLE_NAME.

View the Current ConfigMap

To see who currently has access:

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

The mapRoles section will contain entries for the EKS node group instance roles and the Jenkins service account role. Do not remove or modify those entries.

Grant Access Using eksctl (Recommended)

Using eksctl is the safest way to add entries because it reads the existing ConfigMap, merges the new entry, and writes it back atomically.

Substitute your own values:

• AWS_PROFILE — an AWS CLI profile configured with the bootstrap credentials (see Log On To the Kubernetes Cluster)
• CLUSTER_NAME — the value of TF_VAR_kubernetes_cluster_name from docker-compose.override.yml
• REGION — the value of TF_VAR_aws_region from docker-compose.override.yml
• ROLE_ARN — the full ARN of the IAM role, for example arn:aws:iam::111122223333:role/MyTeamRole
• REFERENCE_NAME — a label used in Kubernetes audit logs. It does not need to match the IAM role name (for example, ops-team or my-team-role).

eksctl create iamidentitymapping \
  --profile=AWS_PROFILE \
  --cluster CLUSTER_NAME \
  --region REGION \
  --arn ROLE_ARN \
  --username REFERENCE_NAME \
  --group system:masters \
  --no-duplicate-arns

The system:masters group grants full cluster-admin access.

To verify the mapping was added:

eksctl get iamidentitymapping --profile=AWS_PROFILE --cluster CLUSTER_NAME --region REGION

Grant Access by Editing the ConfigMap Directly

If eksctl is not available, you can edit the ConfigMap directly.

warning

A malformed aws-auth ConfigMap can lock all users out of the cluster. Edit it carefully. Using eksctl (described above) is safer than editing the ConfigMap manually.

Add an IAM Role

kubectl edit configmap aws-auth -n kube-system

Under the mapRoles key, add an entry for your role. The indentation must be exactly as shown:

• rolearn — the full ARN of the IAM role, for example arn:aws:iam::111122223333:role/MyTeamRole
• username — a label used in Kubernetes audit logs. It does not need to match the IAM role name (for example, ops-team or my-team-role).

data:
  mapRoles: |
    # ... existing entries, do not remove them ...
    - groups:
      - system:masters
      rolearn: ROLE_ARN
      username: REFERENCE_NAME

Save and close the editor to apply the change.

Add an IAM User

note

AWS recommends granting access to IAM roles rather than IAM users. Consider assigning the user to a role and granting that role access instead.

Add an entry under the mapUsers key (create the key if it does not exist):

• userarn — the full ARN of the IAM user, for example arn:aws:iam::111122223333:user/jane
• username — a label used in Kubernetes audit logs (for example, jane)

data:
  mapUsers: |
    # ... existing entries, do not remove them ...
    - groups:
      - system:masters
      userarn: USER_ARN
      username: REFERENCE_NAME

Configure kubectl for the New Principal

If the user wants to use kubectl to access the cluster, then they must configure their local kubeconfig to point at the cluster. They should run the following command using their own AWS credentials:

aws eks update-kubeconfig \
  --name CLUSTER_NAME \
  --region REGION

Verify Access

After configuring kubeconfig, they can run kubectl commands to verify that can reach the cluster:

kubectl get nodes

The above example commands will list list cluster nodes, confirming that access is working.

Reference

• Grant IAM users access to Kubernetes with a ConfigMap — AWS documentation