OSDOCS-5006 & 5007:Automigration for Azure File and Vsphere

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

@@ -6,30 +6,19 @@
 [id="persistent-storage-csi-migration-overview_{context}"]
 = 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; {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.
+This feature automatically migrates volumes that were provisioned using in-tree storage plugins to their counterpart Container Storage Interface (CSI) drivers. 
 
-The following in-tree to CSI drivers are supported:
+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. CSI automatic migration should be seamless. This feature does not change how you use all existing API objects: for example, `PersistentVolumes`, `PersistentVolumeClaims`, and `StorageClasses`.
 
-.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?
+The following in-tree to CSI drivers are automatically migrated:
 
-a|
 * 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_".
-
-a|
 * Azure File
-* VMware vSphere
-|Technology Preview (TP)
-| No. To enable, see "_Manually enabling CSI automatic migration_".
-|===
+* VMware vSphere (see information below for specific migration behavior for vSphere)
 
-CSI automatic migration should be seamless. This feature does not change how you use all existing API objects: for example, `PersistentVolumes`, `PersistentVolumeClaims`, and `StorageClasses`.
+CSI migration for these volume types is considered generally available (GA), and requires no manual intervention.
 
-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.
+CSI automatic migration of 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.

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

@@ -0,0 +1,11 @@
+// Module included in the following assemblies:
+//
+// * storage/container_storage_interface/persistent-storage-csi-migration.adoc
+
+:_content-type: CONCEPT
+[id="persistent-storage-csi-migration-sc-implications_{context}"]
+= Storage class implications
+
+For new {product-title} 4.13, 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.12, and earlier, to 4.13, 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.

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

@@ -0,0 +1,86 @@
+// Module included in the following assemblies:
+//
+// * storage/container_storage_interface/persistent-storage-csi-migration.adoc
+
+:_content-type: CONCEPT
+[id="persistent-storage-csi-migration-sc-vsphere_{context}"]
+= vSphere automatic migration
+
+=== New installations of {product-title}
+For new installations of {product-title} 4.13, or later, automatic migration is enabled by default.
+
+=== Upgrading {product-title}
+When upgrading from {product-title} 4.12, or earlier, to 4.13, automatic CSI migration for vSphere only occurs if you opt in.
+
+[IMPORTANT]
+====
+Carefully review the following consequences before opting in to migration:
+
+* link:https://access.redhat.com/node/7011683[There are known issues that can occur that can cause the migration to fail].
+
+* Enabling migration cannot be undone.
+
+* Migration can take awhile to complete depending on how many nodes are on the cluster.
+
+* Migration is a disruptive process. The Machine Config Operator (MCO) has to update kubelet, which means degrading each node as it rolls out the new MachineConfig to each machine.  
+====
+
+==== Using the web console to opt in to automatic CSI migration
+
+===== Prerequisites
+
+* Access to the {product-title} web console.
+
+* Access to the cluster with cluster-admin privileges.
+
+===== Procedure
+
+To opt in to automatic CSI migration for vSphere:
+
+. Log in to the web console.
+
+. Click *Administration* -> *CustomResourceDefinitions*.
+
+. On the *CustomResourceDefinitions* page, type "Storage" to find the `Storage` custom resource (CR).
+
+. Click the *Storage* CR.
+
+. On the *storages.operator.openshift.io* page, click the *Instances* tab. 
+
+. Click the name of the desired instance, and then click the *YAML* tab.
+
+. Set the `spec.vsphereStorageDriver` parameter to `CSIWithMigrationDriver`, as shown in the following example:
++
+[source, yaml]
+----
+....
+spec:
+  logLevel: Normal
+  managementState: Managed
+  operatorLogLevel: Normal
+  vsphereStorageDriver: CSIWithMigrationDriver <1>
+...
+----
+<1> `spec.vsphereStorageDriver` parameter set to `CSIWithMigrationDriver`
+
+. Click *Save*.
+
+==== Using the CLI to opt in to automatic CSI migration
+
+===== Prerequisites
+
+* Access to the cluster with cluster-admin privileges.
+
+===== Procedure
+
+To opt in to automatic CSI migration for vSphere, run the following command:
+
+[source, cli]
+----
+oc patch storage cluster --type=merge -p '{"spec":{"vsphereStorageDriver":"CSIWithMigrationDriver"}}'
+----
+
+[NOTE]
+====
+You can determine when migration is complete by verifying that the `VSphereMigrationControllerAvailable` condition is set to "true" in the `Storage` object.
+====

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

@@ -22,11 +22,7 @@ include::modules/persistent-storage-csi-about.adoc[leveloffset=+1]
 
 [IMPORTANT]
 ====
-{product-title} defaults to using an in-tree (non-CSI) plugin to provision Azure Disk storage.
-
-In future {product-title} versions, volumes provisioned using existing in-tree plugins are planned for migration to their equivalent CSI driver. CSI automatic migration should be seamless. Migration does not change how you use all existing API objects, such as persistent volumes, persistent volume claims, and storage classes. For more information about migration, see xref:../../storage/container_storage_interface/persistent-storage-csi-migration.adoc#persistent-storage-csi-migration[CSI automatic migration].
-
-After full migration, in-tree plugins will eventually be removed in later versions of {product-title}.
+{product-title} defaults to using the CSI plugin to provision Azure Disk storage.
 ====
 
 include::modules/persistent-storage-csi-azure-disk-sc-zrs.adoc[leveloffset=+1]

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

@@ -25,11 +25,7 @@ include::modules/persistent-storage-csi-about.adoc[leveloffset=+1]
 
 [IMPORTANT]
 ====
-{product-title} defaults to using an in-tree (non-CSI) plugin to provision Cinder storage.
-
-In future {product-title} versions, volumes provisioned using existing in-tree plugins are planned for migration to their equivalent CSI driver. CSI automatic migration should be seamless. Migration does not change how you use all existing API objects, such as persistent volumes, persistent volume claims, and storage classes. For more information about migration, see xref:../../storage/container_storage_interface/persistent-storage-csi-migration.adoc#persistent-storage-csi-migration[CSI automatic migration].
-
-After full migration, in-tree plugins will eventually be removed in future versions of {product-title}.
+{product-title} defaults to using the CSI plugin to provision Cinder storage.
 ====
 
 include::modules/persistent-storage-csi-cinder-storage-class.adoc[leveloffset=+1]

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

@@ -29,14 +29,7 @@ include::modules/persistent-storage-csi-about.adoc[leveloffset=+1]
 
 [IMPORTANT]
 ====
-{product-title} defaults to using an in-tree (non-CSI) plugin to provision AWS EBS storage.
-
-In future {product-title} versions, volumes provisioned using existing in-tree plug-ins are planned for migration to their equivalent CSI driver. CSI automatic migration should be seamless. Migration does not change how you use all existing API objects, such as persistent volumes, persistent volume claims, and storage classes. 
-ifndef::openshift-rosa,openshift-dedicated[]
-For more information about migration, see xref:../../storage/container_storage_interface/persistent-storage-csi-migration.adoc#persistent-storage-csi-migration[CSI automatic migration].
-endif::openshift-rosa,openshift-dedicated[]
-
-After full migration, in-tree plugins will eventually be removed in future versions of {product-title}.
+{product-title} defaults to using the CSI plugin to provision AWS EBS storage.
 ====
 
 For information about dynamically provisioning AWS EBS persistent volumes in {product-title}, see xref:../../storage/persistent_storage/persistent-storage-aws.adoc#persistent-storage-aws[Persistent storage using AWS Elastic Block Store].

storage/container_storage_interface/persistent-storage-csi-gcp-pd.adoc

@@ -22,14 +22,7 @@ To create CSI-provisioned persistent volumes (PVs) that mount to GCP PD storage
 
 [IMPORTANT]
 ====
-{product-title} defaults to using an in-tree (non-CSI) plugin to provision GCP PD storage.
-
-In future {product-title} versions, volumes provisioned using existing in-tree plug-ins are planned for migration to their equivalent CSI driver. CSI automatic migration should be seamless. Migration does not change how you use all existing API objects, such as persistent volumes, persistent volume claims, and storage classes. 
-ifndef::openshift-dedicated[]
-For more information about migration, see xref:../../storage/container_storage_interface/persistent-storage-csi-migration.adoc#persistent-storage-csi-migration[CSI automatic migration].
-endif::openshift-dedicated[]
-
-After full migration, in-tree plugins will eventually be removed in future versions of {product-title}.
+{product-title} defaults to using the CSI plugin to provision GCP PD storage.
 ====
 
 include::modules/persistent-storage-csi-about.adoc[leveloffset=+1]

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

@@ -6,21 +6,11 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-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 plugins to their equivalent CSI drivers.
+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 in-tree volume plugins to their equivalent CSI drivers.
 
 include::modules/persistent-storage-csi-migration-overview.adoc[leveloffset=+1]
+include::modules/persistent-storage-csi-migration-sc.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]
+To change the default storage class, see xref:../../storage/container_storage_interface/persistent-storage-csi-sc-manage.adoc#change-default-storage-class_persistent-storage-csi-sc-manage[Changing the default storage class].
 
-* 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
-
-* xref:../../nodes/clusters/nodes-cluster-enabling-features.adoc#nodes-cluster-enabling[Enabling features using feature gates]
+include::modules/persistent-storage-csi-migration-vsphere.adoc[leveloffset=+1]

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

@@ -24,9 +24,13 @@ To create CSI-provisioned persistent volumes (PVs) that mount to vSphere storage
 
 [IMPORTANT]
 ====
-{product-title} defaults to using an in-tree (non-CSI) plugin to provision vSphere storage.
+For vSphere:
 
-In future {product-title} versions, volumes provisioned using existing in-tree plugins are planned for migration to their equivalent CSI driver. CSI automatic migration should be seamless. Migration does not change how you use all existing API objects, such as persistent volumes, persistent volume claims, and storage classes. For more information about migration, see xref:../../storage/container_storage_interface/persistent-storage-csi-migration.adoc#persistent-storage-csi-migration[CSI automatic migration].
+* For new installations of {product-title} 4.13, or later, automatic migration is enabled by default.
++
+CSI automatic migration should be seamless. Migration does not change how you use all existing API objects, such as persistent volumes, persistent volume claims, and storage classes. For more information about migration, see xref:../../storage/container_storage_interface/persistent-storage-csi-migration.adoc#persistent-storage-csi-migration[CSI automatic migration].
+
+* When upgrading from {product-title} 4.12, or earlier, to 4.13, automatic CSI migration for vSphere only occurs if you opt in. If you do not opt in, {product-title} defaults to using the in-tree (non-CSI) plugin to provision vSphere storage. xref:../../storage/container_storage_interface/persistent-storage-csi-migration.adoc#upgrading-openshift-container-platform[Carefully review the indicated consequences before opting in to migration].
 
 After full migration, in-tree plugins will eventually be removed in future versions of {product-title}.
 ====