Automating EKS Access Control: Goodbye aws-auth, Hello Access Entries

May 6
4 min read

Updated: May 10

Overview

In Amazon EKS, the traditional way to grant IAM users or roles access to the Kubernetes API was through the aws-auth ConfigMap. However, managing this manually was error-prone and lacked fine-grained access control.

To address these limitations, AWS introduced Access Entries—a modern, API-driven mechanism for managing access to EKS clusters. In this post, we'll walk through migrating from the aws-auth ConfigMap to Access Entries, using Terraform to define everything as code.

What is an Access Entry?

An access entry represents a cluster identity that maps to an AWS IAM principal (a user or role) for authentication with the cluster. Similar to how IAM policies are attached to principals to authorize specific actions on AWS resources, access entries can be authorized in two ways:

By attaching an access policy directly to the access entry
By associating the access entry with a Kubernetes group

These methods define what actions the access entry can perform within the cluster.

It's important to distinguish between AWS permissions granted through IAM policies and EKS permissions granted through access policies. EKS access policies define Kubernetes-level permissions, not IAM-level permissions.

Access policies are managed by the Amazon EKS service, not by IAM. EKS provides six default access policies you can choose from. To view them, run the following command:

aws eks list-access-policies

If you see the error message aws: error: argument operation: Invalid choice, valid choices are it likely means your AWS CLI version is outdated. Updating to the latest version should resolve the issue.

For more details on access policies, refer to the official documentation. If none of the default access policies meet your needs, you can skip associating an access policy with the access entry. Instead, assign one or more Kubernetes group names to the access entry and manage permissions using Kubernetes role-based access control (RBAC).

Why Should You Migrate from aws-auth ConfigMap to Access Entries?

There are five key reasons to make the switch:

Control over Cluster-Admin Permissions:

When using the aws-auth ConfigMap, the IAM principal who created the cluster is automatically mapped to the system:masters Kubernetes group, granting admin access. This access is fixed and not visible within the aws-auth ConfigMap. With access entries, however, you can modify or even revoke Kubernetes permissions for the IAM principal who created the cluster. To update an access entry, perform under mentioned steps:

Go to EKS cluster
Click on "Access" tab
Select the entry you wish to modify and click "View details."

There you will have an option to edit the access entry/ policies.

Enhanced Visibility of Cluster Access

With the aws-auth ConfigMap, the cluster creator is not listed in the ConfigMap or any other configuration, making it harder to track their access over time. As a result, additional effort is required to document the creator and ensure this information is retained. In contrast, access entries allow you to easily view access details through the AWS console (as shown in the image above) or by running the commands below.

# Lists the access entries for your cluster.
aws eks list-access-entries --cluster-name <value>

# Describes an access entry.
aws eks describe-access-entry --cluster-name <value> --principal-arn <value>

Ability to Manage Access Externally:

With access entries, you can manage permissions using Amazon EKS APIs (such as the AWS Console or AWS CLI) instead of relying on the Kubernetes API (via kubectl or eksctl). This eliminates the need to update the ~/.kube/config file and ensures the correct context is set before modifying access mappings in the aws-auth ConfigMap.

# Creates an access entry.
aws eks create-access-entry --cluster-name <value> --principal-arn <value>

# Associates an access policy and its scope to an access entry.
aws eks associate-access-policy --cluster-name <value> --principal-arn <value> --policy-arn <value> --access-scope <value>

Eliminate Common Issues with the aws-auth ConfigMap

Modifying the aws-auth ConfigMap incorrectly can result in losing access to the cluster. It requires more care and effort to edit the aws-auth ConfigMap via kubectl edit cm aws-auth -n kube-system or eksctl compared to modifying access entries using the AWS Console, AWS CLI, or Infrastructure-as-Code (IaC) tools. If an access entry is misconfigured, cluster access can be quickly restored by calling the Amazon EKS API. Additionally, access entries allow you to include an IAM role ARN path, which is not possible with the aws-auth ConfigMap.

Compatibility and Security Considerations

The aws-auth ConfigMap is deprecated, with AWS recommending the use of access entries to manage access to Kubernetes APIs. It is likely to be removed in a future EKS version, and since it’s deprecated, no further support, bug fixes, or updates will be provided. To prevent future compatibility or security issues, it’s recommended to migrate to access entries.

Existing Setup (aws-auth ConfigMap)


mapRoles: |
  - rolearn: arn:aws:iam::123456789012:role/EKSAdminRole
    username: admin
    groups:
      - system:masters

This grants full Kubernetes cluster-admin access to the specified IAM role.

Target: Access Entry (Using Terraform)

We'll recreate this access with Terraform using the new aws_eks_access_entry and aws_eks_access_policy_association resources.

Note: These require Terraform AWS provider v5.44.0+ and EKS v1.28+.

Step-by-Step: Terraform Example

Terraform Provider Setup

provider "aws" {
  region = "us-east-1"
}

Define EKS Access Entry

resource "aws_eks_access_entry" "this" {
  cluster_name  = "my-eks-cluster"
  principal_arn = "arn:aws:iam::123456789012:role/EKSAdminRole"
}

Attach Access Policy


resource "aws_eks_access_policy_association" "this" {
  cluster_name  = "my-eks-cluster"
  principal_arn = aws_eks_access_entry.eks_admin_access.principal_arn
  policy_arn    = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy"
  access_scope {
    type = "cluster"
  }
}

This grants cluster-admin level access to the IAM role, just like system:masters.

Cleanup aws-auth ConfigMap (Optional)

Once your Access Entry is working:

Remove the equivalent role from aws-auth.
Validate access using kubectl or IAM authenticator.

kubectl edit configmap aws-auth -n kube-system

Important Notes

EKS Version: Ensure your cluster is running EKS 1.28 or later.
Permissions: Terraform user needs eks:CreateAccessEntry and eks:AssociateAccessPolicy.
IAM Roles: The IAM role must still be assumable by whoever is accessing the cluster (via aws sts assume-role or otherwise).

Appointment Organizer

Book Now

Conclusion

Migrating from the legacy aws-auth ConfigMap to Access Entries is a major step toward cleaner, scalable EKS access control. By using Terraform, you can manage this access declaratively, audit it easily, and integrate it with CI/CD pipelines.

If you're building secure, production-grade EKS clusters, now's the time to make the switch.

At Ananta Cloud, we specialize in building and optimizing Kubernetes platforms—integrating automation, observability, and scalability from day one.

🚀Empower your cloud-native applications with production-grade Kubernetes infrastructure and expert operational support.

📞 Contact Ananta Cloud today for a free consultation on your Kubernetes journey.

SPEAK TO OUR KUBERNETES EXPERT