Merge pull request #45025 from lpettyjo/OSDOCS-3544and3545

OSDOCS-3544 & 3545: CSI Migration of Cinder and Azure Disk to GA

Author: lpettyjo

modules/persistent-storage-csi-migration-automatic-ga.adoc

@@ -0,0 +1,19 @@
+// Module included in the following assemblies:
+//
+// * storage/container_storage_interface/persistent-storage-csi-migration.adoc
+
+:_content-type: CONCEPT
+[id="persistent-storage-csi-migration-automatic-ga_{context}"]
+= Automatic migration of in-tree volumes to CSI
+
+{product-title} supports automatic and seamless migration for the following in-tree volume types to their Container Storage Interface (CSI) driver counterpart:
+
+* Azure Disk
+
+* OpenStack Cinder
+
+CSI migration for these volume types is considered generally available (GA), and requires no manual intervention.
+
+For new {product-title} 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 plug-in will continue working, we recommend that you switch the default storage class to the CSI storage class.

modules/persistent-storage-csi-migration-enable.adoc

@@ -4,7 +4,24 @@
 
 :_content-type: PROCEDURE
 [id="persistent-storage-csi-migration-enable_{context}"]
-= Enabling CSI automatic migration
+= Manually enabling CSI automatic migration
+
+If you want to test Container Storage Interface (CSI) migration in development or staging {product-title} clusters, you must manually enable in-tree to CSI migration for the following in-tree volume types:
+
+* AWS Elastic Block Storage (EBS)
+
+* Google Compute Engine Persistent Disk (GCE-PD)
+
+* VMware vSphere Disk
+
+* Azure File
+
+:FeatureName: CSI automatic migration for the preceding in-tree volume plug-ins and CSI driver pairs
+include::snippets/technology-preview.adoc[leveloffset=+1]
+
+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 plug-ins in a future {product-title} release, so it is highly recommended that you test it now and report any issues.
 
 [NOTE]
 ====
@@ -20,7 +37,7 @@ Enabling CSI automatic migration drains, and then restarts, all nodes in the clu
 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 to all CSI drivers supported by this feature:
+The following configuration example enables CSI automatic migration for all CSI drivers supported by this feature that are currently in Technology Preview (TP) status:
 +
 [source,yaml]
 ----
@@ -32,17 +49,13 @@ spec:
   featureSet: TechPreviewNoUpgrade <1>
 ...
 ----
-<1> Enables automatic migration for AWS EBS, Cinder, GCP, Azure Disk, Azure File, and VMware vSphere.
+<1> Enables automatic migration for AWS EBS, GCP, 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:
 +
 --
 * CSIMigrationAWS
 
-* CSIMigrationOpenStack
-
-* CSIMigrationAzure
-
 * CSIMigrationAzureFile
 
 * CSIMigrationGCE

modules/persistent-storage-csi-migration-overview-support-level.adoc

