Merge pull request #64470 from ShaunaDiaz/OSDOCS-7070

OSDOCS-7070: update storage migration controller

Author: opayne1

_topic_maps/_topic_map_ms.yml

@@ -154,6 +154,8 @@ Topics:
   File: microshift-storage-plugin-overview
 - Name: Working with volume snapshots
   File: volume-snapshots-microshift
+- Name: Understanding storage migration
+  File: microshift-storage-migration
 ---
 Name: Running applications
 Dir: microshift_running_apps

microshift_rest_api/understanding-compatibility-guidelines.adoc

@@ -6,6 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+Follow the compatibility guidelines to understand the APIs enabled for {product-title}.
+
 [IMPORTANT]
 ====
 This guidance does not cover layered {product-title} offerings.

microshift_storage/microshift-storage-migration.adoc

@@ -0,0 +1,11 @@
+:_content-type: ASSEMBLY
+[id="microshift-storage-migration"]
+= Storage migration using the Kube Storage Version Migrator
+include::_attributes/attributes-microshift.adoc[]
+:context: microshift-storage-plugin-overview
+
+toc::[]
+
+Storage version migration is used to update existing objects in the cluster from their current version to the latest version. The Kube Storage Version Migrator embedded controller is used in {product-title} to migrate resources without having to recreate those resources. Either you or a controller can create a `StorageVersionMigration` custom resource (CR) that will request a migration through the Migrator Controller.
+
+include::modules/microshift-making-storage-migration-request.adoc[leveloffset=+1]

modules/microshift-making-storage-migration-request.adoc

@@ -0,0 +1,38 @@
+// Module included in the following assemblies:
+//
+// * microshift_storage/microshift-storage-migration.adoc
+
+:_content-type: PROCEDURE
+[id="microshift-making-storage-migration-request_{context}"]
+= Making a storage migration request
+
+Storage migration is the process of updating stored data to the latest storage version, for example from `v1beta1` to `v1beta2`. To update your storage version, use the following procedure.
+
+.Procedure
+
+* Either you or any controller that has support for the `StorageVersionMigration` API must trigger a migration request. Use the following example request for reference:
++
+.Example request
++
+[source,terminal]
+----
+apiVersion: migration.k8s.io/v1alpha1
+kind: StorageVersionMigration
+metadata:
+  name: snapshot-v1
+spec:
+  resource:
+    group: snapshot.storage.k8s.io
+    resource: volumesnapshotclasses <1>
+    version: v1 <2>
+----
+<1> You must use the plural name of the resource.
+<2> Version being updated to.
+
+*  The progress of the migration is posted to the `StorageVersionMigration` status.
+
+[NOTE]
+====
+* Failures can occur because of a misnamed group or resource.
+* Migration failures can also occur when there is an incompatibility between the previous and latest versions.
+====

rest_api/workloads_apis/persistentvolume-core-v1.adoc

@@ -305,7 +305,7 @@ Defaults to unset
 | Parameter | Type | Description
 | `body`
 | xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`]
-| 
+|
 |===
 
 .HTTP responses
@@ -398,7 +398,7 @@ Description::
 | Parameter | Type | Description
 | `body`
 | xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`]
-| 
+|
 |===
 
 .HTTP responses
@@ -461,7 +461,7 @@ Description::
 | Parameter | Type | Description
 | `body`
 | xref:../objects/index.adoc#deleteoptions-meta-v1[`DeleteOptions meta/v1`]
-| 
+|
 |===
 
 .HTTP responses
@@ -515,7 +515,7 @@ Description::
 | Parameter | Type | Description
 | `body`
 | xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`]
-| 
+|
 |===
 
 .HTTP responses
@@ -551,7 +551,7 @@ Description::
 | Parameter | Type | Description
 | `body`
 | xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`]
-| 
+|
 |===
 
 .HTTP responses
@@ -626,7 +626,7 @@ Description::
 | Parameter | Type | Description
 | `body`
 | xref:../objects/index.adoc#patch-meta-v1[`Patch meta/v1`]
-| 
+|
 |===
 
 .HTTP responses
@@ -662,7 +662,7 @@ Description::
 | Parameter | Type | Description
 | `body`
 | xref:../workloads_apis/persistentvolume-core-v1.adoc#persistentvolume-core-v1[`PersistentVolume core/v1`]
-| 
+|
 |===
 
 .HTTP responses