Post cover image

June 9, 2026

Migrating EKS from aws-auth ConfigMap to Access Entries: A Phased Production Guide

In our main EKS architectural series, we established that a production cluster is only as secure as its gatekeeper. For years, that…

By M Bilal

5 min read

In our main EKS architectural series, we established that a production cluster is only as secure as its gatekeeper. For years, that gatekeeper was the aws-auth ConfigMap — a clunky, manual bridge between IAM and Kubernetes.

This guide provides a battle-tested roadmap to systematically dismantle that legacy ConfigMap and move your live enterprise clusters over to the EKS Access Entries API.

The Problem with the Legacy Way (aws-auth)

If you've managed EKS for long, you know the pain:

  • Race Conditions: If the ConfigMap isn't updated at the exact right moment during automated node provisioning, nodes won't join or admins lose access.
  • Lack of Visibility: You can't see cluster permissions via the AWS Console or API; you have to dig into Kubernetes internal objects to audit who has access.
  • Brittle Management: A single YAML indentation error or a corrupted change pushed to the ConfigMap can instantly lock everyone — including your CI/CD pipelines — out of the cluster.
  • Scale Limitations: A single ConfigMap is bound by etcd's per-object size limit (1 MiB by default). For massive enterprises with thousands of developers, you will literally run out of room to define users in a single object.

1. The Migration Strategy: The Hybrid Bridge

We don't just "flip a switch" in a live production environment. We use a phased hybrid approach. By setting the cluster's authentication mode to API_AND_CONFIG_MAP, we allow the new API-based entries to work seamlessly alongside the old ConfigMap while we verify our permissions.

graph LR
    A[Start: ConfigMap Only] --> B[Step 1: Upgrade Control Plane API_AND_CONFIG_MAP]
    B --> C[Step 2: Map Entries via API]
    C --> D[Step 3: Validate & Audit]
    D --> E[Step 4: API Only - ConfigMap Destroyed]

2. Step 0: Inventory Your Current State

Before you change anything, write down what you're migrating from. You cannot safely cut over to the API model if you don't know which principals the old ConfigMap was authorizing. Dump the live ConfigMap:

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

Walk through every entry under mapRoles and mapUsers. For each one, record:

  • The IAM principal ARN
  • Whether it's a worker-node role, a human user, or an automation principal (CI/CD, third-party tools)
  • The Kubernetes RBAC groups it was mapped into (system:masters, system:nodes, custom groups, etc.)

This inventory is the contract you'll validate against at the end of Step 3. Without it, "we're done migrating" is a guess, not a verifiable claim. Keep aws-auth.backup.yaml checked into a private repo until Step 4 is complete — it is your rollback artifact.

3. Step 1: Upgrade the Control Plane

Before mapping users, your EKS control plane must be instructed to look at the AWS API for authorization mapping. We use Terraform to switch the cluster's authentication_mode without disrupting active workloads.

module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "~> 20.0"

  cluster_name    = "production-cluster"
  cluster_version = "1.31"

  # The Hybrid Bridge: enables both methods simultaneously.
  authentication_mode = "API_AND_CONFIG_MAP"

  # Module default in v20+ is `true`, which automatically creates an
  # access entry for the IAM principal running `terraform apply` and
  # attaches AmazonEKSClusterAdminPolicy. Be aware of this — if you see
  # an access entry you didn't explicitly declare, this is the source.
  # Set to `false` if your platform team prefers to manage every entry
  # explicitly.
  enable_cluster_creator_admin_permissions = true
}

Applying this change updates the EKS control plane metadata in place with zero downtime to running pods.

4. Step 2: Mapping Personas via Access Entries

With the hybrid bridge active, we can begin mirroring the entries from your old aws-auth ConfigMap into native Terraform resources using aws_eks_access_entry. Work through your inventory from Step 0, one principal at a time.

A. Registering Worker Nodes (Crucial)

If your worker nodes are managed by specialized configurations or custom autoscaling engines (e.g., Karpenter, self-managed node groups) rather than native EKS managed groups, they must be registered immediately so they don't drop out of the cluster.

