Soon, all Red Hat OpenShift documentation will only be available on docs.redhat.com, the official location of all Red Hat product documentation. Get familiar with the updated experience today!
  1. Documentation
×

CSI automatic migration

In-tree storage drivers that are traditionally shipped with OKD are being deprecated and replaced by their equivalent Container Storage Interface (CSI) drivers. OKD provides automatic migration for certain supported in-tree volume plugins to their equivalent CSI drivers.

Overview

Volumes that are provisioned by using in-tree storage plugins, and that are supported by this feature, are migrated to their counterpart Container Storage Interface (CSI) drivers. This process does not perform any data migration; OKD only translates the persistent volume object in memory. As a result, the translated persistent volume object is not stored on disk, nor is its contents changed.

The following in-tree to CSI drivers are supported:

Table 1. CSI automatic migration feature supported in-tree/CSI drivers
In-tree/CSI drivers Support level CSI auto migration enabled automatically?

  • Azure Disk

  • OpenStack Cinder

  • Amazon Web Services (AWS) Elastic Block Storage (EBS)

  • Google Compute Engine Persistent Disk (GCP PD)

Generally available (GA)

Yes. For more information, see Automatic migration of in-tree volumes to CSI.

  • Azure File

  • VMware vSphere

Technology Preview (TP)

No. To enable, see Manually enabling CSI automatic migration.

Also, for vSphere, see information below in:

  • Updating from OKD 4.12 to 4.13 with vSphere in-tree PVs

  • Updating from OKD 4.12 to 4.14 with vSphere in-tree PVs

CSI automatic migration should be seamless. This feature does not change how you use all existing API objects: for example, PersistentVolumes, PersistentVolumeClaims, and StorageClasses.

Enabling CSI automatic migration for in-tree persistent volumes (PVs) or persistent volume claims (PVCs) does not enable any new CSI driver features, such as snapshots or expansion, if the original in-tree storage plugin did not support it.

Additional resources

Automatic migration of in-tree volumes to CSI

OKD supports automatic and seamless migration for the following in-tree volume types to their Container Storage Interface (CSI) driver counterpart:

  • Azure Disk

  • OpenStack Cinder

  • Amazon Web Services (AWS) Elastic Block Storage (EBS)

  • Google Compute Engine Persistent Disk (GCP PD)

CSI migration for these volume types is considered generally available (GA), and requires no manual intervention.

For new OKD 4.11, and later, installations, the default storage class is the CSI storage class. All volumes provisioned using this storage class are CSI persistent volumes (PVs).

For clusters upgraded from 4.10, and earlier, to 4.11, and later, the CSI storage class is created, and is set as the default if no default storage class was set prior to the upgrade. In the very unlikely case that there is a storage class with the same name, the existing storage class remains unchanged. Any existing in-tree storage classes remain, and might be necessary for certain features, such as volume expansion to work for existing in-tree PVs. While storage class referencing to the in-tree storage plugin will continue working, we recommend that you switch the default storage class to the CSI storage class.

Manually enabling CSI automatic migration

If you want to test Container Storage Interface (CSI) migration in development or staging OKD clusters, you must manually enable in-tree to CSI migration for the following in-tree volume types:

  • VMware vSphere Disk

  • Azure File

CSI automatic migration for the preceding in-tree volume plugins and CSI driver pairs is a Technology Preview feature only. Technology Preview features are not supported with Red Hat production service level agreements (SLAs) and might not be functionally complete. Red Hat does not recommend using them in production. These features provide early access to upcoming product features, enabling customers to test functionality and provide feedback during the development process.

For more information about the support scope of Red Hat Technology Preview features, see Technology Preview Features Support Scope.

After migration, the default storage class remains the in-tree storage class.

CSI automatic migration will be enabled by default for all storage in-tree plugins in a future OKD release, so it is highly recommended that you test it now and report any issues.

Enabling CSI automatic migration drains, and then restarts, all nodes in the cluster in sequence. This might take some time.
Procedure

  • Enable feature gates (see Nodes → Working with clusters → Enabling features using feature gates).

    After turning on Technology Preview features using feature gates, they cannot be turned off. As a result, cluster upgrades are prevented.

    The following configuration example enables CSI automatic migration for all CSI drivers supported by this feature that are currently in Technology Preview (TP) status:

    apiVersion: config.openshift.io/v1
kind: FeatureGate
metadata:
  name: cluster
spec:
  featureSet: TechPreviewNoUpgrade (1)
...
    1 Enables automatic migration for Azure File and VMware vSphere.

    You can specify CSI automatic migration for a selected CSI driver by setting CustomNoUpgrade featureSet and for featuregates to one of the following:

    • CSIMigrationAzureFile

    • CSIMigrationvSphere

    The following configuration example enables automatic migration to the vSphere CSI driver only:

    apiVersion: config.openshift.io/v1
kind: FeatureGate
metadata:
  name: cluster
spec:
  featureSet: CustomNoUpgrade
  customNoUpgrade:
    enabled:
      - CSIMigrationvSphere (1)
    ...
    1 Enables automatic migration for vSphere only.
Additional resources

Updating from OKD 4.12 to 4.13 with vSphere in-tree PVs

If you are using vSphere in-tree persistent volumes (PVs) and want to update from OKD 4.12 to 4.13, update vSphere vCenter and ESXI host to 7.0 Update 3L or 8.0 Update 2, otherwise the OKD upgrade is blocked. After updating vSphere, your OKD update can occur and automatic Container Storage Interface (CSI) migration for vSphere occurs only if you opt in.

Alternatively, if you do not want to update vSphere, you can proceed with an OKD update by running the following command to perform an administrator acknowledgment:

oc -n openshift-config patch cm admin-acks --patch '{"data":{"ack-4.12-kube-126-vsphere-migration-in-4.14":"true"}}' --type=merge

It is generally safe to provide the requested administrator acknowledgment for updates from OKD 4.12 to 4.13 because CSI migration is not yet enabled for upgraded clusters from 4.12 to 4.13. However, Red Hat recommends that you start planning an update of your vSphere environment for a future update to 4.14, so that all the in-tree volumes can be managed by the CSI driver seamlessly.

If you do not update to OKD 4.13.10, or later, and do not update vSphere, and then opt in to migration (see Manually enabling CSI automatic migration under Additional resources), known issues can occur. Before opting in to migration, carefully read this knowledge base article.
Additional resources

Updating from OKD 4.12 to 4.14 with vSphere in-tree PVs

If you are using vSphere in-tree persistent volumes (PVs) and want to update from OKD 4.12 to 4.14, update vSphere vCenter and ESXI host to 7.0 Update 3L or 8.0 Update 2, otherwise the OKD updates are blocked. After updating vSphere, your OKD update can occur and automatic Container Storage Interface (CSI) migration for vSphere occurs automatically by default.

Alternatively, if you do not want to update vSphere, you can proceed with an OKD update by running both of the following commands to perform an administrator acknowledgment:

oc -n openshift-config patch cm admin-acks --patch '{"data":{"ack-4.12-kube-126-vsphere-migration-in-4.14":"true"}}' --type=merge
oc -n openshift-config patch cm admin-acks --patch '{"data":{"ack-4.13-kube-127-vsphere-migration-in-4.14":"true"}}' --type=merge

If you update to OKD 4.14 without updating vSphere, known issues can occur due to CSI migration being enabled by default in OKD 4.14. Before updating, carefully read this knowledge base article.

Updating from OKD 4.12 to 4.14 is an Extended Update Support (EUS)-to-EUS update. To understand the ramifications for this type of update and how to perform it, see the EUS-to-EUS update link in the Additional resources section below.