Amazon EKS Access Entries: Authorization Design and aws-auth Migration

Amazon EKS access entries provide an EKS API-managed mapping between an IAM principal and Kubernetes permissions. They can replace new human and automation mappings in the legacy aws-auth ConfigMap, but they do not collapse AWS identity, Kubernetes authentication, and Kubernetes authorization into one permission switch. A principal must still be allowed to assume its IAM role, authenticate to the cluster, and receive the specific Kubernetes permissions required for its work.

The production design has two separate authorization mechanisms after authentication: EKS access policies and Kubernetes RBAC. Access policies are predefined Kubernetes allow rules maintained by AWS, while group names on a standard access entry can connect the IAM identity to Kubernetes RoleBinding and ClusterRoleBinding objects. When both mechanisms grant access, their permissions accumulate. Treat the access entry, IAM trust policy, policy associations, Kubernetes bindings, and authentication mode as one reviewed access contract.

Understand the cluster authentication modes

An EKS cluster can use one of three authentication modes:

CONFIG_MAP uses IAM mappings in the in-cluster aws-auth ConfigMap.
API_AND_CONFIG_MAP accepts access entries in the EKS API and mappings in aws-auth.
API uses access entries and no longer uses aws-auth for IAM principal access.

Enabling the EKS API is a one-way mode transition: you cannot later change the cluster to a mode that removes access entries. In API_AND_CONFIG_MAP, the two mapping stores remain separate; creating an access entry does not edit aws-auth. For the same IAM principal represented in both stores, EKS uses the access entry’s mapping. This makes a dual-mode migration possible, but it also means an old ConfigMap entry can conceal a mismatch until the access entry is tested.

Check the current mode before planning a change:

aws eks describe-cluster \
  --name production \
  --query 'cluster.accessConfig.authenticationMode' \
  --output text

For a cluster that currently uses CONFIG_MAP, enabling both methods preserves a migration window:

aws eks update-cluster-config \
  --name production \
  --access-config authenticationMode=API_AND_CONFIG_MAP

This is an EKS cluster update, not an instantaneous edit. Wait for the cluster to return to ACTIVE and confirm the resulting mode before depending on new access entries. Review platform-version requirements for older clusters, and make the transition through the same infrastructure-as-code and change-control path as other cluster configuration. Do not enable the API casually in a cluster whose long-term access and rollback expectations have not been reviewed.

Choose a permission source deliberately

An access entry of type STANDARD can grant permissions through one or both of these mechanisms:

Associate an EKS access policy with a cluster-wide or namespace scope.
Set one or more Kubernetes group names and bind those groups to Kubernetes RBAC roles.

EKS access policies contain Kubernetes permissions, not AWS IAM permissions. They are predefined by AWS, are not editable, and only express allow rules. If no policy matches the required permission set, use Kubernetes RBAC groups instead of trying to extend a managed policy. Scope a policy to the smallest set of namespaces that fits the job. EKS does not verify that a namespace string in the association exists or is spelled correctly, so validate names against the cluster before rollout.

The policy’s displayed name is not a substitute for reviewing its rules. Read the current permission table before granting it. In particular, the EKS AmazonEKSAdminViewPolicy includes read access to Kubernetes Secrets. A team that treats secret reads as privileged must not infer that “view” means secrets are excluded. Prefer policies whose actual resources and verbs match the task, and use namespace scope where cluster-wide visibility is not required.

If using a Kubernetes group, create the corresponding RBAC objects. EKS accepts the group string without checking that a RoleBinding or ClusterRoleBinding exists. A missing or misspelled binding therefore leaves the IAM principal authenticated but without the intended permissions. For example, a namespace-scoped reader group can be bound like this:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: workload-reader
  namespace: payments