resource "aws_eks_access_entry" "worker_nodes" {
  cluster_name  = module.eks.cluster_name
  principal_arn = "arn:aws:iam::123456789012:role/custom-node-execution-role"
  type          = "EC2_LINUX" # Tells EKS this IAM role belongs to a node bootstrap loop
}

The EC2_LINUX type causes EKS to automatically grant the role the Kubernetes RBAC permissions a node kubelet needs (the equivalent of the old system:nodes group). You do not need a separate aws_eks_access_policy_association for nodes.

B. Registering Human Admins & Platforms

Unlike the old way where you passed raw Kubernetes RBAC groups as strings, the new API introduces Access Policies — managed permission sets applied directly at the AWS cloud boundary.

resource "aws_eks_access_entry" "admin_user" {
  cluster_name  = module.eks.cluster_name
  principal_arn = "arn:aws:iam::123456789012:user/bilal.ayyoob"
  type          = "STANDARD"
}

resource "aws_eks_access_policy_association" "admin_policy" {
  cluster_name  = module.eks.cluster_name
  policy_arn    = "arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy"
  principal_arn = aws_eks_access_entry.admin_user.principal_arn

  access_scope {
    type = "cluster"
  }
}

Note the policy ARN format: arn:aws:eks::aws:cluster-access-policy/.... The service prefix is eks, not iam — a detail that catches a lot of first-time users off guard.

5. Step 3: The Validation & Audit Protocol

Once your access entries are deployed, you must verify that authorization requests are passing through the new API layer before cutting the cord.

Run the following command to check that AWS recognizes your cloud-native configurations:

aws eks list-access-entries --cluster-name production-cluster

Cross-check the output against the inventory you took in Step 0. Every principal in aws-auth.backup.yaml should have a corresponding access entry. Anything missing is a future lockout waiting to happen.

Next, verify that your active user context can perform actions against the API server:

kubectl auth can-i "*" "*" --all-namespaces

Important caveat: kubectl auth can-i only validates the principal you are currently authenticated as. It does not confirm that all migrated users have correct access. For a rigorous audit, test at least one principal in each category — admin, viewer, CI/CD role, node IAM role — by assuming each role, running aws eks update-kubeconfig, and executing a representative action (kubectl get pods -n some-ns, etc.). Until every category has been exercised, you have not actually validated the migration.

6. Step 4: Cutting the Cord (API Only)

After auditing your access logs and confirming that both human operators and compute components are communicating successfully through the cloud provider APIs, it's time to delete the legacy system entirely.

Pre-flight Checklist — confirm all of the following before proceeding:

  • Every entry from your Step 0 inventory (aws-auth.backup.yaml) has a corresponding aws_eks_access_entry resource applied and visible in aws eks list-access-entries.
  • You have exercised at least one principal in each category (admin, edit, view, node IAM role, CI/CD role) and confirmed access works through the API path.
  • You have AWS CLI access from a separate IAM principal that holds eks:AssociateAccessPolicy and eks:CreateAccessEntry permissions — your break-glass account, in case you lock yourself out.
  • You have a recent backup of aws-auth.backup.yaml in a private repository, available if you ever need to reconstruct the migration map.

Only proceed when every box is checked.

Step 1: Update Terraform to Lock Down Authentication

Change your cluster configuration to drop ConfigMap support entirely.

module "eks" {
  source  = "terraform-aws-modules/eks/aws"
  version = "~> 20.0"

  cluster_name        = "production-cluster"
  authentication_mode = "API" # ConfigMap is now ignored completely by EKS
}

Step 2: Purge the Legacy Remnant

Clean your cluster by physically removing the old Kubernetes resource:

kubectl delete configmap aws-auth -n kube-system

Architect's Summary: The Clean State

By migrating completely to EKS Access Entries, you have successfully:

  • Converted an obscure internal text-file configuration into immutable Infrastructure as Code.
  • Gained full visibility over who has access to your clusters directly from the AWS Console and CLI.
  • Eradicated the catastrophic cluster-wide lockout risks introduced by YAML indentation mistakes in the ConfigMap.
  • Established a reproducible, inventory-driven migration pattern you can apply to every future EKS cluster you operate.