How to Use an IAM Role Assigned to a Kubernetes Service Account in AWS with Hybrid Deployment

Question

How do I use an IAM role assigned to a Kubernetes service account in AWS with Hybrid Deployment?

Environment

Container platform: Kubernetes

Answer

To use an IAM role assigned to a Kubernetes service account in AWS with Hybrid Deployment, follow the steps below. For more information, see the AWS documentation for IAM roles for service accounts (IRSA).

Create IAM policy

Depending on which AWS services you need to access, create one or more IAM policies that define the necessary permissions. Multiple IAM policies can be attached to a single IAM role.

For example, to access an S3 bucket:

1. Create an S3 bucket.

2. Define an IAM policy s3-policy.json that grants access to the bucket:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Action": [
           "s3:DeleteObjectTagging",
           "s3:ReplicateObject",
           "s3:PutObject",
           "s3:GetObjectAcl",
           "s3:GetObject",
           "s3:DeleteObjectVersion",
           "s3:ListBucket",
           "s3:PutObjectTagging",
           "s3:DeleteObject",
           "s3:PutObjectAcl"
         ],
         "Resource": [
           "arn:aws:s3:::BUCKET_NAME",
           "arn:aws:s3:::BUCKET_NAME/*"
         ]
       }
     ]
   }
   

3. Create the policy with the AWS CLI:

   aws iam create-policy --policy-name <your-policy> --policy-document file://s3-policy.json
   

Create IAM role

1. Define a trust policy trust-policy.json:

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": { "Service": "ec2.amazonaws.com" },
         "Action": "sts:AssumeRole"
       }
     ]
   }
   

2. Create the IAM role and attach each IAM policy:

   aws iam create-role --role-name <your-role-name> --assume-role-policy-document file://trust-policy.json
   aws iam attach-role-policy --role-name <your-role-name> --policy-arn arn:aws:iam::<account-id>:policy/<your-policy>
   

Retrieve OIDC provider URL

1. Get the OIDC provider URL for your EKS cluster:

   aws eks describe-cluster --name <your-cluster-name> --region <region> --query "cluster.identity.oidc.issuer" --output text
   

2. Save the oidc-id (the last segment of the URL).

3. Verify that the OIDC provider exists in your account:

   aws iam list-open-id-connect-providers
   

   If the OIDC provider does not exist in your account, add it manually in the IAM Console. For more information, see the AWS documentation on creating and managing OIDC identity providers.

Create trust policy

1. Create a trust policy (trust-policy-irsa.json):

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Effect": "Allow",
         "Principal": {
           "Federated": "arn:aws:iam::<account-id>:oidc-provider/oidc.eks.<region>.amazonaws.com/id/<oidc-id>"
         },
         "Action": "sts:AssumeRoleWithWebIdentity",
         "Condition": {
           "StringEquals": {
             "oidc.eks.<region>.amazonaws.com/id/<oidc-id>:sub": "system:serviceaccount:<namespace>:hd-job-sa"
           }
         }
       }
     ]
   }
   

2. Update the IAM role trust policy:

   aws iam update-assume-role-policy --role-name <your-role-name> --policy-document file://trust-policy-irsa.json
   

Annotate Kubernetes service account

Annotate the service account with the IAM role ARN:

kubectl annotate serviceaccount hd-job-sa -n <namespace> eks.amazonaws.com/role-arn=arn:aws:iam::<account-id>:role/<your-role-name>

Update Hybrid Deployment jobs

When these jobs run, they automatically assume the associated IAM role and access AWS services as defined by the attached IAM policy.