Introduction

When working with Amazon EKS (Elastic Kubernetes Service), one of the critical aspects to manage is user authentication. Kubernetes provides several ways to authenticate users and workloads, but when integrating with AWS, IAM-based authentication is a powerful and secure approach. Amazon EKS supports API authentication using AWS IAM roles and users, and ConfigMap-based authentication is used to map IAM identities to Kubernetes RBAC groups and roles.

In this article, we will explore how these two authentication methods work together to ensure secure access to your Kubernetes cluster.

Authentication Overview in Amazon EKS

1. IAM Authentication (API Authentication)

   • IAM authentication is the primary method for authenticating users and workloads to the Kubernetes API in Amazon EKS.

   • IAM roles and users are used to authenticate, and the aws-iam-authenticator (integrated with EKS) ensures seamless authentication by verifying IAM credentials.

   • Kubernetes Role-Based Access Control (RBAC) is then used to manage fine-grained permissions.

2. ConfigMap-based Authentication

   • The aws-auth ConfigMap is the central place where IAM roles and users are mapped to Kubernetes users and groups.

   • While ConfigMap-based authentication is not a separate mechanism, it complements the IAM-based authentication by mapping the authenticated IAM identities to specific Kubernetes groups (e.g., system:masters for admin access).

How IAM Authentication Works in EKS

When an IAM identity (user or role) attempts to access the Kubernetes API, the API server authenticates the request using IAM credentials. AWS IAM is used to validate the identity, and after successful authentication, the aws-auth ConfigMap defines what Kubernetes groups the identity belongs to. These groups control what RBAC permissions the user or service has within the cluster.

Here’s how the authentication process works:

1. The IAM user or role makes a request to the Kubernetes API.

2. The IAM role or user is authenticated via AWS IAM.

3. The aws-auth ConfigMap maps IAM roles/users to specific Kubernetes groups and users.

4. Kubernetes RBAC policies are applied to grant the appropriate permissions based on the user's group.

Setting Up IAM and ConfigMap Authentication in Amazon EKS

1. Create an EKS Cluster

If you don’t have an EKS cluster set up already, you can create one using the AWS Management Console, AWS CLI, or eksctl.

Example using eksctl:

eksctl create cluster --name my-cluster --region us-west-2 --nodes 3 --node-type t3.medium

2. Create IAM Roles for the EKS Cluster

Before mapping users or roles to Kubernetes groups, create IAM roles or users in AWS IAM.

Example to create an IAM role for the EKS cluster:

1. Go to IAM > Roles and select Create role.

2. Attach the necessary IAM policies such as AmazonEKSClusterPolicy.

3. Name the role (e.g., eks-cluster-role) and create it.

Alternatively, you can use the AWS CLI:

aws iam create-role --role-name eks-cluster-role --assume-role-policy-document file://eks-cluster-trust-policy.json

Trust policy file (eks-cluster-trust-policy.json):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "eks.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

3. Map IAM Roles and Users to Kubernetes Groups in the aws-auth ConfigMap

Once IAM roles or users are created, the aws-auth ConfigMap is used to map these identities to Kubernetes groups. This is a crucial step in defining what access permissions the IAM roles and users will have in the cluster.

1. First, retrieve the current aws-auth ConfigMap:

    kubectl -n kube-system get configmap/aws-auth -o yaml > aws-auth.yaml
   

2. Edit the aws-auth.yaml file to add the IAM roles and users. For example:

   Example for IAM role:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: aws-auth
      namespace: kube-system
    data:
      mapRoles: |
        - rolearn: arn:aws:iam::123456789012:role/eks-admin-role
          username: eks-admin
          groups:
            - system:masters
   

   Example for IAM user:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: aws-auth
      namespace: kube-system
    data:
      mapUsers: |
        - userarn: arn:aws:iam::123456789012:user/username
          username: kubernetes-user
          groups:
            - system:masters
   

   • rolearn: The ARN of the IAM role.

   • userarn: The ARN of the IAM user.

   • username: The Kubernetes username the IAM identity will use.

   • groups: The Kubernetes groups that the IAM identity will be part of.

3. Apply the changes to the aws-auth ConfigMap:

    kubectl apply -f aws-auth.yaml
   

4. Verify Access

To ensure the IAM roles and users are properly authenticated and mapped to Kubernetes roles:

1. Assume the IAM role or use the IAM user credentials via AWS CLI:

    aws sts assume-role --role-arn arn:aws:iam::123456789012:role/eks-admin-role --role-session-name eks-session
   

2. Set the temporary credentials in your environment variables and use kubectl commands to check your access:

    kubectl get nodes
   

   If the mapping is done correctly, the IAM identity should have the appropriate level of access to the cluster.

Can You Use Both Authentication Methods Together?

Yes! You can use both IAM authentication and ConfigMap-based authentication together. In fact, they are designed to work together seamlessly. IAM provides the identity, while the aws-auth ConfigMap manages the mapping of IAM users and roles to Kubernetes users and groups. This allows you to control access to the Kubernetes API based on IAM roles and users, and the ConfigMap ensures that those identities are mapped to appropriate Kubernetes RBAC groups.

For example, you can have different IAM roles for admin access, read-only access, or custom access. The aws-auth ConfigMap maps these IAM roles and users to appropriate Kubernetes groups, which determine their permissions within the cluster.

Example: Combining IAM and ConfigMap Authentication

Here’s an example of how you might combine IAM roles and users in the aws-auth ConfigMap:

apiVersion: v1
kind: ConfigMap
metadata:
  name: aws-auth
  namespace: kube-system
data:
  mapRoles: |
    - rolearn: arn:aws:iam::123456789012:role/eks-admin-role
      username: eks-admin
      groups:
        - system:masters
    - rolearn: arn:aws:iam::123456789012:role/eks-readonly-role
      username: eks-readonly
      groups:
        - read-only
  mapUsers: |
    - userarn: arn:aws:iam::123456789012:user/username
      username: kubernetes-user
      groups:
        - system:masters

• eks-admin-role is mapped to the system:masters group (admin access).

• eks-readonly-role is mapped to the read-only group (limited access).

• username is mapped to the system:masters group (admin access).

Conclusion

Both IAM Authentication and ConfigMap-based Authentication are essential components for managing secure access to your Amazon EKS cluster. IAM handles the identity and authentication of users and services, while the aws-auth ConfigMap defines the mapping to Kubernetes groups that control access levels. Together, they provide a flexible and secure method for managing access to your Kubernetes resources.