Creating the Amazon EBS CSI driver IAM role
The Amazon EBS CSI plugin requires IAM permissions to make calls to AWS APIs on your
behalf. For more information, see Set up driver permission
Note
Pods will have access to the permissions that are assigned to the IAM role unless 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 AWS 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.
The following procedure shows you how to create an IAM role and attach the required
AWS managed policy to it. You can use eksctl
, the AWS Management Console, or the AWS CLI.
Note
The specific steps in this procedure are written for using the driver as an Amazon EKS add-on. Different steps are needed to use the driver as a self-managed add-on.
- eksctl
-
To create your Amazon EBS CSI plugin IAM role with
eksctl
-
Create an IAM role and attach the required AWS managed policy with the following command. Replace
with the name of your cluster. The command deploys an AWS CloudFormation stack that creates an IAM role and attaches the IAM policy to it. If your cluster is in the AWS GovCloud (US-East) or AWS GovCloud (US-West) AWS Regions, then replacemy-cluster
arn:aws:
witharn:aws-us-gov:
.eksctl create iamserviceaccount \ --name ebs-csi-controller-sa \ --namespace kube-system \ --cluster
my-cluster
\ --attach-policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy
\ --approve \ --role-only \ --role-nameAmazonEKS_EBS_CSI_DriverRole
-
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: -
Copy and paste the following code into a new
file. Replacekms-key-for-encryption-on-ebs
.json
with the custom KMS key ARN.custom-key-arn
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": ["
custom-key-arn
"], "Condition": { "Bool": { "kms:GrantIsForAWSResource": "true" } } }, { "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": ["custom-key-arn
"] } ] } -
Create the policy. You can change
to a different name. However, if you do, make sure to change it in later steps, too.KMS_Key_For_Encryption_On_EBS_Policy
aws iam create-policy \ --policy-name
KMS_Key_For_Encryption_On_EBS_Policy
\ --policy-document file://kms-key-for-encryption-on-ebs
.json -
Attach the IAM policy to the role with the following command. Replace
with your account ID. If your cluster is in the AWS GovCloud (US-East) or AWS GovCloud (US-West) AWS Regions, then replace111122223333
arn:aws:
witharn:aws-us-gov:
.aws iam attach-role-policy \ --policy-arn arn:aws:iam::
111122223333
:policy/KMS_Key_For_Encryption_On_EBS_Policy
\ --role-nameAmazonEKS_EBS_CSI_DriverRole
-
-
- AWS Management Console
-
To create your Amazon EBS CSI plugin IAM role with the AWS Management Console
Open the IAM console at https://console.aws.amazon.com/iam/
. -
In the left navigation pane, choose Roles.
-
On the Roles page, choose Create role.
-
On the Select trusted entity page, do the following:
In the Trusted entity type section, choose Web identity.
-
For Identity provider, choose the OpenID Connect provider URL for your cluster (as shown under Overview in Amazon EKS).
-
For Audience, choose
sts.amazonaws.com
. Choose Next.
-
On the Add permissions page, do the following:
-
In the Filter policies box, enter
.AmazonEBSCSIDriverPolicy
-
Select the check box to the left of the
returned in the search.AmazonEBSCSIDriverPolicy
Choose Next.
-
-
On the Name, review, and create page, do the following:
-
For Role name, enter a unique name for your role, such as
.AmazonEKS_EBS_CSI_DriverRole
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.
-
Choose Create role.
-
After the role is created, choose the role in the console to open it for editing.
Choose the Trust relationships tab, and then choose Edit trust policy.
-
Find the line that looks similar to the following line:
"oidc.eks.
region-code
.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE
:aud": "sts.amazonaws.com"Add a comma to the end of the previous line, and then add the following line after the previous line. Replace
with the AWS Region that your cluster is in. Replaceregion-code
with your cluster's OIDC provider ID.EXAMPLED539D4633E53DE1B71EXAMPLE
"oidc.eks.
region-code
.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE
:sub": "system:serviceaccount:kube-system:ebs-csi-controller-sa" Choose Update policy to finish.
-
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: -
In the left navigation pane, choose Policies.
-
On the Policies page, choose Create Policy.
-
On the Create policy page, choose the JSON tab.
-
Copy and paste the following code into the editor, replacing
with the custom KMS key ARN.custom-key-arn
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": ["
custom-key-arn
"], "Condition": { "Bool": { "kms:GrantIsForAWSResource": "true" } } }, { "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": ["custom-key-arn
"] } ] } -
Choose Next: Tags.
-
On the Add tags (Optional) page, choose Next: Review.
-
For Name, enter a unique name for your policy (for example,
).KMS_Key_For_Encryption_On_EBS_Policy
-
Choose Create policy.
-
In the left navigation pane, choose Roles.
-
Choose the
AmazonEKS_EBS_CSI_DriverRole
in the console to open it for editing. -
From the Add permissions drop-down list, choose Attach policies.
-
In the Filter policies box, enter
.KMS_Key_For_Encryption_On_EBS_Policy
-
Select the check box to the left of the
that was returned in the search.KMS_Key_For_Encryption_On_EBS_Policy
-
Choose Attach policies.
-
- AWS CLI
-
To create your Amazon EBS CSI plugin IAM role with the AWS CLI
-
View your cluster's OIDC provider URL. Replace
with your cluster name. If the output from the command ismy-cluster
None
, review the Prerequisites.aws eks describe-cluster --name
my-cluster
--query "cluster.identity.oidc.issuer" --output textThe example output is as follows.
https://oidc.eks.
region-code
.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE
-
Create the IAM role, granting the
AssumeRoleWithWebIdentity
action.-
Copy the following contents to a file that's named
. Replaceaws-ebs-csi-driver-trust-policy
.json
with your account ID. Replace111122223333
andEXAMPLED539D4633E53DE1B71EXAMPLE
with the values returned in the previous step. If your cluster is in the AWS GovCloud (US-East) or AWS GovCloud (US-West) AWS Regions, then replaceregion-code
arn:aws:
witharn:aws-us-gov:
.{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Federated": "arn:aws:iam::
111122223333
:oidc-provider/oidc.eks.region-code
.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE
" }, "Action": "sts:AssumeRoleWithWebIdentity", "Condition": { "StringEquals": { "oidc.eks.region-code
.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE
:aud": "sts.amazonaws.com", "oidc.eks.region-code
.amazonaws.com/id/EXAMPLED539D4633E53DE1B71EXAMPLE
:sub": "system:serviceaccount:kube-system:ebs-csi-controller-sa" } } } ] } -
Create the role. You can change
to a different name. If you change it, make sure to change it in later steps.AmazonEKS_EBS_CSI_DriverRole
aws iam create-role \ --role-name
AmazonEKS_EBS_CSI_DriverRole
\ --assume-role-policy-document file://"aws-ebs-csi-driver-trust-policy
.json"
-
-
Attach the required AWS managed policy to the role with the following command. If your cluster is in the AWS GovCloud (US-East) or AWS GovCloud (US-West) AWS Regions, then replace
arn:aws:
witharn:aws-us-gov:
.aws iam attach-role-policy \ --policy-arn arn:aws:iam::aws:policy/service-role/
AmazonEBSCSIDriverPolicy
\ --role-nameAmazonEKS_EBS_CSI_DriverRole
-
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: -
Copy and paste the following code into a new
file. Replacekms-key-for-encryption-on-ebs
.json
with the custom KMS key ARN.custom-key-arn
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:CreateGrant", "kms:ListGrants", "kms:RevokeGrant" ], "Resource": ["
custom-key-arn
"], "Condition": { "Bool": { "kms:GrantIsForAWSResource": "true" } } }, { "Effect": "Allow", "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:ReEncrypt*", "kms:GenerateDataKey*", "kms:DescribeKey" ], "Resource": ["custom-key-arn
"] } ] } -
Create the policy. You can change
to a different name. However, if you do, make sure to change it in later steps, too.KMS_Key_For_Encryption_On_EBS_Policy
aws iam create-policy \ --policy-name
KMS_Key_For_Encryption_On_EBS_Policy
\ --policy-document file://kms-key-for-encryption-on-ebs
.json -
Attach the IAM policy to the role with the following command. Replace
with your account ID. If your cluster is in the AWS GovCloud (US-East) or AWS GovCloud (US-West) AWS Regions, then replace111122223333
arn:aws:
witharn:aws-us-gov:
.aws iam attach-role-policy \ --policy-arn arn:aws:iam::
111122223333
:policy/KMS_Key_For_Encryption_On_EBS_Policy
\ --role-nameAmazonEKS_EBS_CSI_DriverRole
-
-
Now that you have created the Amazon EBS CSI driver IAM role, you can continue to Adding the Amazon EBS CSI add-on. When
you deploy the plugin in that procedure, 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.