Install EKS EBS CSI Driver¶

Install the Amazon EBS Container Storage Interface (CSI) driver to enable Kubernetes workloads on EKS to dynamically provision and manage EBS volumes as PersistentVolumes. Follow the sequence to create the IAM role, install the addon, apply the fallback workaround when iam:PassRole is unavailable, and verify the installation.

Meet Prerequisites¶

Ensure the following prerequisites are in place before starting:

• An EKS cluster is running and kubectl is configured.
• eksctl is installed.
• AWS CLI is installed and authenticated.
• Access exists to create IAM roles and install EKS addons, or at minimum to create IAM roles and patch Kubernetes ServiceAccounts.

Export the Cluster Name¶

Export the cluster name as an environment variable:

export CLUSTER_NAME=<eks-cluster-name>

Verify the variable before continuing:

echo "$CLUSTER_NAME"

An error occurred (ParamValidation): argument --cluster-name: expected one argument

Create the IAM Role¶

Run the following command:

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

This command creates the IAM role required by the EBS CSI driver. It configures the role for IRSA (IAM Roles for Service Accounts) so the Kubernetes ServiceAccount can later assume the role through the cluster OIDC provider.

Understand the role of --role-only¶

Use --role-only to stop eksctl from creating or modifying the Kubernetes ServiceAccount. Leave ServiceAccount creation to the EKS addon installation flow or to a manual patching step in the fallback path.

By default, eksctl create iamserviceaccount performs two actions:

1. Create the IAM role.
2. Create or update the Kubernetes ServiceAccount with the IAM role annotation.

With --role-only, perform only the first action.

Check the addon versions¶

Check the supported addon versions for the cluster Kubernetes version:

eksctl utils describe-addon-versions --kubernetes-version 1.35 | grep AddonName

Replace 1.35 with the actual cluster version if required.

Check the cluster version with:

aws eks describe-cluster --name $CLUSTER_NAME --query "cluster.version" --output text

Install the addon with the IAM role ARN¶

Retrieve the IAM role ARN:

ROLE_ARN=$(aws iam get-role --role-name AmazonEKS_EBS_CSI_DriverRole --query "Role.Arn" --output text)

Install the addon with the role ARN:

aws eks create-addon \
  --cluster-name $CLUSTER_NAME \
  --addon-name aws-ebs-csi-driver \
  --service-account-role-arn $ROLE_ARN

This command installs the AWS-managed EBS CSI addon on the cluster and attach the previously created IAM role to the addon-managed ServiceAccount.

After successful completion, expect the following resources to appear:

• The EBS CSI controller deployment in kube-system.
• The ebs-csi-controller-sa ServiceAccount in kube-system.
• A default EBS-backed StorageClass.

Apply the fallback workaround when iam:PassRole is unavailable¶

Use the fallback path when the environment does not allow adding the missing IAM permission, such as a third-party AWS playground or KodeKloud AWS playground. In that case, create the addon without passing the role ARN, then manually annotate the ServiceAccount and restart the controller.

Recognize the failure¶

Expect the standard addon command to fail with an error similar to the following:

AccessDeniedException: User ... is not authorized to perform: iam:PassRole on resource ... because no identity-based policy allows the iam:PassRole action

Create the addon without the role ARN¶

Run the addon installation without --service-account-role-arn:

aws eks create-addon \
  --cluster-name $CLUSTER_NAME \
  --addon-name aws-ebs-csi-driver \
  --resolve-conflicts "OVERWRITE"

Wait for the addon resources to appear.

Annotate the ServiceAccount manually¶

Retrieve the IAM role ARN:

ROLE_ARN=$(aws iam get-role --role-name AmazonEKS_EBS_CSI_DriverRole --query "Role.Arn" --output text)

Annotate the ServiceAccount manually:

kubectl annotate serviceaccount ebs-csi-controller-sa \
  -n kube-system \
  eks.amazonaws.com/role-arn=$ROLE_ARN \
  --overwrite

Restart the controller¶

Restart the controller deployment so the pods pick up the new annotation:

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

Wait for the rollout to complete:

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

Verify the installation¶

Check the addon state:

aws eks describe-addon \
  --cluster-name $CLUSTER_NAME \
  --addon-name aws-ebs-csi-driver \
  --query "addon.status"

Check the deployment and ServiceAccount:

kubectl get deploy -n kube-system | grep ebs-csi
kubectl get sa -n kube-system | grep ebs-csi-controller-sa

Check the StorageClass:

kubectl get storageclass

Confirm the ServiceAccount annotation:

kubectl get sa ebs-csi-controller-sa -n kube-system -o yaml | grep role-arn

Configure the Default StorageClass (gp2 → gp3)¶

After installing the EBS CSI driver, running kubectl get sc shows a gp2 StorageClass that was never explicitly created:

NAME   PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
gp2    kubernetes.io/aws-ebs   Delete          WaitForFirstConsumer   false                  68m

This StorageClass is created automatically by EKS during cluster bootstrapping. It uses the in-tree EBS provisioner (kubernetes.io/aws-ebs), which is built into the Kubernetes node itself and does not require any CSI driver. AWS shipped this as the cluster default up through EKS 1.29.

This provisioner is deprecated. It does not support gp3 volume types. To use gp3, create a new StorageClass backed by the modern CSI provisioner (ebs.csi.aws.com) and demote gp2 from the default.

gp2 vs gp3¶

The critical gp2 trap: a 10 GiB gp2 volume gets only 30 IOPS. A 10 GiB gp3 volume gets 3,000 IOPS at no extra cost.

Create the gp3 StorageClass¶

Apply the following manifest to create a gp3 StorageClass using the CSI provisioner:

cat <<EOF | kubectl apply -f -
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gp3
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: ebs.csi.aws.com
parameters:
  type: gp3
  fsType: ext4
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
EOF

Remove the default annotation from gp2¶

kubectl patch storageclass gp2 -p \
  '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "false"}}}'

Verify¶

kubectl get sc

Expect the following output:

NAME            PROVISIONER             RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
gp2             kubernetes.io/aws-ebs   Delete          WaitForFirstConsumer   false                  80m
gp3 (default)   ebs.csi.aws.com         Delete          WaitForFirstConsumer   true                   36s

Any new PVC that does not specify a storageClassName will now automatically provision a gp3 EBS volume with 3,000 IOPS baseline.

Troubleshoot common failures¶

Fix iam:PassRole failures¶

Use the fallback workaround section in environments where IAM policy changes are not possible. If IAM policy changes are possible, add iam:PassRole permission on AmazonEKS_EBS_CSI_DriverRole and use the standard addon installation path.

Handle a missing ServiceAccount before addon installation¶

Treat this as expected behavior. The ServiceAccount is not created by the eksctl create iamserviceaccount ... --role-only command. The ServiceAccount appears only after addon installation, or after a manual creation path outside this runbook.

Quick Run¶

export CLUSTER_NAME=<eks-cluster-name>
echo "$CLUSTER_NAME"

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

ROLE_ARN=$(aws iam get-role --role-name AmazonEKS_EBS_CSI_DriverRole --query "Role.Arn" --output text)

aws eks create-addon \
  --cluster-name $CLUSTER_NAME \
  --addon-name aws-ebs-csi-driver \
  --service-account-role-arn $ROLE_ARN

aws eks describe-addon \
  --cluster-name $CLUSTER_NAME \
  --addon-name aws-ebs-csi-driver \
  --query "addon.status"

sleep 15

kubectl get deploy -n kube-system | grep ebs-csi
kubectl get sa -n kube-system | grep ebs-csi-controller-sa
kubectl get storageclass

# Migrate default StorageClass from gp2 to gp3
cat <<EOF | kubectl apply -f -
apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: gp3
  annotations:
    storageclass.kubernetes.io/is-default-class: "true"
provisioner: ebs.csi.aws.com
parameters:
  type: gp3
  fsType: ext4
reclaimPolicy: Delete
volumeBindingMode: WaitForFirstConsumer
allowVolumeExpansion: true
EOF

kubectl patch storageclass gp2 -p \
  '{"metadata": {"annotations": {"storageclass.kubernetes.io/is-default-class": "false"}}}'

kubectl get sc

Fallback for iam:PassRole failures¶

aws eks create-addon \
  --cluster-name $CLUSTER_NAME \
  --addon-name aws-ebs-csi-driver \
  --resolve-conflicts "OVERWRITE"

sleep 15

kubectl annotate serviceaccount ebs-csi-controller-sa \
  -n kube-system \
  eks.amazonaws.com/role-arn=$ROLE_ARN \
  --overwrite

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

sleep 15

aws eks describe-addon \
  --cluster-name $CLUSTER_NAME \
  --addon-name aws-ebs-csi-driver \
  --query "addon.status"

kubectl get deploy -n kube-system | grep ebs-csi
kubectl get sa -n kube-system | grep ebs-csi-controller-sa
kubectl get storageclass
kubectl get sa ebs-csi-controller-sa -n kube-system -o yaml | grep role-arn