@@ -0,0 +1,36 @@
+// Module included in the following assemblies:
+//
+// * storage/container_storage_interface/persistent-storage-csi-migration.adoc
+
+:_content-type: CONCEPT
+[id="persistent-storage-csi-migration-overview-support-level_{context}"]
+= Automatic migration support level
+
+Certain in-tree volume plug-ins and their equivalent Container Storage Interface (CSI) driver are supported in Technology Preview (TP) status, whereas others are supported in General Availability (GA) status.
+
+The following table provides details about the support level of in-tree volume plug-ins/CSI driver pairs.
+
+.CSI automatic migration In-tree volume plug-ins/CSI driver pair support in {product-title}
+[cols=",^v,^v,^v width="100%",options="header"]
+|===
+|CSI drivers |Support level |CSI auto migration enabled automatically?
+
+a|
+* Amazon Web Services (AWS) Elastic Block Storage (EBS)
+* Azure File
+* Google Compute Engine Persistent Disk (in-tree) and Google Cloud Platform Persistent Disk (CSI)
+* VMware vSphere
+|TP
+| No. To enable, see "_Enabling CSI automatic migration_".
+
+a|
+* Azure Disk
+* OpenStack Cinder
+|GA
+| Yes
+|===
+
+[IMPORTANT]
+====
+CSI automatic migration will be enabled by default for all storage in-tree plug-ins in a future {product-title} release, so it is highly recommended that you test it now and report any issues.
+====

modules/persistent-storage-csi-migration-overview.adoc

@@ -6,27 +6,30 @@
 [id="persistent-storage-csi-migration-overview_{context}"]
 = Overview
 
-With the automatic migration feature enabled, volumes provisioned using in-tree storage plug-ins supported by this feature are migrated to their counterpart CSI drivers.
+Volumes that are provisioned by using in-tree storage plug-ins, 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; {product-title} 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 drivers are supported:
+The following in-tree to CSI drivers are supported:
 
-* Amazon Web Services (AWS) Elastic Block Storage (EBS)
-
-* OpenStack Cinder
+.CSI automatic migration feature supported in-tree/CSI drivers
+[cols=",^v,^v,^v width="100%",options="header"]
+|===
+|In-tree/CSI drivers |Support level |CSI auto migration enabled automatically?
 
+a|
 * Azure Disk
+* OpenStack Cinder
+|Generally available (GA)
+| Yes. For more information, see "_Automatic migration of in-tree volumes to CSI_".
 
+a|
+* Amazon Web Services (AWS) Elastic Block Storage (EBS)
 * Azure File
-
 * Google Compute Engine Persistent Disk (in-tree) and Google Cloud Platform Persistent Disk (CSI)
-
 * VMware vSphere
+|Techology Preview (TP)
+| No. To enable, see "_Manually enabling CSI automatic migration_".
+|===
 
-CSI automatic migration should be seamless. Enabling this feature does not change how you use all existing API objects (for example, `PersistentVolumes`, `PersistentVolumeClaims`, and `StorageClasses`).
-
-By default, automatic migration is disabled.
+CSI automatic migration should be seamless. This feature does not change how you use all existing API objects: for example, `PersistentVolumes`, `PersistentVolumeClaims`, and `StorageClasses`.
 
-[IMPORTANT]
-====
-CSI automatic migration will be enabled by default in a future {product-title} release, so it is highly recommended that you test it now and report any issues.
-====
+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 plug-in did not support it.

storage/container_storage_interface/persistent-storage-csi-migration.adoc

@@ -6,16 +6,21 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-{product-title} provides automatic migration for supported in-tree volume plug-ins to their equivalent Container Storage Interface (CSI) drivers.
-
-:FeatureName: CSI automatic migration
-include::snippets/technology-preview.adoc[leveloffset=+1]
+In-tree storage drivers that are traditionally shipped with {product-title} are being deprecated and replaced by their equivalent Container Storage Interface (CSI) drivers. {product-title} provides automatic migration for certain supported in-tree volume plug-ins to their equivalent CSI drivers.
 
 include::modules/persistent-storage-csi-migration-overview.adoc[leveloffset=+1]
 
+[role="_additional-resources"]
+.Additional resources
+* xref:../../storage/container_storage_interface/persistent-storage-csi-migration.adoc#persistent-storage-csi-migration-automatic-ga_persistent-storage-csi-migration[Automatic migration of in-tree volumes to CSI]
+
+* xref:../../storage/container_storage_interface/persistent-storage-csi-migration.adoc#persistent-storage-csi-migration-enable_persistent-storage-csi-migration[Manually enabling CSI automatic migration]
+
+include::modules/persistent-storage-csi-migration-automatic-ga.adoc[leveloffset=+1]
+
 include::modules/persistent-storage-csi-migration-enable.adoc[leveloffset=+1]
 
 [role="_additional-resources"]
-== Additional resources
+.Additional resources
 
 * xref:../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[Enabling features using feature gates]