The Amazon EBS CSI (Container Storage Interface) driver allows Amazon EKS clusters to manage the lifecycle of Amazon EBS volumes for persistent storage in Kubernetes.
This KB provides step-by-step instructions to install and configure the EBS CSI driver directly from the AWS Management.
By default, Kubernetes cannot directly create or attach AWS EBS volumes — it needs a Container Storage Interface (CSI) driver to communicate with AWS’s storage APIs.
Without this driver, any PVC created by the SWIFT sync process would remain in a “Pending” state, and the sync jobs would fail to initialize their data volumes.
Pre-requisite:
1. You have an existing Amazon EKS cluster.
2. You have Administrator access or sufficient IAM permissions to:
a. Manage EKS Add-ons
b. Create IAM roles and policies
Common Errors while sync in SWIFT if EBS CSI Driver Is Missing
If the EBS CSI driver is not installed on your EKS cluster, you may get the following errors when running sync operations in SWIFT: TRAIPOD deploy fail with below error.
K8S cluster object sync failed. Detailed Error: Failed to deploy the TRAIPOD for the target cluster target-eks [ ERROR: TRAIPOD did not get ready for the K8S 'target-eks'. ERROR: SchedulerError: running PreBind plugin "VolumeBinding": binding volumes: context deadline exceeded TRAI Service Events: ============================== Type Reason Age From Message ---- ------ --- ---- ------- Normal EnsuringLoadBalancer 11m service-controller Ensuring load balancer Normal EnsuredLoadBalancer 10m service-controller Ensured load balancer TRAI Pod Events: ============================== Type Reason Age From Message ---- ------ --- ---- ------- Warning FailedScheduling 489080h running PreBind plugin "VolumeBinding": binding volumes: context deadline exceeded ]
Also if you describe the 'Pending' PVC, you will get the exact reason for the failure.
kubectl describe pvc <pvc-name> -n <namespace>
Normal WaitForFirstConsumer 16m (x5 over 17m) persistentvolume-controller waiting for first consumer to be created before binding Normal ExternalProvisioning 2m43s (x59 over 16m) persistentvolume-controller Waiting for a volume to be created either by the external provisioner 'ebs.csi.aws.com' or manually by the system administrator. If volume creation is delayed, please verify that the provisioner is running and correctly registered.
Above error indicate that the sync process cannot create or attach persistent volumes because the EBS CSI driver is missing. Installing the driver resolves these issues and allows the sync process to run successfully.
Below are the steps to add AWS EBS CSI Driver to resolution above error.
Step 1: Access the EKS Console
1. Sign in to the AWS Management Console.
2. Navigate to Amazon EKS > Clusters.
3. Select the cluster where you want to install the EBS CSI Driver.
Step 2: Open the Add-ons Section
1. In the left-hand navigation pane, click Add-ons.
2. Click Get more add-ons to view available add-ons.
Step 3: Select Amazon EBS CSI Driver
1. In the search bar, type EBS.
2. Select Amazon EBS CSI Driver from the list.
3. Click Next to configure the add-on.
Step 4: Configure the Add-on
1. Version – Select the latest version compatible with your EKS cluster version.
2. IAM Role – Choose or create a role:
- If you already have a role with the AmazonEBSCSIDriverPolicy, select it.
- If not, click Create a new IAM role.
- In the IAM console, attach the managed policy:
