IAM Authentication & aws-auth

EKS authenticates users with AWS IAM, then maps IAM identities to Kubernetes users and groups.

EKS has an unusual split: authentication (who are you?) is handled by AWS IAM, while authorization (what can you do?) is handled by Kubernetes RBAC. The bridge between them is an identity mapping.

Two ways to map identities

  • Access entries (newer, recommended) — managed through the EKS API with aws eks create-access-entry. No cluster config to edit.
  • aws-auth ConfigMap (classic) — a ConfigMap in kube-system that lists which IAM roles/users map to which Kubernetes groups.

Why it matters

The IAM identity that created the cluster is automatically an admin. Everyone else must be added, or they'll get an Unauthorized error even with valid AWS credentials.

Example

Example · bash
# Modern way: grant an IAM role cluster-admin via an access entry
aws eks create-access-entry \
  --cluster-name demo \
  --principal-arn arn:aws:iam::111122223333:role/DevOps

aws eks associate-access-policy \
  --cluster-name demo \
  --principal-arn arn:aws:iam::111122223333:role/DevOps \
  --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy \
  --access-scope type=cluster

When to use it

  • A platform team adds a new IAM user to the aws-auth ConfigMap so a developer can run kubectl without creating separate Kubernetes credentials.
  • A security team maps a CI/CD IAM role to the system:masters group in aws-auth so the pipeline can deploy to the cluster without long-term passwords.
  • A compliance officer reviews the aws-auth ConfigMap to audit which IAM entities have cluster-admin access before a SOC 2 audit.

More examples

View aws-auth ConfigMap

Displays the aws-auth ConfigMap that maps IAM users and roles to Kubernetes users and groups.

Example · bash
kubectl get configmap aws-auth -n kube-system -o yaml

Add IAM role to aws-auth

Maps an IAM role to a Kubernetes username and group in aws-auth using eksctl, granting the CI/CD role cluster-admin access.

Example · bash
eksctl create iamidentitymapping \
  --cluster prod \
  --arn arn:aws:iam::123456789012:role/CICDDeployRole \
  --username cicd-deployer \
  --group system:masters

View all IAM identity mappings

Lists all IAM-to-Kubernetes identity mappings configured on the cluster, providing an auditable inventory of who has access.

Example · bash
eksctl get iamidentitymapping --cluster prod

Related

eks rbaceks kubeconfig

Discussion

  • Be the first to comment on this lesson.