Enabling Container Image Inspection from EKS Pods with OIDC and IAM (for ECR)

When running applications in Kubernetes on AWS EKS, it's often necessary for pods to interact with other AWS services, such as ECR (Elastic Container Registry) to pull or inspect images, or S3 to store data. Traditionally, this might involve embedding AWS access keys and secret keys within the pod, which is not a secure practice.

AWS IAM Roles for Service Accounts (IRSA) solves this by associating an Identity and Access Management (IAM) role with a Kubernetes service account (KSA). This allows applications running in the pod to assume the specified IAM role, granting them temporary credentials to access AWS resources. This document specifically focuses on using IRSA to enable a pod to inspect container images, and the related IAM permissions.

This guide outlines the steps to configure your Amazon EKS cluster and AWS Identity and Access Management (IAM) to allow pods to inspect container images without needing to store AWS credentials directly. This is achieved by leveraging AWS IRSA, which utilizes OpenID Connect (OIDC).

Prerequisites

Before you begin, ensure you have the following:

• An existing Amazon EKS cluster
• kubectl installed and configured to connect to your EKS cluster
• aws cli installed and configured with appropriate permissions to manage IAM and EKS resources
• eksctl installed (recommended for managing EKS clusters and OIDC)
• Understanding of KSA and AWS IAM

Step 1: Set variables

Set your environment variables:

export CLUSTER_NAME="your-eks-cluster-name"
export REGION="your-eks-cluster-region"
export AWS_ACCOUNT_ID="your-aws-account-id"
export EKS_ECR_INSPECT_POLICY="ECRImageInspectPolicy"
export EKS_ECR_INSPECT_ROLE="EKS_ECR_Inspect_Role"
export NAMESPACE="default"
export KSA_NAME="anzo-operator"

Step 2: Enable OIDC Provider for EKS Cluster

If your EKS cluster doesn't already have an OIDC identity provider associated with it, you need to enable it. This is a one-time setup per cluster.

You can check if an OIDC provider is enabled by running:

aws eks describe-cluster --name $CLUSTER_NAME --query "cluster.identity.oidc.issuer" --region $REGION --output text

If the output is empty, you need to enable it. The easiest way to do this is using eksctl:

eksctl utils associate-iam-oidc-provider --cluster $CLUSTER_NAME --region $REGION --approve

This command will:

• Discover your cluster's OIDC issuer URL.
• Create an IAM OIDC identity provider in your AWS account.

Note down the OIDC URL created for the cluster. You need to add this as a reference in IAM role.

Step 3: Create an IAM Policy for Image Inspection

Next, create an IAM policy that grants the necessary permissions to inspect container images from ECR.

Create a file named ecr-image-inspection-policy.json with the following content:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "ecr:GetDownloadUrlForLayer",
                "ecr:BatchGetImage",
                "ecr:DescribeImages",
                "ecr:BatchCheckLayerAvailability"
            ],
            "Resource": "arn:aws:ecr:us-east-1:$AWS_ACCOUNT_ID:repository/<ECR_REPO_NAME>"
        },
        {
            "Effect": "Allow",
            "Action": [
                "ecr:GetAuthorizationToken"
            ],
            "Resource": "*"
        }
    ]
}

Now, create the IAM policy using the AWS CLI:

aws iam create-policy \
    --policy-name $EKS_ECR_INSPECT_POLICY \
    --policy-document file://ecr-image-inspection-policy.json

Make a note of the Amazon resource name (ARN) of the created policy. You'll need it in the next step.

Step 4: Create an IRSA

Create an IAM role that your KSA will assume. This role will have a trust policy that allows the OIDC provider to assume it, and it will be attached to the EKSImageInspectionPolicy created in the previous step.

Create a file named trust-policy.json with the following content:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::$AWS_ACCOUNT_ID:oidc-provider/<OIDC_URL_WITHOUT_HTTPS>"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "OIDC_PROVIDER_URL:sub": "system:serviceaccount:$NAMESPACE:$KSA_NAME"
        }
      }
    }
  ]
}

aws iam create-role \
  --role-name $EKS_ECR_INSPECT_ROLE \
  --assume-role-policy-document file://trust-policy.json

aws iam attach-role-policy \
  --role-name $EKS_ECR_INSPECT_ROLE \
  --policy-arn arn:aws:iam::$AWS_ACCOUNT_ID:policy/$EKS_ECR_INSPECT_POLICY

These commands automate the following steps:

• Creates an IAM role.
• Attaches the specified IAM policy to the role.
• Configures the trust policy of the IAM role to allow your EKS cluster's OIDC provider to assume it.
• Creates or modifies a KSA with the necessary annotations (eks.amazonaws.com/role-arn).

Note down the ARN of the IAM role created. You need to add it as an annotation to the KSA.

Step 5: Annotate the KSA with the IRSA

To allow the KSA to impersonate the Google Cloud Service Account (GSA), annotate the KSA with the GSA’s email:

kubectl annotate serviceaccount \
  --namespace $NAMESPACE \
  $KSA_NAME \
    eks.amazonaws.com/role-arn=arn:aws:iam::$AWS_ACCOUNT_ID:role/$EKS_ECR_INSPECT_ROLE

This annotation tells EKS to use the specified IAM role and related permissions when the workload uses this KSA.