# Amazon EKS access entry authentication Amazon EKS supports two mechanisms for granting an IAM principal permission to call the cluster's Kubernetes API: the legacy `aws-auth` ConfigMap and the newer [access entry API](https://docs.amazonaws.cn/eks/latest/userguide/access-entries.html). An access entry grants Kubernetes API access to an IAM principal without requiring you to edit a ConfigMap. Amazon Batch can authenticate to your cluster through either mechanism. When you set `eksConfiguration.accessEntry.desiredState` to `ENABLED` on a compute environment, Amazon Batch can manage the access entry for that compute environment on the cluster. You no longer need to manually edit the `aws-auth` ConfigMap. Whether Amazon Batch provisions an access entry depends on your Amazon Batch compute environment and your Amazon EKS cluster configuration. See [Interaction with the cluster's `authenticationMode`](#eks-access-entries-matrix) for details. ## Values for `accessEntry.desiredState` The `desiredState` field on `EksAccessEntry` declares the desired access entry state for the compute environment. Valid values are: `ENABLED` Amazon Batch creates an Amazon Batch-managed access entry on the cluster for the compute environment. Amazon Batch will only create an Amazon Batch-managed access entry if all compute environments on the cluster have set `desiredState` to `ENABLED` (see [How Amazon Batch reconciles `desiredState` across compute environments](#eks-access-entries-reconciliation) for details). `DISABLED` Amazon Batch deletes the Amazon Batch-managed access entry for the cluster. Amazon Batch will only delete an Amazon Batch-managed access entry if all compute environments on the cluster have set `desiredState` to `DISABLED` (see [How Amazon Batch reconciles `desiredState` across compute environments](#eks-access-entries-reconciliation) for details). Access to the cluster must be configured through the `aws-auth` ConfigMap. `INHERIT_FROM_CLUSTER` Amazon Batch defers to the cluster's current access entry `status`. On an Amazon EKS cluster whose authentication mode is `API`, Amazon Batch creates and manages an access entry because the cluster has no `aws-auth` ConfigMap to fall back to. On a cluster whose authentication mode is `CONFIG_MAP` or `API_AND_CONFIG_MAP`, Amazon Batch neither adds nor removes an access entry. The compute environment also exposes a read-only `accessEntry.status` field in [DescribeComputeEnvironments](https://docs.amazonaws.cn/batch/latest/APIReference/API_DescribeComputeEnvironments.html) responses. `ACTIVE` means that an Amazon Batch-managed access entry for the compute environment exists on the cluster and takes precedence over the `aws-auth` ConfigMap. `INACTIVE` means that no Amazon Batch-managed access entry is present. This can be because `desiredState` is `DISABLED`, because the compute environments targeting the cluster don't yet agree on `desiredState`, or because the entry hasn't been provisioned yet. If `accessEntry.status` is `INACTIVE`, Batch uses `aws-auth` ConfigMap for cluster access. **Note** An access entry reports `ACTIVE` as soon as it exists on the cluster, even if Amazon Batch hasn't finished associating the access policy that makes it usable. If the compute environment status changes to `INVALID` while `accessEntry.status` is `ACTIVE`, see [Amazon EKS access entry setup is incomplete](batch_eks_invalid_compute_environment.md#batch_eks_access_entry_incomplete). **Note** If you omit the `accessEntry` field, Amazon Batch doesn't record a `desiredState` for the compute environment, and `DescribeComputeEnvironments` doesn't return one. For the purpose of provisioning the access entry, Amazon Batch behaves as it does for `INHERIT_FROM_CLUSTER`. ## Interaction with the cluster's `authenticationMode` How Amazon Batch behaves for a given `desiredState` depends on the cluster's authentication mode. The following table applies to both `CreateComputeEnvironment` and `UpdateComputeEnvironment`.
Cluster authenticationModeCompute environment accessEntry.desiredState=ENABLEDCompute environment accessEntry.desiredState=DISABLEDCompute environment accessEntry.desiredState=INHERIT_FROM_CLUSTER
CONFIG_MAPAccess entries aren't available on the cluster, so Amazon Batch doesn't create or remove one. Amazon Batch still records the value that you specify. After you change the cluster's authentication mode, that recorded value takes effect on your next CreateComputeEnvironment or UpdateComputeEnvironment call that specifies desiredState.
API_AND_CONFIG_MAPAmazon Batch compares the recorded values across the compute environments that share the cluster — see How Amazon Batch reconciles `desiredState` across compute environments.Existing access mode is retained. Amazon Batch does not add or remove an access entry.
APIAccess entry is created and maintained on the cluster.The request is rejected. A cluster in this mode doesn't support the aws-auth ConfigMap, and the ConfigMap method can't be enabled after cluster creation, so DISABLED would leave the compute environment with no way to authenticate.Access entry is created and maintained on the cluster. When the cluster is API-only, inheriting is equivalent to ENABLED.
## How Amazon Batch reconciles `desiredState` across compute environments Because a single Amazon EKS cluster can back multiple Amazon Batch compute environments, a cluster's access configuration is a shared resource. Amazon Batch therefore reconciles, or compares and resolves, the `desiredState` values recorded across those compute environments. When the cluster's `authenticationMode` is `API_AND_CONFIG_MAP`, Amazon Batch compares the `desiredState` recorded for every compute environment in the same Amazon account and Amazon Region that targets the cluster. Amazon Batch uses this comparison to determine whether to add or remove the access entry on each `CreateComputeEnvironment` or `UpdateComputeEnvironment` operation that specifies `desiredState`. Every compute environment has `desiredState=ENABLED` Amazon Batch creates the access entry on the cluster. Every compute environment has `desiredState=DISABLED` Amazon Batch deletes the access entry from the cluster if one exists. The recorded `desiredState` values don't all match Amazon Batch retains the existing access mode. The access entry is neither added nor removed. This includes any mix of `ENABLED`, `DISABLED`, and `INHERIT_FROM_CLUSTER`, and it also includes any compute environment that has no `desiredState` recorded. **Note** To transition a cluster whose authentication mode is `API_AND_CONFIG_MAP` from `aws-auth` ConfigMap to access entry authentication, set `desiredState=ENABLED` on every Amazon Batch compute environment that targets the cluster. To transition back, set `desiredState=DISABLED` on every one of them. ## What Amazon Batch creates on your cluster Amazon Batch creates one access entry per cluster that meets the above conditions, then associates the `AWSBatchClusterPolicy` Amazon EKS access policy with that access entry. The access entry is per cluster rather than per compute environment, so all Amazon Batch compute environments that target the same cluster share it. **Note** Deleting a compute environment doesn't remove the access entry, even if it's the last Amazon Batch compute environment on the cluster. To remove an Amazon Batch-managed access entry, call `UpdateComputeEnvironment` with `desiredState=DISABLED` on every Amazon Batch compute environment that targets the cluster before you delete them. An access entry isn't sufficient on its own to run jobs on the cluster. For the Kubernetes permissions and node access that you must configure yourself, see [Cluster configuration that you must still provide](#eks-access-entries-additional-configuration). ## Required permissions Amazon Batch manages the access entry using the credentials of the IAM identity that calls the `CreateComputeEnvironment` or `UpdateComputeEnvironment` operation. That identity must be allowed to perform the following Amazon EKS actions: + `eks:DescribeCluster` + `eks:DescribeAccessEntry` + `eks:CreateAccessEntry` + `eks:AssociateAccessPolicy` + `eks:DeleteAccessEntry` ## Configure the access entry You can configure the access entry on a compute environment through the `eksConfiguration.accessEntry` field of the [CreateComputeEnvironment](https://docs.amazonaws.cn/batch/latest/APIReference/API_CreateComputeEnvironment.html) or [UpdateComputeEnvironment](https://docs.amazonaws.cn/batch/latest/APIReference/API_UpdateComputeEnvironment.html) API. ------ #### [ Amazon CLI ] **Enable an Amazon Batch-managed access entry when creating a compute environment** ``` $ aws batch create-compute-environment \ --compute-environment-name {{my-eks-ce}} \ --type MANAGED \ --eks-configuration 'eksClusterArn={{arn:aws:eks:us-east-1:123456789012:cluster/my-cluster}},kubernetesNamespace={{my-aws-batch-namespace}},accessEntry={desiredState=ENABLED}' \ --compute-resources 'type=EC2,maxvCpus=128,subnets={{subnet-a123456b}},securityGroupIds={{sg-a12b3456}},instanceRole={{arn:aws:iam::123456789012:instance-profile/my-node-instance-profile}}' ``` **Enable an Amazon Batch-managed access entry on an existing compute environment** ``` $ aws batch update-compute-environment \ --compute-environment {{my-eks-ce}} \ --eks-configuration 'accessEntry={desiredState=ENABLED}' ``` **Check the status** ``` $ aws batch describe-compute-environments \ --compute-environments {{my-eks-ce}} \ --query "computeEnvironments[0].eksConfiguration.accessEntry" ``` The response includes both the `desiredState` that you specified and the observed `status`: ``` { "desiredState": "ENABLED", "status": "ACTIVE" } ``` **Note** Amazon Batch returns `accessEntry.status` for all Amazon EKS compute environments, and returns `desiredState` only if you have set it. A compute environment where you never specified `accessEntry` returns `status` alone. To stop Amazon Batch from managing the access entry, set `desiredState` to `DISABLED` instead. Before you do, review [Interaction with the cluster's `authenticationMode`](#eks-access-entries-matrix): `DISABLED` is rejected on a cluster whose authentication mode is `API`, and on a cluster whose authentication mode is `API_AND_CONFIG_MAP` the access entry is removed only after every Amazon Batch compute environment that targets the cluster is set to `DISABLED`. ------ #### [ API ] Use the `eksConfiguration.accessEntry` object in your [CreateComputeEnvironment](https://docs.amazonaws.cn/batch/latest/APIReference/API_CreateComputeEnvironment.html) or [UpdateComputeEnvironment](https://docs.amazonaws.cn/batch/latest/APIReference/API_UpdateComputeEnvironment.html) request. **Create a compute environment with an Amazon Batch-managed access entry** Include `accessEntry` in the request body: ``` { "computeEnvironmentName": "{{my-eks-ce}}", "type": "MANAGED", "state": "ENABLED", "eksConfiguration": { "eksClusterArn": "{{arn:aws:eks:us-east-1:123456789012:cluster/my-cluster}}", "kubernetesNamespace": "{{my-aws-batch-namespace}}", "accessEntry": { "desiredState": "ENABLED" } }, "computeResources": { "type": "EC2", "maxvCpus": 128, "subnets": ["{{subnet-a123456b}}"], "securityGroupIds": ["{{sg-a12b3456}}"], "instanceRole": "{{arn:aws:iam::123456789012:instance-profile/my-node-instance-profile}}" } } ``` **Update the access entry on an existing compute environment** ``` { "computeEnvironment": "{{my-eks-ce}}", "eksConfiguration": { "accessEntry": { "desiredState": "ENABLED" } } } ``` For more information, see [`EksAccessEntry`](https://docs.amazonaws.cn/batch/latest/APIReference/API_EksAccessEntry.html), [CreateComputeEnvironment](https://docs.amazonaws.cn/batch/latest/APIReference/API_CreateComputeEnvironment.html), and [UpdateComputeEnvironment](https://docs.amazonaws.cn/batch/latest/APIReference/API_UpdateComputeEnvironment.html) in the *Amazon Batch API Reference*. ------ ## Cluster configuration that you must still provide An access entry controls only how Amazon Batch authenticates to your cluster. It doesn't grant Amazon Batch the Kubernetes permissions that it needs to run your jobs, and it doesn't let the instances that Amazon Batch launches join the cluster. Regardless of which authentication mechanism you use, you must still configure both of the following. **Important** Once an Amazon Batch-managed access entry is created for the Amazon Batch service-linked role on a cluster (`accessEntry.status=ACTIVE`), it takes precedence over the `aws-auth` ConfigMap configuration for the role. The ConfigMap entries for the Amazon Batch service-linked role are unused, and Amazon Batch authenticates using the access entry instead. To return to ConfigMap authentication, set `desiredState=DISABLED` on all compute environments that target the cluster. This removes the Amazon Batch-managed access entry. Kubernetes permissions for the Amazon Batch namespace Amazon Batch needs Kubernetes permissions to create and manage pods in the namespace that you specify in `eksConfiguration.kubernetesNamespace`. Create the namespace, then configure those permissions using one of the following methods depending on your authentication approach: + **Access policy association (required when access entry `status=ACTIVE`)** — When you set `desiredState=ENABLED` on all compute environments targeting a cluster, Amazon Batch creates an access entry with the cluster-level `AWSBatchClusterPolicy`. You must then associate the namespace-scoped `AWSBatchNamespacePolicy` to grant Amazon Batch permission to create and manage pods. After the access entry reaches `status=ACTIVE`, associate the namespace policy using the Amazon CLI: ``` $ aws eks associate-access-policy \ --cluster-name {{my-cluster}} \ --principal-arn {{arn:aws:iam::123456789012:role/aws-service-role/batch.amazonaws.com/AWSServiceRoleForBatch}} \ --policy-arn arn:aws:eks::aws:cluster-access-policy/AWSBatchNamespacePolicy \ --access-scope type=namespace,namespaces={{my-aws-batch-namespace}} ``` Replace {{my-aws-batch-namespace}} with the value you specified in `eksConfiguration.kubernetesNamespace`. **Important** Without the namespace-scoped policy association, jobs will remain stuck in `RUNNABLE` status. The cluster-level policy alone does not grant pod management permissions. + **Kubernetes roles and role bindings (when access entry `status=INACTIVE`)** — If the Amazon Batch-managed access entry is not active, create the Kubernetes roles and role bindings that grant those permissions, as described in [Step 2: Prepare your Amazon EKS cluster for Amazon Batch](getting-started-eks-configmap.md#getting-started-eks-configmap-step-1). You do this once for each cluster. **Note** When an Amazon Batch-managed access entry is active (`status=ACTIVE`), the Kubernetes RBAC roles are bypassed. You must use the access policy association method instead. Amazon Batch doesn't create these resources for you, and an Amazon Batch-managed access entry doesn't substitute for them. If they're missing, the compute environment can still become `VALID` while your jobs fail to start. Cluster access for the node instance role Instances that Amazon Batch launches join the cluster using the instance profile that you specify in `computeResources.instanceRole`. That role needs its own access to the cluster, which is separate from the Amazon Batch-managed access entry and which Amazon Batch doesn't configure. The configuration method depends on your cluster's `authenticationMode`: + **On clusters whose `authenticationMode` is `CONFIG_MAP`** — You must use the `aws-auth` ConfigMap. Access entries are not supported on these clusters. + **On clusters whose `authenticationMode` is `API_AND_CONFIG_MAP`** — The node instance role can authenticate using either the `aws-auth` ConfigMap or an access entry. If the instance role is already mapped in the ConfigMap, nodes will join successfully without creating an access entry for the role. + **On clusters whose `authenticationMode` is `API`** — You must create an access entry for the node instance role. The `aws-auth` ConfigMap is not used for authentication on these clusters. To create an access entry for the node instance role, use the Amazon CLI: ``` $ aws eks create-access-entry \ --cluster-name {{my-cluster}} \ --principal-arn {{arn:aws:iam::123456789012:role/my-node-instance-role}} \ --type EC2_LINUX ``` For more information, see [Creating access entries](https://docs.amazonaws.cn/eks/latest/userguide/creating-access-entries.html) in the **Amazon EKS User Guide**. Without proper cluster access for the node instance role, EC2 instances cannot join the cluster. Jobs will remain in the `RUNNABLE` state because no capacity registers with the cluster. ## Choosing between the `aws-auth` ConfigMap and access entries Access entry authentication is the recommended path for new Amazon Batch on Amazon EKS compute environments, and it offers the following advantages: + Eliminates the need to manually edit the `aws-auth` ConfigMap to grant Amazon Batch access to the cluster. + Provides an auditable, API-driven record of the principals that have access to the cluster. + Is required for clusters whose `authenticationMode` is `API`, which do not support the `aws-auth` ConfigMap. If your cluster's `authenticationMode` is `CONFIG_MAP`, access entries aren't available and Amazon Batch authenticates through the `aws-auth` ConfigMap. For instructions, see [Verify that the `aws-auth ConfigMap` is configured correctly](verify-configmap-config.md).