Install AWS EBS CSI driver

The Amazon Elastic Block Store (Amazon EBS) Container Storage Interface (CSI) driver allows Amazon Elastic Kubernetes Service (Amazon EKS) clusters to manage the lifecycle of Amazon EBS volumes for persistent volumes.

The Amazon EBS CSI driver isn't installed when you first create a cluster. These instructions will allow you to install manually after an EKS cluster has been created.

Pre-requisites:

• eksctl
• AWS CLI

Set the following environment variables:

• REGION
  • In lowercase
• CLUSTER_NAME
• AWS_ACCOUNT_ID
  • Can retrieve and set using export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
• EBS_CSI_DRIVER_ROLE
  • e.g. "sanjay_EBS_CSI_Driver_Role"

Step 1: Associate IAM OIDC provider with the EKS cluster

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

Step 2: Retrieve OIDC issuer URL of the EKS cluster

The OIDC issuer URL is the endpoint for authentication for the cluster's worker nodes

export OIDC_ISSUER=$(aws eks describe-cluster --name $CLUSTER_NAME --region $REGION --query "cluster.identity.oidc.issuer" --output text | sed -e "s/^https:\/\///")

Step 3: Create policy document

The file "trust-policy.json" is an AWS Identity and Access Management (IAM) policy document. It defines the permissions for a role, in this case a role that is assumed by an OIDC-authenticated user. The policy sets up trust between the role and the specified OIDC provider by allowing the provider to assume the role using the OIDC authentication token.

cat > trust-policy.json << EOF
{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Principal":{
            "Federated":"arn:aws:iam::${AWS_ACCOUNT_ID}:oidc-provider/${OIDC_ISSUER}"
         },
         "Action":"sts:AssumeRoleWithWebIdentity",
         "Condition":{
            "StringEquals":{
               "${OIDC_ISSUER}:aud": "sts.amazonaws.com",
               "${OIDC_ISSUER}:sub": "system:serviceaccount:kube-system:ebs-csi-controller-sa"
            }
         }
      }
   ]
}
EOF

Step 4: Create new IAM role for the EBS CSI Driver

aws iam create-role \
  --region $REGION \
  --role-name $EBS_CSI_DRIVER_ROLE \
  --assume-role-policy-document file://$(pwd)/trust-policy.json

(FOR CLEANUP ONLY) To delete role:

aws iam delete-role --region $REGION --role-name $EBS_CSI_DRIVER_ROLE

Step 5: Attach AmazonEBSCSIDriverPolicy to EBS CSI Driver role

aws iam attach-role-policy \
  --region $REGION \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy \
  --role-name $EBS_CSI_DRIVER_ROLE

(FOR CLEANUP ONLY) To delete the policy:

aws iam detach-role-policy --region $REGION --role-name $EBS_CSI_DRIVER_ROLE --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy

Step 6: Create AWS EBS CSI Driver add-on

aws eks create-addon --cluster-name $CLUSTER_NAME --addon-name aws-ebs-csi-driver  --region $REGION \
  --service-account-role-arn arn:aws:iam::${AWS_ACCOUNT_ID}:role/${EBS_CSI_DRIVER_ROLE}

To check the status of the EBC CSI driver add on in the cluster:

aws eks describe-addon --cluster-name $CLUSTER_NAME --region $REGION --addon-name aws-ebs-csi-driver

• Once addon.status is "ACTIVE" you are set

Example All-in-one script

Installation

export REGION=us-east-2
export CLUSTER_NAME=your-cluster-name
export AWS_ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
export EBS_CSI_DRIVER_ROLE="XXXX_EBS_CSI_Driver_Role"

eksctl utils associate-iam-oidc-provider --region=$REGION --cluster $CLUSTER_NAME --approve
sleep 1
export OIDC_ISSUER=$(aws eks describe-cluster --name $CLUSTER_NAME --region $REGION --query "cluster.identity.oidc.issuer" --output text | sed -e "s/^https:\/\///")
sleep 1
cat > trust-policy.json << EOF
{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Principal":{
            "Federated":"arn:aws:iam::${AWS_ACCOUNT_ID}:oidc-provider/${OIDC_ISSUER}"
         },
         "Action":"sts:AssumeRoleWithWebIdentity",
         "Condition":{
            "StringEquals":{
               "${OIDC_ISSUER}:aud": "sts.amazonaws.com",
               "${OIDC_ISSUER}:sub": "system:serviceaccount:kube-system:ebs-csi-controller-sa"
            }
         }
      }
   ]
}
EOF

aws iam create-role \
  --region $REGION \
  --role-name $EBS_CSI_DRIVER_ROLE \
  --assume-role-policy-document file://$(pwd)/trust-policy.json
sleep 1

aws iam attach-role-policy \
  --region $REGION \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy \
  --role-name $EBS_CSI_DRIVER_ROLE

sleep 1
aws eks create-addon --cluster-name $CLUSTER_NAME --addon-name aws-ebs-csi-driver  --region $REGION \
  --service-account-role-arn arn:aws:iam::${AWS_ACCOUNT_ID}:role/${EBS_CSI_DRIVER_ROLE}
sleep 1
aws eks describe-addon --cluster-name $CLUSTER_NAME --region $REGION --addon-name aws-ebs-csi-driver

Uninstall

aws iam detach-role-policy --region $REGION --role-name $EBS_CSI_DRIVER_ROLE --policy-arn arn:aws:iam::aws:policy/service-role/AmazonEBSCSIDriverPolicy
sleep 1
aws iam delete-role --region $REGION --role-name $EBS_CSI_DRIVER_ROLE