K8s

Amazon EKS Credentials and Authentication

Learn how AWS credentials, EKS authentication, Kubernetes RBAC, node roles, workload identity, and CI/CD access work together securely.

Amazon EKS access has several separate layers. AWS IAM identifies the caller, EKS authenticates that caller to the Kubernetes API, and Kubernetes authorization determines which API operations are allowed. Workloads in pods use a different credential path when they need to call AWS services.

This distinction explains many common errors: an Unauthorized response usually indicates an EKS authentication problem, while a Forbidden response usually means authentication succeeded but Kubernetes RBAC denied the operation.

The EKS credential and authorization layers

The request path normally looks like this:

1. A person, CI/CD job, node, or application obtains AWS credentials.
2. The AWS CLI or SDK uses those credentials to identify an IAM principal.
3. kubectl invokes an exec credential plugin, commonly the AWS CLI, to request a short-lived EKS authentication token.
4. The EKS API authenticates the IAM principal represented by that token.
5. EKS access configuration maps the principal to cluster access, groups, or an AWS-managed EKS access policy.
6. Kubernetes authorization, commonly RBAC, decides whether the requested verb and resource are permitted.

Permission to call AWS APIs does not automatically grant permission to create pods, read Secrets, or administer Kubernetes objects. Conversely, an identity can be accepted by the EKS API and still have no useful Kubernetes permissions.

AWS credentials used with EKS

An access key is a credential pair used to sign AWS API requests. A long-lived access key belongs to an IAM user or other credential owner and should not be the normal choice for human, node, or application access.

An IAM role is an assumable identity. AWS Security Token Service (STS) issues temporary credentials when a trusted principal assumes the role. Temporary credentials include an access key ID, secret access key, and session token, and expire after a limited period.

AWS IAM Identity Center provides workforce sign-in and cached, short-lived sessions through named AWS CLI profiles. EC2 instance roles provide temporary credentials to instances through instance metadata. Containers can receive credentials from container credential endpoints, and workloads can use web identity tokens or EKS Pod Identity.

The AWS SDK and CLI credential provider chain

The AWS SDK and AWS CLI examine credential sources in an ordered provider chain. Exact precedence can vary by SDK, but common sources include environment variables, an explicitly selected profile, shared AWS configuration and credential files, IAM Identity Center caches, web identity token files, container credentials, and EC2 instance metadata.

Environment variables such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_PROFILE, and AWS_REGION can change which identity or region is used. An environment credential can take precedence over the profile you expected to use. Always inspect the effective configuration rather than assuming it.

Configure and verify the AWS CLI

Use a named profile for a clear, repeatable identity. Interactive configuration may create entries in shared AWS configuration and credential files:

aws configure
aws configure set region us-west-2 --profile platform-admin
export AWS_PROFILE=platform-admin
export AWS_REGION=us-west-2

For an IAM Identity Center profile, start or refresh its session before using EKS:

aws sso login --profile platform-admin

Verify the caller before generating a token or changing a cluster:

aws sts get-caller-identity
aws sts get-caller-identity --profile platform-admin
aws configure list

The result identifies the AWS account and the ARN of the current user or assumed role. EKS cluster discovery also requires permission to call eks:DescribeCluster for the target cluster. Confirm the account, region, cluster name, profile, and assumed role together.

Role assumption

A profile can be configured to assume a role from a source profile. The source identity must be allowed to call STS role assumption, and the target role trust policy must trust that source identity. A role session can then be used to discover the cluster and generate an EKS token.

kubectl, kubeconfig, and EKS tokens

A kubeconfig describes Kubernetes clusters, users, and contexts. A cluster entry contains the API server and certificate authority data. A user entry describes how credentials are obtained. A context combines a cluster and user, optionally with a default namespace.

For EKS, the user entry usually contains an exec credential plugin. Rather than storing a static Kubernetes password, kubectl executes the AWS CLI to generate a short-lived EKS authentication token. The token represents the AWS principal active at that moment.

aws eks update-kubeconfig --region us-west-2 --name production
aws eks update-kubeconfig --region us-west-2 --name production --profile platform-admin --alias production
aws eks update-kubeconfig --region us-west-2 --name production --role-arn arn:aws:iam::123456789012:role/EksClusterOperator

kubectl config current-context
kubectl get namespaces

--profile selects credentials used while updating or using the configuration, while --role-arn selects a role for EKS authentication. Use aliases to avoid confusing similarly named clusters and inspect the selected entry with:

kubectl config view --minify

EKS tokens are short-lived. The exec plugin normally obtains a fresh token when needed, but renewal cannot work if the underlying IAM Identity Center session, assumed-role session, web identity token, or other AWS credentials have expired. Refresh the AWS session and retry before rebuilding kubeconfig.

EKS API authentication mechanisms

Access entries and access policies

EKS access entries are the current AWS-managed mechanism for registering IAM principals with a cluster. An entry identifies a principal and can provide Kubernetes groups or associate an EKS access policy. AWS-managed access policies provide common scopes such as view, edit, or administrative access, with optional namespace scope.

aws eks list-access-entries --cluster-name production --region us-west-2
aws eks create-access-entry --cluster-name production --principal-arn arn:aws:iam::123456789012:role/DeveloperRole --type STANDARD
aws eks associate-access-policy --cluster-name production --principal-arn arn:aws:iam::123456789012:role/DeveloperRole --policy-arn arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy --access-scope type=namespace,namespaces=team-a

The legacy aws-auth ConfigMap

Older clusters commonly map IAM roles or users through the aws-auth ConfigMap in the kube-system namespace. The mapping supplies Kubernetes usernames and groups, which are then evaluated by Kubernetes RBAC. It may still be present during migration or in clusters configured to use it.

kubectl get configmap aws-auth -n kube-system -o yaml

Do not edit this ConfigMap casually: a syntax error or removal of an administrator mapping can lock out operators. Before migrating, identify the cluster authentication mode, existing role and user mappings, group-based RoleBindings, and equivalent access-entry policies. Test a replacement identity before removing old access.

Authentication modes and bootstrap access

EKS authentication modes determine which mechanisms the cluster accepts. API uses access entries, API_AND_CONFIG_MAP accepts both access entries and the legacy ConfigMap, and CONFIG_MAP uses the legacy model. The available modes and transition rules depend on the cluster configuration and EKS support for that cluster.

The principal that creates a cluster receives special initial access considerations. Treat this bootstrap administrator identity as a recovery path, not as a shared daily credential. Create named operator roles and access entries promptly, and protect the bootstrap identity.

Kubernetes RBAC authorization

Role-based access control (RBAC) grants permissions to subjects. A Kubernetes Role is namespace-scoped; a ClusterRole can describe cluster-wide permissions or reusable rules; a RoleBinding grants a Role or ClusterRole within one namespace; and a ClusterRoleBinding grants a ClusterRole across the cluster.

Subjects include authenticated users, groups supplied by the EKS access mechanism, and Kubernetes ServiceAccounts. A ServiceAccount is a Kubernetes identity for a workload. Its token is a Kubernetes credential and is not, by itself, an AWS access key or IAM role session.

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: team-a-readonly
  namespace: team-a
rules:
- apiGroups: [""]
  resources: ["pods", "services"]
  verbs: ["get", "list", "watch"]
- apiGroups: ["apps"]
  resources: ["deployments"]
  verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: developer-team-a-readonly
  namespace: team-a
subjects:
- kind: Group
  name: team-a-developers
  apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: team-a-readonly
  apiGroup: rbac.authorization.k8s.io

The EKS access entry must place the IAM principal in team-a-developers, or an equivalent EKS access policy must grant the intended access. Creating only the RoleBinding does not make an IAM principal known to the cluster.

kubectl auth can-i get pods --namespace team-a
kubectl auth can-i create deployments --namespace team-a

Use namespace-scoped Roles and read-only verbs whenever possible. Avoid cluster-admin access for routine developers, deployment jobs, nodes, and applications.

Common EKS roles and permissions

Node credentials and registration

Managed node groups use a node IAM role supplied by the node group configuration. Self-managed nodes and launch templates also require an instance profile or equivalent role. During bootstrap, the node discovers the cluster, configures the kubelet, and authenticates to the Kubernetes API. The kubelet then uses Kubernetes node authorization to perform node operations.

Node IAM permissions and Kubernetes node authorization are different. An instance role can allow AWS API calls without allowing arbitrary Kubernetes actions, and kubelet authorization does not give the node's applications unrestricted AWS access.

Common node permission categories include EKS cluster discovery, pulling images from the configured container registry, Amazon VPC CNI networking operations, and log delivery when logging is enabled. Exact policies depend on the node type, networking, registry, and add-ons. Remove permissions unrelated to those responsibilities.

Workload credentials for AWS APIs

Applications should not rely on the node IAM role. If they do, every pod on that node may gain the same broad AWS permissions, and behavior can change when scheduling moves a pod to another node.

IRSA

IAM roles for service accounts (IRSA) uses the cluster's OIDC issuer. An IAM OIDC provider is associated with that issuer. A ServiceAccount contains the annotation eks.amazonaws.com/role-arn. EKS projects a web identity token into a pod, and the AWS SDK exchanges it with STS using AssumeRoleWithWebIdentity.

The role trust policy should restrict the issuer, audience, and subject. The subject commonly identifies one namespace and ServiceAccount, such as system:serviceaccount:team-a:app-sa. The identity policy should then grant only the required AWS actions and resources.

