Create access entries

Considerations

Before creating access entries, consider the following:

• A properly set authentication mode. See Change authentication mode to use access entries.

• An access entry includes the Amazon Resource Name (ARN) of one, and only one, existing IAM principal. An IAM principal can't be included in more than one access entry. Additional considerations for the ARN that you specify:

  • IAM best practices recommend accessing your cluster using IAM roles that have short-term credentials, rather than IAM users that have long-term credentials. For more information, see Require human users to use federation with an identity provider to access AWS using temporary credentials in the IAM User Guide.

  • If the ARN is for an IAM role, it can include a path. ARNs in aws-auth ConfigMap entries, can't include a path. For example, your ARN can be arn:aws:iam::111122223333:role/development/apps/my-role or arn:aws:iam::111122223333:role/my-role.

  • If the type of the access entry is anything other than STANDARD (see next consideration about types), the ARN must be in the same AWS account that your cluster is in. If the type is STANDARD, the ARN can be in the same, or different, AWS account than the account that your cluster is in.

  • You can't change the IAM principal after the access entry is created.

  • If you ever delete the IAM principal with this ARN, the access entry isn't automatically deleted. We recommend that you delete the access entry with an ARN for an IAM principal that you delete. If you don't delete the access entry and ever recreate the IAM principal, even if it has the same ARN, the access entry won't work. This is because even though the ARN is the same for the recreated IAM principal, the roleID or userID (you can see this with the aws sts get-caller-identity AWS CLI command) is different for the recreated IAM principal than it was for the original IAM principal. Even though you don't see the IAM principal's roleID or userID for an access entry, Amazon EKS stores it with the access entry.

• Each access entry has a type. You can specify EC2 Linux (for an IAM role used with Linux or Bottlerocket self-managed nodes), EC2 Windows (for an IAM roles used with Windows self-managed nodes), FARGATE_LINUX (for an IAM roles used with AWS Fargate (Fargate)), or STANDARD as a type. If you don't specify a type, Amazon EKS automatically sets the type to STANDARD. It's unnecessary to create an access entry for an IAM role that's used for a managed node group or a Fargate profile, because Amazon EKS adds entries for these roles to the aws-auth ConfigMap, regardless of which platform version your cluster is at.

  You can't change the type after the access entry is created.

• If the type of the access entry is STANDARD, you can specify a username for the access entry. If you don't specify a value for username, Amazon EKS sets one of the following values for you, depending on the type of the access entry and whether the IAM principal that you specified is an IAM role or IAM user. Unless you have a specific reason for specifying your own username, we recommend that don't specify one and let Amazon EKS auto-generate it for you. If you specify your own username:

  • It can't start with system:, eks:, aws:, amazon:, or iam:.

  • If the username is for an IAM role, we recommend that you add {{SessionName}} to the end of your username. If you add {{SessionName}} to your username, the username must include a colon before {{SessionName}}. When this role is assumed, the name of the session specified when assuming the role is automatically passed to the cluster and will appear in CloudTrail logs. For example, you can't have a username of john{{SessionName}}. The username would have to be :john{{SessionName}} or jo:hn{{SessionName}}. The colon only has to be before {{SessionName}}. The username generated by Amazon EKS in the following table includes an ARN. Since an ARN includes colons, it meets this requirement. The colon isn't required if you don't include {{SessionName}} in your username.

  IAM principal type	Type	Username value that Amazon EKS automatically sets
  User	STANDARD	The ARN of the user. Example: arn:aws:iam::111122223333:user/my-user
  Role	STANDARD	The STS ARN of the role when it's assumed. Amazon EKS appends {{SessionName}} to the role. Example: arn:aws:sts::111122223333:assumed-role/my-role/{{SessionName}} If the ARN of the role that you specified contained a path, Amazon EKS removes it in the generated username.
  Role	EC2 Linux or EC2 Windows	system:node:{{EC2PrivateDNSName}}
  Role	FARGATE_LINUX	system:node:{{SessionName}}

  You can change the username after the access entry is created.

• If an access entry's type is STANDARD, and you want to use Kubernetes RBAC authorization, you can add one or more group names to the access entry. After you create an access entry you can add and remove group names. For the IAM principal to have access to Kubernetes objects on your cluster, you must create and manage Kubernetes role-based authorization (RBAC) objects. Create Kubernetes RoleBinding or ClusterRoleBinding objects on your cluster that specify the group name as a subject for kind: Group. Kubernetes authorizes the IAM principal access to any cluster objects that you've specified in a Kubernetes Role or ClusterRole object that you've also specified in your binding's roleRef. If you specify group names, we recommend that you're familiar with the Kubernetes role-based authorization (RBAC) objects. For more information, see Using RBAC Authorization in the Kubernetes documentation.

  Important

  Amazon EKS doesn't confirm that any Kubernetes RBAC objects that exist on your cluster include any of the group names that you specify.

  Instead of, or in addition to, Kubernetes authorizing the IAM principal access to Kubernetes objects on your cluster, you can associate Amazon EKS access policies to an access entry. Amazon EKS authorizes IAM principals to access Kubernetes objects on your cluster with the permissions in the access policy. You can scope an access policy's permissions to Kubernetes namespaces that you specify. Use of access policies don't require you to manage Kubernetes RBAC objects. For more information, see Associate access policies with access entries.

