Help improve this page
Want to contribute to this user guide? Scroll to the bottom of this page and select Edit this page on GitHub. Your contributions will help make our user guide better for everyone.
Amazon EBS CSI migration frequently asked questions
Important
If you have Pods running on a version 1.22
or earlier
cluster, then you must install the Amazon EBS CSI driver
before updating your cluster to version 1.23
to avoid service interruption.
The Amazon EBS container storage interface (CSI) migration feature moves responsibility for handling storage operations from the Amazon EBS in-tree EBS storage provisioner to the Amazon EBS CSI driver.
What are CSI drivers?
CSI drivers:
-
replace the Kubernetes "in-tree" storage drivers that exist in the Kubernetes project source code.
-
work with storage providers, such as Amazon EBS.
-
provide a simplified plugin model that make it easier for storage providers like Amazon to release features and maintain support without depending on the Kubernetes release cycle.
For more information, see Introduction
What is CSI migration?
The Kubernetes CSI Migration feature moves responsibility for handling storage operations
from the existing in-tree storage plugins, such as kubernetes.io/aws-ebs
,
to corresponding CSI drivers. Existing StorageClass
,
PersistentVolume
and PersistentVolumeClaim
(PVC) objects
continue to work, as long as the corresponding CSI driver is installed. When the feature
is enabled:
-
Existing workloads that utilize PVCs continue to function as they always have.
-
Kubernetes passes control of all storage management operations to CSI drivers.
For more information, see Kubernetes1.23
: Kubernetes In-Tree to CSI Volume Migration Status
Update
To help you migrate from the in-tree plugin to CSI drivers, the
CSIMigration
and CSIMigrationAWS
flags are enabled by
default on Amazon EKS version 1.23
and later clusters. These flags enable your
cluster to translate the in-tree APIs to their equivalent CSI APIs. These flags are set
on the Kubernetes control plane managed by Amazon EKS and in the kubelet
settings configured in
Amazon EKS optimized AMIs. If you have Pods using Amazon EBS
volumes in your cluster, you must install the Amazon EBS CSI driver before updating your
cluster to version 1.23
. If you don't, volume operations
such as provisioning and mounting might not work as expected. For more information, see
Use Amazon EBS storage.
Note
The in-tree StorageClass
provisioner is named
kubernetes.io/aws-ebs
. The Amazon EBS CSI StorageClass
provisioner is named ebs.csi.aws.com
.
Can I mount
kubernetes.io/aws-ebs StorageClass
volumes in version
1.23
and later clusters?
Yes, as long as the Amazon EBS CSI driver is installed. For
newly created version 1.23
and later clusters, we recommend installing the
Amazon EBS CSI driver as part of your cluster creation process. We also recommend only using
StorageClasses
based on the ebs.csi.aws.com
provisioner.
If you've updated your cluster control plane to version 1.23
and haven't
yet updated your nodes to 1.23
, then the CSIMigration
and
CSIMigrationAWS
kubelet
flags aren't enabled. In this case, the
in-tree driver is used to mount kubernetes.io/aws-ebs
based volumes. The
Amazon EBS CSI driver must still be installed however, to ensure that Pods
using kubernetes.io/aws-ebs
based volumes can be scheduled. The driver is
also required for other volume operations to succeed.
Can I provision
kubernetes.io/aws-ebs StorageClass
volumes on Amazon EKS
1.23
and later clusters?
Yes, as long as the Amazon EBS CSI driver is installed.
Will the
kubernetes.io/aws-ebs StorageClass
provisioner ever be removed from
Amazon EKS?
The kubernetes.io/aws-ebs
StorageClass
provisioner and awsElasticBlockStore
volume type
are no longer supported, but there are no plans to remove them. These resources are
treated as a part of the Kubernetes API.
How do I install the Amazon EBS CSI driver?
We recommend installing the Amazon EBS CSI driver Amazon EKS
add-on. When an update is required to the Amazon EKS add-on, you initiate the
update and Amazon EKS updates the add-on for you. If you want to manage the driver yourself,
you can install it using the open source Helm chart
Important
The Kubernetes in-tree Amazon EBS driver runs on the Kubernetes control plane. It uses IAM permissions assigned to the Amazon EKS cluster IAM role to provision Amazon EBS volumes. The Amazon EBS CSI driver runs on nodes. The driver needs IAM permissions to provision volumes. For more information, see Create an Amazon EBS CSI driver IAM role.
How can I check whether the Amazon EBS CSI driver is installed in my cluster?
To determine whether the driver is installed on your cluster, run the following command:
kubectl get csidriver ebs.csi.aws.com
To check if that installation is managed by Amazon EKS, run the following command:
aws eks list-addons --cluster-name
my-cluster
Will Amazon EKS prevent a cluster
update to version 1.23
if I haven't already installed the Amazon EBS CSI
driver?
No.
What if I forget to install the Amazon EBS CSI driver before I update my cluster to version 1.23? Can I install the driver after updating my cluster?
Yes, but volume operations requiring the Amazon EBS CSI driver will fail after your cluster update until the driver is installed.
What is the default
StorageClass
applied in newly created Amazon EKS version
1.23
and later clusters?
The default StorageClass
behavior remains unchanged. With each new
cluster, Amazon EKS applies a kubernetes.io/aws-ebs
based
StorageClass
named gp2
. We don't plan to ever remove this
StorageClass
from newly created clusters. Separate from the
cluster default StorageClass
, if you create an ebs.csi.aws.com
based StorageClass
without specifying a volume type, the Amazon EBS CSI driver
will default to using gp3
.
Will Amazon EKS make any changes
to StorageClasses
already present in my existing cluster when I update
my cluster to version 1.23
?
No.
How do I migrate a
persistent volume from the kubernetes.io/aws-ebs
StorageClass
to ebs.csi.aws.com
using snapshots?
To migrate a persistent volume, see Migrating Amazon EKS clusters from gp2 to gp3 EBS volumes
How do I modify an Amazon EBS volume using annotations?
Starting with aws-ebs-csi-driver
v1.19.0-eksbuild.2
, you can modify Amazon EBS volumes using annotations within
their PersistentVolumeClaim
s (PVC). The new volume modificationvolumemodifier
. For more information, see Simplifying Amazon EBS volume migration and modification on Kubernetes using the EBS CSI
Driver
Is migration supported for Windows workloads?
Yes. If you're installing the Amazon EBS CSI driver using the open source Helm chart, set
node.enableWindows
to true
. This is set by default if
installing the Amazon EBS CSI driver as an Amazon EKS add-on. When creating
StorageClasses
, set the fsType
to a Windows file system,
such as ntfs
. Volume operations for Windows workloads are then migrated to
the Amazon EBS CSI driver the same as they are for Linux workloads.