EKS Access Entries - Eksctl User Guide

EKS Access Entries

You can use eksctl to manage EKS Access Entries. Use access entries to grant Kubernetes permissions to AWS IAM Identities. For example, you might grant a developer role permission to read Kubernetes resources in a cluster.

This topic covers how to use eksctl to manage access entries. For general information about access entries, see Grant IAM users access to Kubernetes with EKS access entries.

You can attach Kubernetes access policies defined by AWS, or assocoiate an IAM Identity with a Kubernetes group.

For more information about the available pre-defined policies, see Associate access policies with access entries.

If you need to define customer Kubernetes policies, associate the IAM Identity with a Kubernetes group, and grant permissions to that group.

Cluster authentication mode

You can only use access entries if the authentication mode of the cluster permits it.

For more information, see Set Cluster Authentication Mode

Set authentication mode with a YAML file

eksctl has added a new accessConfig.authenticationMode field under ClusterConfig, which can be set to one of the following three values:

  • CONFIG_MAP - default in EKS API - only aws-auth ConfigMap will be used

  • API - only access entries API will be used

  • API_AND_CONFIG_MAP - default in eksctl - both aws-auth ConfigMap and access entries API can be used

Set authentication mode in ClusterConfig YAML:

accessConfig: authenticationMode: <>

Update authentication mode with a command

If you want to use access entries on an already existing, non-eksctl created, cluster, where CONFIG_MAP option is used, the user will need to first set authenticationMode to API_AND_CONFIG_MAP. For that, eksctl has introduced a new command for updating the cluster authentication mode, which works both with CLI flags e.g.

eksctl utils update-authentication-mode --cluster my-cluster --authentication-mode API_AND_CONFIG_MAP

Access Entry Resources

Access entries have a type, such as STANDARD or EC2_LINUX. The type depends on how you are using the access entry.

  • The standard type is for granting Kubernetes permissions to IAM Users and IAM Roles.

    • For example, you can view Kubernetes resources in the AWS console by attaching an access policy to the Role or User you use to access the console.

  • The EC2_LINUX and EC2_WINDOWS types are for granting Kubernetes permissions to EC2 instances. Instances use these permissions to join the cluster.

For more information about the types of access entries, see Create access entries

IAM Entities

You can use access entries to grant Kubernetes permissions to IAM Identities such as IAM Users and IAM Roles.

Use the accessConfig.accessEntries field to associate the ARN of an IAM resource with a Access Entries EKS API. For example:

accessConfig: authenticationMode: API_AND_CONFIG_MAP accessEntries: - principalARN: arn:aws:iam::111122223333:user/my-user-name type: STANDARD kubernetesGroups: # optional Kubernetes groups - group1 # groups can used to give permissions via RBAC - group2 - principalARN: arn:aws:iam::111122223333:role/role-name-1 accessPolicies: # optional access polices - policyARN: arn:aws:eks::aws:cluster-access-policy/AmazonEKSViewPolicy accessScope: type: namespace namespaces: - default - my-namespace - dev-* - principalARN: arn:aws:iam::111122223333:role/admin-role accessPolicies: # optional access polices - policyARN: arn:aws:eks::aws:cluster-access-policy/AmazonEKSClusterAdminPolicy accessScope: type: cluster - principalARN: arn:aws:iam::111122223333:role/role-name-2 type: EC2_LINUX

In addition to associating EKS policies, one can also specify the Kubernetes groups to which an IAM entity belongs, thus granting permissions via RBAC.

Managed nodegroups and Fargate

The integration with access entries for these resources will be achieved behind the scenes, by the EKS API. Newly created managed node groups and Fargate pods will create API access entries, rather than using pre-loaded RBAC resources. Existing node groups and Fargate pods will not be changed, and continue to rely on the entries in the aws-auth config map.

Self-managed nodegroups

Each access entry has a type. For authorizing self-managed nodegroups, eksctl will create a unique access entry for each nodegroup with the principal ARN set to the node role ARN and type set to either EC2_LINUX or EC2_WINDOWS depending on nodegroup amiFamily.

When creating your own access entries, you can also 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, the default type is set to STANDARD.

Note

When deleting a nodegroup created with a pre-existing instanceRoleARN, it is the user’s responsibility to delete the corresponding access entry when no more nodegroups are associated with it. This is because eksctl does not attempt to find out if an access entry is still in use by non-eksctl created self-managed nodegroups as it is a complicated process.

Create access entry

This can be done in two different ways, either during cluster creation, specifying the desired access entries as part of the config file and running:

eksctl create cluster -f config.yaml

OR post cluster creation, by running:

eksctl create accessentry -f config.yaml

For an example config file for creating access entries, see 40-access-entries.yaml in the eksctl GitHub repo.

Get access entry

The user can retieve all access entries associated with a certain cluster by running one of the following:

eksctl get accessentry -f config.yaml

OR

eksctl get accessentry --cluster my-cluster

Alternatively, to retrieve only the access entry corresponding to a certain IAM entity one shall use the --principal-arn flag. e.g.

eksctl get accessentry --cluster my-cluster --principal-arn arn:aws:iam::111122223333:user/admin

Delete access entry

To delete a single access entry at a time use:

eksctl delete accessentry --cluster my-cluster --principal-arn arn:aws:iam::111122223333:user/admin

To delete multiple access entries, use the --config-file flag and specify all the principalARN’s corresponding with the access entries, under the top-level accessEntry field, e.g.

... accessEntry: - principalARN: arn:aws:iam::111122223333:user/my-user-name - principalARN: arn:aws:iam::111122223333:role/role-name-1 - principalARN: arn:aws:iam::111122223333:role/admin-role
eksctl delete accessentry -f config.yaml

Migrate from aws-auth ConfigMap

The user can migrate their existing IAM identities from aws-auth configmap to access entries by running the following:

eksctl utils migrate-to-access-entry --cluster my-cluster --target-authentication-mode <API or API_AND_CONFIG_MAP>

When --target-authentication-mode flag is set to API, authentication mode is switched to API mode (skipped if already in API mode), IAM identity mappings will be migrated to access entries, and aws-auth configmap is deleted from the cluster.

When --target-authentication-mode flag is set to API_AND_CONFIG_MAP, authentication mode is switched to API_AND_CONFIG_MAP mode (skipped if already in API_AND_CONFIG_MAP mode), IAM identity mappings will be migrated to access entries, but aws-auth configmap is preserved.

Note

When --target-authentication-mode flag is set to API, this command will not update authentication mode to API mode if aws-auth configmap has one of the below constraints.

  • There is an Account level identity mapping.

  • One or more Roles/Users are mapped to the kubernetes group(s) which begin with prefix system: (except for EKS specific groups i.e. system:masters, system:bootstrappers, system:nodes etc).

  • One or more IAM identity mapping(s) are for a [Service Linked Role](link:IAM/latest/UserGuide/using-service-linked-roles.html).

Disable cluster creator admin permissions

eksctl has added a new field accessConfig.bootstrapClusterCreatorAdminPermissions: boolean that, when set to false, disables granting cluster-admin permissions to the IAM identity creating the cluster. i.e.

add the option to the config file:

accessConfig:
  bootstrapClusterCreatorAdminPermissions: false

and run:

eksctl create cluster -f config.yaml