• If you create an access entry with type EC2 Linux or EC2 Windows, the IAM principal creating the access entry must have the iam:PassRole permission. For more information, see Granting a user permissions to pass a role to an AWS service in the IAM User Guide.

• Similar to standard IAM behavior, access entry creation and updates are eventually consistent, and may take several seconds to be effective after the initial API call returns successfully. You must design your applications to account for these potential delays. We recommend that you don't include access entry creates or updates in the critical, high- availability code paths of your application. Instead, make changes in a separate initialization or setup routine that you run less frequently. Also, be sure to verify that the changes have been propagated before production workflows depend on them.

• Access entries do not support service linked roles. You cannot create access entries where the principal ARN is a service linked role. You can identify service linked roles by their ARN, which is in the format arn:aws:iam::*:role/aws-service-role/*.

You can create an access entry using the AWS Management Console or the AWS CLI.

AWS Management Console

To create an access entry

1. Open the Amazon EKS console at https://console.aws.amazon.com/eks/home#/clusters.

2. Choose the name of the cluster that you want to create an access entry in.

3. Choose the Access tab.

4. Choose Create access entry.

5. For IAM principal, select an existing IAM role or user. IAM best practices recommend accessing your cluster using IAM roles that have short-term credentials, rather than IAM users that have long-term credentials. For more information, see Require human users to use federation with an identity provider to access AWS using temporary credentials in the IAM User Guide.

6. For Type, if the access entry is for the node role used for self-managed Amazon EC2 nodes, select EC2 Linux or EC2 Windows. Otherwise, accept the default (Standard).

7. If the Type you chose is Standard and you want to specify a Username, enter the username.

8. If the Type you chose is Standard and you want to use Kubernetes RBAC authorization for the IAM principal, specify one or more names for Groups. If you don't specify any group names and want to use Amazon EKS authorization, you can associate an access policy in a later step, or after the access entry is created.

9. (Optional) For Tags, assign labels to the access entry. For example, to make it easier to find all resources with the same tag.

10. Choose Next.

11. On the Add access policy page, if the type you chose was Standard and you want Amazon EKS to authorize the IAM principal to have permissions to the Kubernetes objects on your cluster, complete the following steps. Otherwise, choose Next.

    1. For Policy name, choose an access policy. You can't view the permissions of the access policies, but they include similar permissions to those in the Kubernetes user-facing ClusterRole objects. For more information, see User-facing roles in the Kubernetes documentation.

    2. Choose one of the following options:

       • Cluster – Choose this option if you want Amazon EKS to authorize the IAM principal to have the permissions in the access policy for all Kubernetes objects on your cluster.

       • Kubernetes namespace – Choose this option if you want Amazon EKS to authorize the IAM principal to have the permissions in the access policy for all Kubernetes objects in a specific Kubernetes namespace on your cluster. For Namespace, enter the name of the Kubernetes namespace on your cluster. If you want to add additional namespaces, choose Add new namespace and enter the namespace name.

    3. If you want to add additional policies, choose Add policy. You can scope each policy differently, but you can add each policy only once.

    4. Choose Next.

12. Review the configuration for your access entry. If anything looks incorrect, choose Previous to go back through the steps and correct the error. If the configuration is correct, choose Create.

AWS CLI

Prerequisite

Install the AWS CLI, as described in Installing, updating, and uninstalling the AWS CLI in the AWS Command Line Interface User Guide.

To create an access entry

You can use any of the following examples to create access entries:

• Create an access entry for a self-managed Amazon EC2 Linux node group. Replace my-cluster with the name of your cluster, 111122223333 with your AWS account ID, and EKS-my-cluster-self-managed-ng-1 with the name of your node IAM role. If your node group is a Windows node group, then replace EC2_Linux with EC2_Windows.

  aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/EKS-my-cluster-self-managed-ng-1 --type EC2_Linux
  

  You can't use the --kubernetes-groups option when you specify a type other than STANDARD. You can't associate an access policy to this access entry, because its type is a value other than STANDARD.

• Create an access entry that allows an IAM role that's not used for an Amazon EC2 self-managed node group, that you want Kubernetes to authorize access to your cluster with. Replace my-cluster with the name of your cluster, 111122223333 with your AWS account ID, and my-role with the name of your IAM role. Replace Viewers with the name of a group that you've specified in a Kubernetes RoleBinding or ClusterRoleBinding object on your cluster.

  aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:role/my-role --type STANDARD --user Viewers --kubernetes-groups Viewers
  

• Create an access entry that allows an IAM user to authenticate to your cluster. This example is provided because this is possible, though IAM best practices recommend accessing your cluster using IAM roles that have short-term credentials, rather than IAM users that have long-term credentials. For more information, see Require human users to use federation with an identity provider to access AWS using temporary credentials in the IAM User Guide.

  aws eks create-access-entry --cluster-name my-cluster --principal-arn arn:aws:iam::111122223333:user/my-user --type STANDARD --username my-user
  

  If you want this user to have more access to your cluster than the permissions in the Kubernetes API discovery roles, then you need to associate an access policy to the access entry, since the --kubernetes-groups option isn't used. For more information, see Associate access policies with access entries and API discovery roles in the Kubernetes documentation.