Authenticate cluster with AWS IAM Authenticator

AWS IAM Authenticator Support (optional)

EKS Anywhere supports configuring AWS IAM Authenticator as an authentication provider for clusters.

When you enable IAM Authenticator on a cluster, EKS Anywhere

• Installs aws-iam-authenticator server as a DaemonSet on the workload cluster.
• Configures the Kubernetes API Server to communicate with iam authenticator using a token authentication webhook .
• Creates the necessary ConfigMaps based on user options.

Create IAM Authenticator enabled cluster

Generate your cluster configuration and add the necessary IAM Authenticator configuration. For a full spec reference check AWSIamConfig .

Create an EKS Anywhere cluster as follows:

CLUSTER_NAME=my-cluster-name
eksctl anywhere create cluster -f ${CLUSTER_NAME}.yaml

Example AWSIamConfig configuration

This example uses a region in the default aws partition and EKSConfigMap as backendMode. Also, the IAM ARNs are mapped to the kubernetes system:masters group.

apiVersion: anywhere.eks.amazonaws.com/v1alpha1
kind: Cluster
metadata:
   name: my-cluster-name
spec:
   ...
   # IAM Authenticator
   identityProviderRefs:
      - kind: AWSIamConfig
        name: aws-iam-auth-config
---
apiVersion: anywhere.eks.amazonaws.com/v1alpha1
kind: AWSIamConfig
metadata:
   name: aws-iam-auth-config
spec:
    awsRegion: us-west-1
    backendMode:
        - EKSConfigMap
    mapRoles:
        - roleARN: arn:aws:iam::XXXXXXXXXXXX:role/myRole
          username: myKubernetesUsername
          groups:
          - system:masters
    mapUsers:
        - userARN: arn:aws:iam::XXXXXXXXXXXX:user/myUser
          username: myKubernetesUsername
          groups:
          - system:masters
    partition: aws

Authenticating with IAM Authenticator

After your cluster is created you may now use the mapped IAM ARNs to authenticate to the cluster.

EKS Anywhere generates a KUBECONFIG file in your local directory that uses aws-iam-authenticator client to authenticate with the cluster. The file can be found at

${PWD}/${CLUSTER_NAME}/${CLUSTER_NAME}-aws.kubeconfig

Steps

1. Ensure the IAM role/user ARN mapped in the cluster is configured on the local machine from which you are trying to access the cluster.

2. Install the aws-iam-authenticator client binary on the local machine.

   • We recommend installing the binary referenced in the latest release manifest of the kubernetes version used when creating the cluster.
   • The below commands can be used to fetch the installation uri for clusters created with 1.33 kubernetes version and OS linux.

   CLUSTER_NAME=my-cluster-name
   KUBERNETES_VERSION=1.33
   
   export KUBECONFIG=${PWD}/${CLUSTER_NAME}/${CLUSTER_NAME}-eks-a-cluster.kubeconfig
   
   EKS_D_MANIFEST_URL=$(kubectl get bundles $CLUSTER_NAME -o jsonpath="{.spec.versionsBundles[?(@.kubeVersion==\"$KUBERNETES_VERSION\")].eksD.manifestUrl}")
   
   OS=linux
   curl -fsSL $EKS_D_MANIFEST_URL | yq e '.status.components[] | select(.name=="aws-iam-authenticator") | .assets[] | select(.os == '"\"$OS\""' and .type == "Archive") | .archive.uri' -
   

3. Export the generated IAM Authenticator based KUBECONFIG file.

   export KUBECONFIG=${PWD}/${CLUSTER_NAME}/${CLUSTER_NAME}-aws.kubeconfig
   

4. Run kubectl commands to check cluster access. Example,

   kubectl get pods -A
   

Managing AWS IAM Authenticator

EKS Anywhere supports adding, removing, and modifying AWS IAM Authenticator configuration on existing clusters. These operations can be performed using the upgrade cluster command or GitOps.

Add AWS IAM Authenticator to existing cluster

You can add AWS IAM Authenticator to an existing cluster that was created without it.

1. Add the identityProviderRefs section to your cluster configuration and create the AWSIamConfig resource:

apiVersion: anywhere.eks.amazonaws.com/v1alpha1
kind: Cluster
metadata:
   name: my-cluster-name
spec:
   ...
   # Add IAM Authenticator to existing cluster
   identityProviderRefs:
      - kind: AWSIamConfig
        name: aws-iam-auth-config
---
apiVersion: anywhere.eks.amazonaws.com/v1alpha1
kind: AWSIamConfig
metadata:
   name: aws-iam-auth-config
spec:
    awsRegion: us-west-1
    backendMode:
        - EKSConfigMap
    mapRoles:
        - roleARN: arn:aws:iam::XXXXXXXXXXXX:role/myRole
          username: myKubernetesUsername
          groups:
          - system:masters
    mapUsers:
        - userARN: arn:aws:iam::XXXXXXXXXXXX:user/myUser
          username: myKubernetesUsername
          groups:
          - system:masters
    partition: aws

2. Run the upgrade command:

CLUSTER_NAME=my-cluster-name
eksctl anywhere upgrade cluster -f ${CLUSTER_NAME}.yaml

EKS Anywhere will:

• Install the aws-iam-authenticator server on the workload cluster
• Configure the Kubernetes API Server with the authentication webhook
• Create the necessary ConfigMaps
• Generate the AWS IAM-based kubeconfig file at ${PWD}/${CLUSTER_NAME}/${CLUSTER_NAME}-aws.kubeconfig

Remove AWS IAM Authenticator from cluster

You can remove AWS IAM Authenticator from a cluster that has it enabled.

1. Set identityProviderRefs to an empty array in your cluster configuration:

apiVersion: anywhere.eks.amazonaws.com/v1alpha1
kind: Cluster
metadata:
   name: my-cluster-name
spec:
   ...
   # Set to empty array to remove IAM Authenticator
   identityProviderRefs: []

2. Run the upgrade command:

CLUSTER_NAME=my-cluster-name
eksctl anywhere upgrade cluster -f ${CLUSTER_NAME}.yaml

EKS Anywhere will:

• Remove the aws-iam-authenticator server from the workload cluster
• Clean up the authentication webhook configuration
• Remove ConfigMaps and other related resources
• Clean up the AWS IAM-based kubeconfig file

Modify IAM Authenticator mappings

The mapRoles and mapUsers lists in AWSIamConfig can be modified when running the upgrade cluster command from EKS Anywhere.

As an example, let’s add another IAM user to the above example configuration.

apiVersion: anywhere.eks.amazonaws.com/v1alpha1
kind: AWSIamConfig
metadata:
   name: aws-iam-auth-config
spec:
    ...
    mapUsers:
        - userARN: arn:aws:iam::XXXXXXXXXXXX:user/myUser
          username: myKubernetesUsername
          groups:
          - system:masters
        - userARN: arn:aws:iam::XXXXXXXXXXXX:user/anotherUser
          username: anotherKubernetesUsername
    partition: aws

and then run the upgrade command

CLUSTER_NAME=my-cluster-name
eksctl anywhere upgrade cluster -f ${CLUSTER_NAME}.yaml

EKS Anywhere now updates the role mappings for IAM authenticator in the cluster and the new user gains access to the cluster.

GitOps

If the cluster has GitOps configured, then AWS IAM Authenticator can be added, removed, or modified by the GitOps controller. For GitOps configuration details refer to Manage Cluster with GitOps .

1. Clone your git repo and modify the cluster specification. The default path for the cluster file is:

   clusters/$CLUSTER_NAME/eksa-system/eksa-cluster.yaml
   

2. To add AWS IAM Authenticator: Add the identityProviderRefs section and AWSIamConfig resource to the cluster specification.

   To remove AWS IAM Authenticator: Set identityProviderRefs: [] (empty array) in the cluster specification.

   To modify mappings: Update the mapRoles and mapUsers lists in the AWSIamConfig object.

3. Commit the file to your git repository

   git add eksa-cluster.yaml
   git commit -m 'Update IAM Authenticator configuration'
   git push origin main
   

EKS Anywhere GitOps Controller will apply the changes to the cluster, adding, removing, or updating the IAM authenticator configuration as specified.