How do I troubleshoot issues with access entries in my Amazon EKS cluster?

Resolution

Prerequisite: Your Amazon EKS cluster runs on Kubernetes version 1.23 or later.

Note: If you receive errors when you run AWS Command Line Interface (AWS CLI) commands, then see Troubleshooting errors for the AWS CLI. Also, make sure that you're using the most recent AWS CLI version.

Authentication mode errors

You receive the following error messages when you modify the authentication mode of a cluster:

• "An error occurred (InvalidParameterException) when calling the UpdateClusterConfig operation: Unsupported authentication mode update from API_AND_CONFIG_MAP to CONFIG_MAP."
• "An error occurred (InvalidParameterException) when calling the UpdateClusterConfig operation: Unsupported authentication mode update from API to CONFIG_MAP."
• "An error occurred (InvalidParameterException) when calling the UpdateClusterConfig operation: Unsupported authentication mode update from API to API_AND_CONFIG_MAP."

When you set the authentication mode, you can't reverse the operation. For example, after you change the mode to API, you can't return to CONFIG_MAP or API_AND_CONFIG_MAP. For more information, see A deep dive into simplified Amazon EKS access management controls.

To prevent authentication mode errors, use access entries instead of the aws-auth ConfigMap.

AccessDeniedException error

You receive an error message when the AWS Identity and Access Management (IAM) principal doesn't have sufficient permissions to use access entries. The error message is similar to the following one:

"An error occurred (AccessDeniedException) when calling the CreateAccessEntry operation: User: [principalARN] is not authorized to perform: eks:CreateAccessEntry on resource: arn:aws:eks:us-east-1:000000000:cluster/your-eks-cluster."

To resolve this issue, add the following permissions to the IAM policy of the IAM principal that's making the request:

• CreateAccessEntry
• ListAccessEntries
• DescribeAccessEntry
• DeleteAccessEntry
• UpdateAccessEntry

CONFIG_MAP to API_AND_CONFIG_MAP migration or update issues

The following notification appears when you migrate or update your access entries from CONFIG_MAP to API_AND_CONFIG_MAP:

"The mapping of the node IAM role defined in the existing ConfigMap/AWS-Auth was automatically added as an access entry. However, in aws-auth, this role is defined as two system:nodes/system:bootstrappers group, but at the access entry side it only has system:nodes/."

There's no error that you must troubleshoot because the migration process maps your node IAM roles to the system:nodes group by default.

After you migrate your access entries, you no longer need the aws-auth ConfigMap or IAM access entry configurations that the system:bootstrappers group grants. Your nodes can perform all operations with the permissions that the system:nodes group grants. The system:nodes group confirms that the CONFIG_MAP to API_AND_CONFIG_MAP migration removed unnecessary groups from access entry.

Type errors

The following error occurs when you don't set an IAM role as your destination IAM principal for the access entry:

"AccessEntry principalArn must be IAM role when using types [EC2_LINUX, EC2_WINDOWS, FARGATE_LINUX]."

To resolve this issue, use one of the following access entry types:

• EC2_LINUX
• EC2_WINDOWS
• FARGATE_LINUX

For more information about access entry types, see Create access entries.

Username errors

If you provide an incorrect username when you create an access entry, then you receive the following error message:

"The username must not begin with [eks:, aws:, system:, amazon:, iam:]."

If you specify your own username, then you can't start the username with the following prefixes:

• eks:
• aws:
• system:
• amazon:
• iam:

To resolve this issue, make sure that your username adheres to the username requirements for access entries. For more information about the username requirements, see Create access entries.

Note: To prevent potential errors, it's a best practice to let Amazon EKS automatically generate a username for you.

Permissions errors

You get permissions errors because Amazon EKS doesn't confirm that Kubernetes role-based access control (RBAC) objects on your cluster include your specified group names. Amazon EKS doesn't verify that the group names that you specify exist in bindings on your cluster.

To resolve this issue, take the following actions:

• Verify that your aws-auth ConfigMap or IAM access entries successfully create the groups that you specified as subjects in Kubernetes RoleBinding or ClusterRoleBinding.
• Check whether the spelling and formatting is correct for references to a Kubernetes group in your access entry.

Service-linked role errors

If you specify a service-linked role when you create an access entry, then you receive the following error message:

"The caller is not allowed to modify access entries with a principalArn value of a Service Linked Role."

Access entries don't support service-linked roles. So, you can't create access entries when the principal Amazon Resource Name (ARN) is a service-linked role. You can identify service-linked roles by their ARN. For example, the arn:aws:iam::*:role/aws-service-role/* ARN is for a service-linked role.

To grant service-linked roles access to your cluster, use the CONFIG_MAP or API_AND_CONFIG_MAP authentication mode to specify the service-linked role in the aws-auth ConfigMap.

Related information

Grant IAM users access to Kubernetes with a ConfigMap