Amazon EBS CSI driver - Amazon EKS

Amazon EBS CSI driver

The Amazon EBS Container Storage Interface (CSI) driver provides a CSI interface that allows Amazon EKS clusters to manage the lifecycle of Amazon EBS volumes for persistent volumes.

This topic shows you how to deploy the Amazon EBS CSI Driver to your Amazon EKS cluster and verify that it works. We recommend using version v0.8.0 of the driver.


The driver is not supported on Fargate. Alpha features of the Amazon EBS CSI Driver are not supported on Amazon EKS clusters. The driver is in Beta release. It is well tested and supported by Amazon EKS for production use. Support for the driver will not be dropped, though details may change. If the schema or schematics of the driver changes, instructions for migrating to the next version will be provided.

For detailed descriptions of the available parameters and complete examples that demonstrate the driver's features, see the Amazon EBS Container Storage Interface (CSI) driver project on GitHub.

To deploy the Amazon EBS CSI driver to an Amazon EKS cluster

  1. Create an IAM policy called Amazon_EBS_CSI_Driver for your node instance profile that allows the Amazon EBS CSI Driver to make calls to AWS APIs on your behalf. Use the following AWS CLI commands to create the IAM policy in your AWS account. You can view the policy document on GitHub.

    1. Download the policy document from GitHub.

      curl -O
    2. Create the policy.

      aws iam create-policy --policy-name Amazon_EBS_CSI_Driver \ --policy-document file://example-iam-policy.json

    Take note of the policy ARN that is returned.

  2. Get the IAM role name for your nodes. Use the following command to print the aws-auth configmap.

    kubectl -n kube-system describe configmap aws-auth


    Name: aws-auth Namespace: kube-system Labels: <none> Annotations: <none> Data ==== mapRoles: ---- - groups: - system:bootstrappers - system:nodes rolearn: arn:aws:iam::111122223333:role/eksctl-my-cluster-my-nodegroup-NodeInstanceRole-XXXXXXXXXXXX username: system:node:{{EC2PrivateDNSName}}

    Record the role name for any rolearn values that have the system:nodes group assigned to them. In the previous example output, the role name is eksctl-my-cluster-my-nodegroup-NodeInstanceRole-XXXXXXXXXXXX. You should have one value for each node group in your cluster.

  3. Attach the new Amazon_EBS_CSI_Driver IAM policy to each of the node IAM roles you identified earlier with the following command, substituting the red text with your own AWS account number and node IAM role name.

    aws iam attach-role-policy \ --policy-arn arn:aws:iam::<111122223333>:policy/Amazon_EBS_CSI_Driver \ --role-name <eksctl-my-cluster-my-nodegroup-NodeInstanceRole-XXXXXXXXXXXX>
  4. If you want the driver to tag all Amazon EBS volumes that the Amazon EBS CSI driver creates with the same tag, complete the following steps. If you don't want the driver to tag the volumes that it creates, skip to step 5.

    1. Clone the Amazon EBS Container Storage Interface (CSI) driver GitHub repository to your computer.

      git clone
    2. Navigate to the base example folder.

      cd aws-ebs-csi-driver/deploy/kubernetes/base/
    3. Edit the controller.yaml file. Find the section of the file with the following text and add --extra-tags to it. The following text shows the section of the file with the existing and added text. This example will cause the controller to add department and environment tags to all volumes it creates.

      ... containers: - name: ebs-plugin image: amazon/aws-ebs-csi-driver:latest imagePullPolicy: IfNotPresent args: # - {all,controller,node} # specify the driver mode - --endpoint=$(CSI_ENDPOINT) - --logtostderr - --v=5 - --extra-tags=department=accounting,environment=dev ...
    4. Apply the modified manifest to your cluster.

      kubectl apply -k ../base
  5. Skip this step if you completed step 4. Deploy the Amazon EBS CSI Driver with the command that corresponds to the Region that your cluster is in.


    This commands require version 1.14 or later of kubectl. You can see your kubectl version with the following command. To install or upgrade your kubectl version, see Installing kubectl.

    kubectl version --client --short
    • All Regions other than China Regions.

      kubectl apply -k ""
    • Beijing and Ningxia China Regions.

      kubectl apply -k ""

To deploy a sample application and verify that the CSI driver is working

This procedure uses the Dynamic volume provisioning example from the Amazon EBS Container Storage Interface (CSI) driver GitHub repository to consume a dynamically-provisioned Amazon EBS volume.

  1. Clone the Amazon EBS Container Storage Interface (CSI) driver GitHub repository to your local system.

    git clone
  2. Navigate to the dynamic-provisioning example directory.

    cd aws-ebs-csi-driver/examples/kubernetes/dynamic-provisioning/
  3. Deploy the ebs-sc storage class, ebs-claim persistent volume claim, and app sample application from the specs directory.

    kubectl apply -f specs/
  4. Describe the ebs-sc storage class.

    kubectl describe storageclass ebs-sc


    Name: ebs-sc IsDefaultClass: No Annotations:{"apiVersion":"","kind":"StorageClass","metadata":{"annotations":{},"name":"ebs-sc"},"provisioner":"","volumeBindingMode":"WaitForFirstConsumer"} Provisioner: Parameters: <none> AllowVolumeExpansion: <unset> MountOptions: <none> ReclaimPolicy: Delete VolumeBindingMode: WaitForFirstConsumer Events: <none>

    Note that the storage class uses the WaitForFirstConsumer volume binding mode. This means that volumes are not dynamically provisioned until a pod makes a persistent volume claim. For more information, see Volume Binding Mode in the Kubernetes documentation.

  5. Watch the pods in the default namespace and wait for the app pod to become ready.

    kubectl get pods --watch
  6. List the persistent volumes in the default namespace. Look for a persistent volume with the default/ebs-claim claim.

    kubectl get pv


    NAME CAPACITY ACCESS MODES RECLAIM POLICY STATUS CLAIM STORAGECLASS REASON AGE pvc-37717cd6-d0dc-11e9-b17f-06fad4858a5a 4Gi RWO Delete Bound default/ebs-claim ebs-sc 30s
  7. Describe the persistent volume.

    kubectl describe pv <pvc-37717cd6-d0dc-11e9-b17f-06fad4858a5a>


    Name: pvc-37717cd6-d0dc-11e9-b17f-06fad4858a5a Labels: <none> Annotations: Finalizers: [ external-attacher/ebs-csi-aws-com] StorageClass: ebs-sc Status: Bound Claim: default/ebs-claim Reclaim Policy: Delete Access Modes: RWO VolumeMode: Filesystem Capacity: 4Gi Node Affinity: Required Terms: Term 0: in [<regiona>] Message: Source: Type: CSI (a Container Storage Interface (CSI) volume source) Driver: VolumeHandle: <vol-0d651e157c6d93445> ReadOnly: false VolumeAttributes: Events: <none>

    The Amazon EBS volume ID is listed as the VolumeHandle.

  8. Verify that the pod is successfully writing data to the volume.

    kubectl exec -it app cat /data/out.txt


    Wed Jul 8 13:52:09 UTC 2020 Wed Jul 8 13:52:14 UTC 2020 Wed Jul 8 13:52:19 UTC 2020 Wed Jul 8 13:52:24 UTC 2020 Wed Jul 8 13:52:29 UTC 2020 Wed Jul 8 13:52:34 UTC 2020
  9. When you finish experimenting, delete the resources for this sample application to clean up.

    kubectl delete -f specs/