Creating the Amazon EBS CSI driver IAM role for service accounts - Amazon EKS
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Creating the Amazon EBS CSI driver IAM role for service accounts

The Amazon EBS CSI plugin requires IAM permissions to make calls to Amazon APIs on your behalf. For more information, see Set up driver permission on GitHub.

When the plugin is deployed, it creates and is configured to use a service account that's named ebs-csi-controller-sa. The service account is bound to a Kubernetes clusterrole that's assigned the required Kubernetes permissions.

Note

No matter if you configure the Amazon EBS CSI plugin to use IAM roles for service accounts, the pods have access to the permissions that are assigned to the IAM role. This is the case except when you block access to IMDS. For more information, see Security best practices for Amazon EKS.

Prerequisites

  • An existing cluster.

    • 1.20 requires eks.3 or later.

    • 1.21 requires eks.3 or later.

  • An existing Amazon Identity and Access Management (IAM) OpenID Connect (OIDC) provider for your cluster. To determine whether you already have one, or to create one, see Creating an IAM OIDC provider for your cluster.

Create an IAM role and attach the required Amazon managed policy to it. You can use eksctl, the Amazon Web Services Management Console, or the Amazon CLI.

eksctl
To create your Amazon EBS CSI plugin IAM role with eksctl

  1. Create an IAM role and attach the required Amazon managed policy with the following command. Replace my-cluster with the name of your cluster. The command deploys an Amazon CloudFormation stack that creates an IAM role, attaches the IAM policy to it, and annotates the existing ebs-csi-controller-sa service account with the Amazon Resource Name (ARN) of the IAM role. 

    eksctl create iamserviceaccount \
  --name ebs-csi-controller-sa \
  --namespace kube-system \
  --cluster my-cluster \
  --attach-policy-arn arn:aws-cn:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy \
  --approve \
  --role-only \
  --role-name AmazonEKS_EBS_CSI_DriverRole

  2. If you use a custom KMS key for encryption on your Amazon EBS volumes, customize the IAM role as needed. For example, do the following:

    1. Copy and paste the following code into a new kms-key-for-encryption-on-ebs.json file. Replace custom-key-id with the custom KMS key ID.

      {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:CreateGrant",
        "kms:ListGrants",
        "kms:RevokeGrant"
      ],
      "Resource": ["custom-key-id"],
      "Condition": {
        "Bool": {
          "kms:GrantIsForAWSResource": "true"
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*",
        "kms:DescribeKey"
      ],
      "Resource": ["custom-key-id"]
    }
  ]
}

    2. Create the policy. You can change KMS_Key_For_Encryption_On_EBS_Policy to a different name. However, if you do, make sure to change it in later steps, too.

      aws iam create-policy \
  --policy-name KMS_Key_For_Encryption_On_EBS_Policy \
  --policy-document file://kms-key-for-encryption-on-ebs.json

    3. Attach the IAM policy to the role with the following command. Replace 111122223333 with your account ID. 

      aws iam attach-role-policy \
  --policy-arn arn:aws-cn:iam::111122223333:policy/KMS_Key_For_Encryption_On_EBS_Policy \
  --role-name AmazonEKS_EBS_CSI_DriverRole
Amazon Web Services Management Console
To create your Amazon EBS CSI plugin IAM role with the Amazon Web Services Management Console

  1. Open the IAM console at https://console.amazonaws.cn/iam/.

  2. In the left navigation pane, choose Roles.

  3. On the Roles page, choose Create role.

  4. On the Select trusted entity page, do the following:

    1. In the Trusted entity type section, choose Web identity.

    2. For Identity provider, choose the OpenID Connect provider URL for your cluster (as shown under Overview in Amazon EKS).

    3. For Audience, choose sts.amazonaws.com.cn.

    4. Choose Next.

  5. On the Add permissions page, do the following:

    1. In the Filter policies box, enter AmazonEBSCSIDriverPolicy.

    2. Select the check box to the left of the AmazonEBSCSIDriverPolicy returned in the search.

    3. Choose Next.

  6. On the Name, review, and create page, do the following:

    1. For Role name, enter a unique name for your role, such as AmazonEKS_EBS_CSI_DriverRole.

    2. Under Add tags (Optional), add metadata to the role by attaching tags as key–value pairs. For more information about using tags in IAM, see Tagging IAM Entities in the IAM User Guide.

    3. Choose Create role.

  7. After the role is created, choose the role in the console to open it for editing.

  8. Choose the Trust relationships tab, and then choose Edit trust policy.

  9. Find the line that looks similar to the following line:

    "oidc.eks.region-code.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com.cn"

    Add a comma to the end of the previous line, and then add the following line after the previous line. Replace region-code with the Amazon Web Services Region that your cluster is in. Replace EXAMPLED539D4633E53DE1B71EXAMPLE with your cluster's OIDC provider ID.

    "oidc.eks.region-code.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:kube-system:ebs-csi-controller-sa"

  10. Choose Update policy to finish.

  11. If you use a custom KMS key for encryption on your Amazon EBS volumes, customize the IAM role as needed. For example, do the following:

    1. In the left navigation pane, choose Policies.

    2. On the Policies page, choose Create Policy.

    3. On the Create policy page, choose the JSON tab.

    4. Copy and paste the following code into the editor, replacing custom-key-id with the custom KMS key ID:

      {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:CreateGrant",
        "kms:ListGrants",
        "kms:RevokeGrant"
      ],
      "Resource": ["custom-key-id"],
      "Condition": {
        "Bool": {
          "kms:GrantIsForAWSResource": "true"
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*",
        "kms:DescribeKey"
      ],
      "Resource": ["custom-key-id"]
    }
  ]
}

    5. Choose Next: Tags.

    6. On the Add tags (Optional) page, choose Next: Review.

    7. For Name, enter a unique name for your policy (for example, KMS_Key_For_Encryption_On_EBS_Policy).

    8. Choose Create policy.

    9. In the left navigation pane, choose Roles.

    10. Choose the AmazonEKS_EBS_CSI_DriverRole in the console to open it for editing.

    11. From the Add permissions drop-down list, choose Attach policies.

    12. In the Filter policies box, enter KMS_Key_For_Encryption_On_EBS_Policy.

    13. Select the check box to the left of the KMS_Key_For_Encryption_On_EBS_Policy that was returned in the search.

    14. Choose Attach policies.

  12. Annotate the ebs-csi-controller-sa Kubernetes service account with the ARN of the IAM role.

    1. Annotate the service account. Replace 111122223333 with your account ID and AmazonEKS_EBS_CSI_DriverRole with the name of the IAM role.

      kubectl annotate serviceaccount ebs-csi-controller-sa \
    -n kube-system \
    eks.amazonaws.com/role-arn=arn:aws-cn:iam::111122223333:role/AmazonEKS_EBS_CSI_DriverRole

    2. Restart the ebs-csi-controller deployment for the annotation to take effect.

      kubectl rollout restart deployment ebs-csi-controller -n kube-system