apiVersion: v1
kind: ServiceAccount
metadata:
  name: app-sa
  namespace: team-a
  annotations:
    eks.amazonaws.com/role-arn: arn:aws:iam::123456789012:role/TeamAAppRole

EKS Pod Identity

EKS Pod Identity uses a Pod Identity association between a cluster, namespace, ServiceAccount, and IAM role. The EKS Pod Identity Agent runs on nodes and delivers role credentials to matching pods. The role trust policy permits the EKS pods service principal under the intended conditions.

Install and run the agent when required by the cluster setup, create the association, and verify that the pod uses the expected ServiceAccount. Unlike IRSA, the association is managed through EKS rather than a ServiceAccount IAM-role annotation.

Both mechanisms depend on an AWS SDK that supports the default credential provider chain. Credentials are rotated and renewed; do not copy temporary credentials into application configuration. Kubernetes ServiceAccount tokens and AWS role credentials are related in these flows but are not interchangeable.

IAM policy layers and least privilege

An identity-based policy grants actions to an IAM user or role. A trust policy controls who may assume a role; it does not grant the role's service permissions. Permission boundaries cap the maximum permissions an identity can receive. Session policies further limit an assumed-role session. Service control policies (SCPs) impose organization-level limits. An explicit deny in an applicable policy overrides an allow.

Scope policies by AWS action, resource ARN, account, region, and conditions where supported. For Kubernetes access, scope by cluster, EKS access policy scope, namespace, resource, verb, group, and ServiceAccount or IAM group. Separate identities for people, automation, nodes, and applications make review and revocation safer.

CI/CD access

CI/CD systems should use OIDC federation to assume a dedicated AWS role instead of storing static AWS keys. The role trust policy should restrict the CI issuer and repository, project, branch, or workflow claims as appropriate.

A deployment role commonly needs permission to describe the target cluster, generate EKS authentication through the normal token flow, and use narrowly scoped Kubernetes permissions. It does not normally need cluster-admin access or permission to change IAM, networking, or unrelated clusters.

aws sts get-caller-identity
aws eks update-kubeconfig --region us-west-2 --name production --profile deployment-role
kubectl config current-context
kubectl auth can-i apply deployments --namespace team-a

Set the region and role explicitly in non-interactive jobs. Do not assume a developer's local profile, kubeconfig, or current context exists in the runner.

Credential security practices

• Do not commit AWS access keys, kubeconfig files containing sensitive configuration, bearer tokens, or Kubernetes Secrets to source control.
• Protect local kubeconfig files and CI/CD secret stores with operating-system and platform access controls.
• Prefer IAM Identity Center, federation, role assumption, and short-lived credentials over long-lived access keys.
• Use separate roles for operators, deployment automation, nodes, and applications.
• Rotate or revoke exposed credentials immediately, then investigate how they were exposed.
• Review AWS activity with CloudTrail and Kubernetes activity with Kubernetes audit logs where configured.
• Use narrow namespaces, ServiceAccounts, actions, and resource ARNs rather than unrestricted administrator policies.

Diagnosing EKS credential failures

A repeatable troubleshooting sequence

1. Confirm the region, account, cluster name, and current context.
2. Run aws configure list and aws sts get-caller-identity with the intended profile.
3. Refresh an expired IAM Identity Center session with aws sso login --profile PROFILE.
4. Verify cluster discovery with aws eks describe-cluster --name production --region us-west-2.
5. Inspect the effective kubeconfig using kubectl config view --minify; check the exec profile and role arguments.
6. For Unauthorized, inspect the cluster authentication mode, access entry, or legacy aws-auth mapping.
7. For Forbidden, run kubectl auth can-i for the exact verb, resource, and namespace, then inspect Roles and bindings.
8. For pod AccessDenied, verify the ServiceAccount, IRSA annotation or Pod Identity association, trust policy, audience, subject, agent, and SDK credential resolution.

Exam-relevant distinctions

• AWS authentication and Kubernetes authorization are separate decisions.
• An EKS token is generated from AWS credentials; it is not a permanent Kubernetes password.
• Unauthorized generally occurs before RBAC evaluation; Forbidden generally means the caller was authenticated but denied by authorization.
• A node IAM role is not a safe substitute for a pod workload role.
• IRSA uses an OIDC provider, a projected token, and AssumeRoleWithWebIdentity; EKS Pod Identity uses an association and the Pod Identity Agent.
• IAM role trust policies control assumption; identity-based policies control actions after assumption.
• Access entries and access policies are distinct from arbitrary Kubernetes RBAC objects, although they can provide or connect to Kubernetes permissions.

For related Kubernetes credential handling, see Kubernetes Secrets YAML.