Configure Pods to use a Kubernetes service account

To configure a Pod to use a service account

1. Use the following command to create a deployment manifest that you can deploy a Pod to confirm configuration with. Replace the example values with your own values.

   cat >my-deployment.yaml <<EOF
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: my-app
   spec:
     selector:
       matchLabels:
         app: my-app
     template:
       metadata:
         labels:
           app: my-app
       spec:
         serviceAccountName: my-service-account
         containers:
         - name: my-app
           image: public.ecr.aws/nginx/nginx:X.XX
   EOF
   

2. Deploy the manifest to your cluster.

   kubectl apply -f my-deployment.yaml
   

3. Confirm that the required environment variables exist for your Pod.

   1. View the Pods that were deployed with the deployment in the previous step.

      kubectl get pods | grep my-app
      

      An example output is as follows.

      my-app-6f4dfff6cb-76cv9   1/1     Running   0          3m28s

   2. View the ARN of the IAM role that the Pod is using.

      kubectl describe pod my-app-6f4dfff6cb-76cv9 | grep AWS_ROLE_ARN:
      

      An example output is as follows.

      AWS_ROLE_ARN:                 arn:aws:iam::111122223333:role/my-role

      The role ARN must match the role ARN that you annotated the existing service account with. For more about annotating the service account, see Configure a Kubernetes service account to assume an IAM role.

   3. Confirm that the Pod has a web identity token file mount.

      kubectl describe pod my-app-6f4dfff6cb-76cv9 | grep AWS_WEB_IDENTITY_TOKEN_FILE:
      

      An example output is as follows.

      AWS_WEB_IDENTITY_TOKEN_FILE:  /var/run/secrets/eks.amazonaws.com/serviceaccount/token

      The kubelet requests and stores the token on behalf of the Pod. By default, the kubelet refreshes the token if the token is older than 80 percent of its total time to live or older than 24 hours. You can modify the expiration duration for any account other than the default service account by using the settings in your Pod spec. For more information, see Service Account Token Volume Projection in the Kubernetes documentation.

      The Amazon EKS Pod Identity Webhook on the cluster watches for Pods that use a service account with the following annotation:

      eks.amazonaws.com/role-arn: arn:aws:iam::111122223333:role/my-role

      The webhook applies the previous environment variables to those Pods. Your cluster doesn't need to use the webhook to configure the environment variables and token file mounts. You can manually configure Pods to have these environment variables. The supported versions of the AWS SDK look for these environment variables first in the credential chain provider. The role credentials are used for Pods that meet this criteria.

4. Confirm that your Pods can interact with the AWS services using the permissions that you assigned in the IAM policy attached to your role.

   Note

   When a Pod uses AWS credentials from an IAM role that's associated with a service account, the AWS CLI or other SDKs in the containers for that Pod use the credentials that are provided by that role. If you don't restrict access to the credentials that are provided to the Amazon EKS node IAM role, the Pod still has access to these credentials. For more information, see Restrict access to the instance profile assigned to the worker node.

   If your Pods can't interact with the services as you expected, complete the following steps to confirm that everything is properly configured.

   1. Confirm that your Pods use an AWS SDK version that supports assuming an IAM role through an OpenID Connect web identity token file. For more information, see Using a supported AWS SDK.

   2. Confirm that the deployment is using the service account.

      kubectl describe deployment my-app | grep "Service Account"
      

      An example output is as follows.

      Service Account:  my-service-account

   3. If your Pods still can't access services, review the steps that are described in Configure a Kubernetes service account to assume an IAM role to confirm that your role and service account are configured properly.