rules:
  - apiGroups: [""]
    resources: ["pods", "pods/log"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: workload-reader-binding
  namespace: payments
subjects:
  - kind: Group
    name: platform-payments-readers
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: workload-reader
  apiGroup: rbac.authorization.k8s.io

Kubernetes RBAC and EKS access policies are additive. Giving a principal a narrow namespace policy and also placing it in a broad Kubernetes group does not constrain the broad group; the principal keeps the union of permissions. Remove unintended grants from every mechanism instead of expecting one source to deny permissions granted by another. Also remember that a namespace RoleBinding grants permissions only in its namespace, while a ClusterRoleBinding can make its referenced permissions cluster-wide.

Create a standard entry for a human or automation role

Prefer federated or otherwise short-lived IAM role credentials for people and automation instead of long-lived IAM user keys. The IAM trust and permission policies that allow a caller to assume a role are still independent of Kubernetes permissions. A role that can be assumed is not automatically a Kubernetes administrator, and a Kubernetes access policy does not grant the IAM ability to assume that role.

Create a standard access entry for an existing role and associate a namespace-scoped EKS policy:

aws eks create-access-entry \
  --cluster-name production \
  --principal-arn arn:aws:iam::111122223333:role/platform/payments-readonly \
  --type STANDARD

aws eks associate-access-policy \
  --cluster-name production \
  --principal-arn arn:aws:iam::111122223333:role/platform/payments-readonly \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy \
  --access-scope type=namespace,namespaces=payments

Use the IAM role ARN that actually exists in the target account. Access-entry ARNs can include IAM role paths, unlike legacy aws-auth mappings, but the principal ARN is fixed when the entry is created. You cannot update an access entry to point at a different IAM identity; create the intended identity mapping deliberately. An IAM principal cannot be included in more than one access entry in the same cluster.

Do not use a human or general-purpose automation entry type to represent worker nodes. EKS has distinct access-entry types for supported node roles, including EC2 Linux, EC2 Windows, Fargate Linux, and hybrid Linux. These types supply node-oriented identity behavior and do not use the standard group’s and policy-association workflow. Follow the EKS documentation for the compute model before changing node-related mappings.

Migrate `aws-auth` without cutting off the cluster

The most common migration mistake is assuming that enabling access entries copies all aws-auth rows. It does not. For eligible older clusters, EKS creates an entry for the original cluster creator, but custom IAM roles and users in the ConfigMap must be migrated explicitly. Entries for managed node groups or Fargate profiles may have been created by EKS itself; deleting those mappings without ensuring the corresponding access entries exist can break cluster operation.

Use a staged migration:

Record the cluster’s authentication mode and export a reviewed inventory of aws-auth, current access entries, policy associations, IAM principals, and Kubernetes RBAC bindings.
Identify which ConfigMap rows are customer-managed mappings and which are maintained for EKS compute integrations. Assign an owner to every principal and preserve node mappings until the equivalent supported access entry has been verified.
If the cluster is still in CONFIG_MAP, move to API_AND_CONFIG_MAP, then wait for the EKS update to complete. Keep both stores available while migrating.
Create the corresponding standard or node access entries, policy associations, and RBAC bindings. Preserve intended usernames and groups when converting a custom mapping, but review them rather than copying powerful groups blindly.
Test each human and automation role using the actual IAM credentials it will use in production. Verify the exact API operations and namespaces it should allow and deny.
Only after the new path works, remove the migrated customer-created ConfigMap entries. Keep EKS-managed node mappings until you have confirmed that their supported access entries are present and healthy.
If the organization intends to stop using aws-auth, plan a separate change to API mode after every required principal is represented and validated through access entries.

While both stores are enabled, an access entry takes precedence over a ConfigMap mapping for the same IAM principal. The mapping that wins may therefore change as soon as the new entry is created. Compare the two definitions before creating entries for existing principals, especially where usernames or groups differ. Test cluster recovery access and the deployment role before removing the old path.

Validate effective permissions as the real principal

kubectl auth can-i --list is not a complete inventory of permissions granted through EKS access policies. AWS documents that this command does not display EKS-policy permissions for the IAM principal used to call it. Impersonation with --as or --as-group also exercises Kubernetes RBAC for the impersonated identity; it does not validate the access-policy authorization path of the original IAM principal.

For an EKS access policy, use the real role credentials and issue targeted authorization checks for expected operations. For example:

kubectl auth can-i get pods -n payments
kubectl auth can-i get secrets -n payments
kubectl auth can-i create deployments -n payments

The expected result should reflect the access contract, not just a successful kubectl connection. Test both positive and negative cases: the intended read should succeed, while an out-of-scope namespace or write verb should be denied. If the identity also belongs to a Kubernetes group, evaluate those bindings separately and account for their additive permissions. For group-based RBAC, inspect the RoleBinding and ClusterRoleBinding subjects and referenced roles, then test through the original role without impersonation.

Audit the EKS control-plane access configuration and Kubernetes audit records together. Use stable role names, meaningful access-entry tags, and role session identities that let operators correlate a person or automation run with API activity. Avoid custom usernames that discard useful session attribution. Access-entry create or update operations can take several seconds to propagate, so make automation verify effective access before a dependent production job begins.

Manage the lifecycle of the IAM principal

An access entry binds an IAM principal ARN to an internal identity. If an IAM role is deleted and later recreated with the same ARN, it has a different underlying role identifier. The old access entry does not become valid just because the text of the ARN matches again. Remove stale entries and create fresh ones as part of the IAM principal replacement workflow.

This lifecycle matters for infrastructure-as-code modules and account vending. Treat role replacement as a coordinated operation: create the new principal, update the cluster access entry, validate the new path, then retire the old role and mapping. Do not leave orphaned access entries after deleting principals. Conversely, do not remove a principal from IAM or EKS until its workloads, break-glass path, and cluster operations have moved to an owned replacement.

Keep entry creation outside high-availability request paths. EKS documents access-entry changes as eventually consistent; a successful API response may precede effective permissions. A cluster bootstrap or deployment pipeline should wait for the access entry to appear and then test a narrowly scoped API operation before handing work to the principal.

Production review checklist

The cluster’s authentication mode and one-way transition impact are understood and recorded.
Every access entry maps one existing IAM principal to one cluster entry with a named owner and purpose.
The entry type matches a standard human or automation principal, a node role, or another documented compute use case.
EKS policies are reviewed by their Kubernetes resources and verbs, not just by their names.
Namespace scope names are verified against existing namespaces; unnecessary cluster-wide scope is avoided.
Group names have matching Kubernetes RBAC bindings, and no broader binding accidentally expands the union of permissions.
Legacy aws-auth custom entries are migrated manually; EKS-created node mappings are preserved until equivalents are verified.
Access to secrets, cluster-wide operations, and emergency administration is tested explicitly.
Validation uses the real IAM role credentials and includes expected-deny cases; kubectl auth can-i --list is not treated as an EKS-policy inventory.
Principal deletion and recreation, entry cleanup, eventual consistency, and recovery access have documented procedures.

Access entries are most useful when they make cluster access easier to review without hiding the authorization model. Keep IAM trust, EKS access policies, Kubernetes RBAC, and legacy migration state visible as separate controls. Then test the effective permission set using the real principal before changing the cluster’s only working access path.

Related:

Sources: