Merge pull request #47093 from RichardHoch/state_only_mig_w_k8s_2

Description of state migration with Kubernetes resources (take 2)

Author: bergerhoffer

modules/migration-kubernetes-objects.adoc

@@ -5,9 +5,16 @@
 
 :_content-type: PROCEDURE
 [id="migration-kubernetes-objects_{context}"]
-= Migrating Kubernetes objects
+= Performing a state migration of Kubernetes objects by using the {mtc-short} API
 
-You can perform a one-time migration of Kubernetes objects that constitute an application's state.
+After you migrate all the PV data, you can use the Migration Toolkit for Containers (MTC) API to perform a one-time state migration of Kubernetes objects that constitute an application.
+
+You do this by configuring `MigPlan` custom resource (CR) fields to provide a list of Kubernetes resources with an additional label selector to further filter those resources, and then performing a migration by creating a `MigMigration` CR. The `MigPlan` resource is closed after the migration.
+
+[NOTE]
+====
+Selecting Kubernetes resources is an API-only feature. You must update the `MigPlan` CR and create a `MigMigration` CR for it by using the CLI. The {mtc-short} web console does not support migrating Kubernetes objects.
+====
 
 [NOTE]
 ====
@@ -16,13 +23,32 @@ After migration, the `closed` parameter of the `MigPlan` CR is set to `true`. Yo
 
 You add Kubernetes objects to the `MigPlan` CR by using one of the following options:
 
-* Adding the Kubernetes objects to the `includedResources` section.
-* Using the `labelSelector` parameter to reference labeled Kubernetes objects.
-* Adding Kubernetes objects to the `includedResources` section and then filtering them with the `labelSelector` parameter, for example, `Secret` and `ConfigMap` resources with the label `app: frontend`.
+* Adding the Kubernetes objects to the `includedResources` section. When the `includedResources` field is specified in the `MigPlan` CR, the plan takes a list of `group-kind` as input. Only resources present in the list are included in the migration.
+* Adding the optional `labelSelector` parameter to filter the `includedResources` in the `MigPlan`. When this field is specified, only resources matching the label selector are included in the migration. For example, you can filter a list of `Secret` and `ConfigMap` resources by using the label `app: frontend` as a filter.
 
 .Procedure
 
-* Update the `MigPlan` CR:
+. Update the `MigPlan` CR to include Kubernetes resources and, optionally, to filter the included resources by adding the `labelSelector` parameter:
+
+.. To update the `MigPlan` CR to include Kubernetes resources:
++
+[source,yaml]
+----
+apiVersion: migration.openshift.io/v1alpha1
+kind: MigPlan
+metadata:
+  name: <migplan>
+  namespace: openshift-migration
+spec:
+  includedResources:
+  - kind: <kind> <1>
+    group: ""
+  - kind: <kind>
+    group: ""
+----
+<1> Specify the Kubernetes object, for example, `Secret` or `ConfigMap`.
+
+.. Optional: To filter the included resources by adding the `labelSelector` parameter:
 +
 [source,yaml]
 ----
@@ -44,3 +70,19 @@ spec:
 ----
 <1> Specify the Kubernetes object, for example, `Secret` or `ConfigMap`.
 <2> Specify the label of the resources to migrate, for example, `app: frontend`.
+
+. Create a `MigMigration` CR to migrate the selected Kubernetes resources. Verify that the correct `MigPlan` is referenced in `migPlanRef`:
++
+[source,yaml]
+----
+apiVersion: migration.openshift.io/v1alpha1
+kind: MigMigration
+metadata:
+  generateName: <migplan>
+  namespace: openshift-migration
+spec:
+  migPlanRef:
+    name: <migplan>
+    namespace: openshift-migration
+  stage: false
+----