Amazon CLI
To create your Amazon EBS CSI plugin IAM role with the Amazon CLI

  1. View your cluster's OIDC provider URL. Replace my-cluster with your cluster name. If the output from the command is None, review the Prerequisites.

    aws eks describe-cluster \
  --name my-cluster \
  --query "cluster.identity.oidc.issuer" \
  --output text

    The example output is as follows.

    https://oidc.eks.region-code.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE

  2. Create the IAM role.

    1. Copy the following contents to a file that's named aws-ebs-csi-driver-trust-policy.json. Replace 111122223333 with your account ID, region-code with your Amazon Web Services Region, and EXAMPLED539D4633E53DE1B71EXAMPLE with the value that was returned in the previous step. 

      {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws-cn:iam::111122223333:oidc-provider/oidc.eks.region-code.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "oidc.eks.region-code.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE:aud": "sts.amazonaws.com",
          "oidc.eks.region-code.amazonaws.com.cn/id/EXAMPLED539D4633E53DE1B71EXAMPLE:sub": "system:serviceaccount:kube-system:ebs-csi-controller-sa"
        }
      }
    }
  ]
}

    2. Create the role. You can change AmazonEKS_EBS_CSI_DriverRole to a different name. If you change it, make sure to change it in later steps.

      aws iam create-role \
  --role-name AmazonEKS_EBS_CSI_DriverRole \
  --assume-role-policy-document file://"aws-ebs-csi-driver-trust-policy.json"

  3. Attach the required Amazon managed policy to the role with the following command. 

    aws iam attach-role-policy \
  --policy-arn arn:aws-cn:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy \
  --role-name AmazonEKS_EBS_CSI_DriverRole

  4. If you use a custom KMS key for encryption on your Amazon EBS volumes, customize the IAM role as needed. For example, do the following:

    1. Copy and paste the following code into a new kms-key-for-encryption-on-ebs.json file. Replace custom-key-id with the custom KMS key ID.

      {
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "kms:CreateGrant",
        "kms:ListGrants",
        "kms:RevokeGrant"
      ],
      "Resource": ["custom-key-id"],
      "Condition": {
        "Bool": {
          "kms:GrantIsForAWSResource": "true"
        }
      }
    },
    {
      "Effect": "Allow",
      "Action": [
        "kms:Encrypt",
        "kms:Decrypt",
        "kms:ReEncrypt*",
        "kms:GenerateDataKey*",
        "kms:DescribeKey"
      ],
      "Resource": ["custom-key-id"]
    }
  ]
}

    2. Create the policy. You can change KMS_Key_For_Encryption_On_EBS_Policy to a different name. However, if you do, make sure to change it in later steps, too.

      aws iam create-policy \
  --policy-name KMS_Key_For_Encryption_On_EBS_Policy \
  --policy-document file://kms-key-for-encryption-on-ebs.json

    3. Attach the IAM policy to the role with the following command. Replace 111122223333 with your account ID. 

      aws iam attach-role-policy \
  --policy-arn arn:aws-cn:iam::111122223333:policy/KMS_Key_For_Encryption_On_EBS_Policy \
  --role-name AmazonEKS_EBS_CSI_DriverRole

  5. Annotate the ebs-csi-controller-sa Kubernetes service account with the ARN of the IAM role. Replace 111122223333 with your account ID and AmazonEKS_EBS_CSI_DriverRole with the name of the IAM role.

    kubectl annotate serviceaccount ebs-csi-controller-sa \
    -n kube-system \
    eks.amazonaws.com/role-arn=arn:aws-cn:iam::111122223333:role/AmazonEKS_EBS_CSI_DriverRole

  6. Restart the ebs-csi-controller deployment for the annotation to take effect.

    kubectl rollout restart deployment ebs-csi-controller -n kube-system