[enterprise-4.16] MIG-1531: MTC docs missing Direct Migration Requirements

_topic_maps/_topic_map.yml

@@ -3187,6 +3187,8 @@ Topics:
   File: premigration-checklists-mtc
 - Name: Network considerations
   File: network-considerations-mtc
+- Name: Direct Migration Requirements
+  File: mtc-direct-migration-requirements
 - Name: Migrating your applications
   File: migrating-applications-with-mtc
 - Name: Advanced migration options

migration_toolkit_for_containers/installing-mtc.adoc

@@ -28,6 +28,9 @@ include::modules/migration-configuring-proxies.adoc[leveloffset=+2]
 
 For more information, see xref:../networking/enable-cluster-wide-proxy.adoc#nw-proxy-configure-object_config-cluster-wide-proxy[Configuring the cluster-wide proxy].
 
+include::modules/ocp-running-rsync-root-or-non-root.adoc[leveloffset=+2]
+
+////
 [id="migration-rsync-root-non-root_{context}"]
 === Running Rsync as either root or non-root
 
@@ -47,7 +50,8 @@ Although running Rsync pods as non-root user works in most cases, data transfer
 * Configure all migrations to run an Rsync pod as root on the destination cluster for all migrations.
 * Run an Rsync pod as root on the destination cluster per migration.
 
-In both cases, you must set the following labels on the source side of any namespaces that are running workloads with higher privileges prior to migration: `enforce`, `audit`, and `warn.`
+In both cases, you must set the following labels on the source side of any namespaces that are running workloads with higher privileges before the migration: `enforce`, `audit`, and `warn.`
+////
 
 To learn more about Pod Security Admission and setting values for labels, see xref:../authentication/understanding-and-managing-pod-security-admission.adoc#security-context-constraints-psa-opting_understanding-and-managing-pod-security-admission[Controlling pod security admission synchronization].
 

migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc

@@ -0,0 +1,59 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="mtc-direct-migration-requirements"]
+= Direct Migration Requirements
+include::_attributes/common-attributes.adoc[]
+include::_attributes/attributes-openshift-dedicated.adoc[]
+:context: mtc-direct-migration-requirements
+:mtc-direct-migration-requirements:
+
+toc::[]
+
+Direct Migration is available with {mtc-full} ({mtc-short}) 1.4.0 or later.
+
+There are two parts of the Direct Migration:
+
+* Direct Volume Migration
+
+* Direct Image Migration
+
+Direct Migration enables the migration of persistent volumes and internal images directly from the source cluster to the destination cluster without an intermediary replication repository (object storage).
+
+== Prerequisites
+
+* Expose the internal registries for both clusters (source and destination) involved in the migration for external traffic.
+
+* Ensure the remote source and destination clusters can communicate using {OCP} routes on port 443.
+
+* Configure the exposed registry route in the source and destination {mtc-short} clusters; do this by specifying the `spec.exposedRegistryPath` field or from the {mtc-short} UI.
++
+[NOTE]
+====
+* If the destination cluster is the same as the host cluster (where a migration controller exists), there is no need to configure the exposed registry route for that particular {mtc-short} cluster.
+
+* The `spec.exposedRegistryPath` is required only for Direct Image Migration and not Direct Volume Migration.
+====
+
+* Ensure the two spec flags in `MigPlan` custom resource (CR) `indirectImageMigration` and `indirectVolumeMigration` are set to `false` for Direct Migration to be performed. The default value for these flags is `false`.
+
+
+The Direct Migration feature of {mtc-short} uses the Rsync utility.
+
+include::modules/configuring-rsync-for-direct-volume-migration.adoc[leveloffset=+1]
+
+include::modules/configuring-resource-limits-on-rsync-pods.adoc[leveloffset=+2]
+
+include::modules/configuring-supplemental-groups-for-rsync-pods.adoc[leveloffset=+3]
+
+include::modules/configuring-retries-for-rsync.adoc[leveloffset=+3]
+
+include::modules/ocp-running-rsync-root-or-non-root.adoc[leveloffset=+3]
+
+To learn more about Pod Security Admission and setting values for labels, see xref:../authentication/understanding-and-managing-pod-security-admission.adoc#security-context-constraints-psa-opting_understanding-and-managing-pod-security-admission[Controlling pod security admission synchronization].
+
+include::modules/migration-rsync-migration-controller-root-non-root.adoc[leveloffset=+3]
+
+include::modules/migration-rsync-mig-migration-root-non-root.adoc[leveloffset=+3]
+
+include::modules/mtc-mig-cluster-configuration.adoc[leveloffset=+2]
+
+:!mtc-direct-migration-requirements:

modules/configuring-resource-limits-on-rsync-pods.adoc

@@ -0,0 +1,58 @@
+// Module included in the following assemblies:
+//
+// migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="configuring-resource-limits-on-rsync-pods_{context}"]
+= Resource limit configurations for Rsync pods
+
+The `MigrationController` CR exposes following variables to configure resource usage requirements and limits on Rsync:
+
+[width="100%",cols="30%,15%,15%,40%",options="header",]
+|===
+|Variable
+|Type
+|Default
+|Description
+
+|`source_rsync_pod_cpu_limits`
+|string
+|`1`
+|Source rsync pod’s CPU limit
+
+|`source_rsync_pod_memory_limits`
+|string
+|`1Gi`
+|Source rsync pod’s memory limit
+
+|`source_rsync_pod_cpu_requests`
+|string
+|`400m`
+|Source rsync pod’s cpu requests
+
+|`source_rsync_pod_memory_requests`
+|string
+|`1Gi`
+|Source rsync pod’s memory requests
+
+|`target_rsync_pod_cpu_limits`
+|string
+|`1`
+|Target rsync pod’s cpu limit
+
+|`target_rsync_pod_cpu_requests`
+|string
+|`400m`
+|Target rsync pod’s cpu requests
+
+|`target_rsync_pod_memory_limits`
+|string
+|`1Gi`
+|Target rsync pod’s memory limit
+
+|`target_rsync_pod_memory_requests`
+|string
+|`1Gi`
+|Target rsync pod’s memory requests
+
+|===

modules/configuring-retries-for-rsync.adoc

@@ -0,0 +1,29 @@
+// Module included in the following assemblies:
+//
+// migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="configuring-retries-for-rsync_{context}"]
+= Rsync retry configuration
+
+With MTC 1.4.3 and later, a new ability of retrying a failed Rsync operation is introduced.
+
+By default, the migration controller retries Rsync until all of the data is successfully transferred from the source to the target volume or a specified number of retries is met. The default retry limit is set to `+20+`.
+
+For larger volumes, a limit of `+20+` retries may not be sufficient.
+
+You can increase the retry limit by using the following variable in the `MigrationController` CR:
+
+[source,yaml]
+----
+apiVersion: migration.openshift.io/v1alpha1
+kind: MigrationController
+metadata:
+  name: migration-controller
+  namespace: openshift-migration
+spec:
+  [...]
+  rsync_backoff_limit: 40
+----
+
+In this example, the retry limit is increased to `40`.

modules/configuring-rsync-for-direct-volume-migration.adoc

@@ -0,0 +1,82 @@
+// Module included in the following assemblies:
+//
+// migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="configuring-rsync-for-direct-volume-migration_{context}"]
+= Rsync configuration for direct volume migration
+
+Direct Volume Migration (DVM) in {mtc-short} uses Rsync to synchronize files between the source and the target persistent volumes (PVs), using a direct connection between the two PVs.
+
+Rsync is a command-line tool that allows you to transfer files and directories to local and remote destinations.
+
+The `rsync` command used by DVM is optimized for clusters functioning as expected.
+
+The `MigrationController` CR exposes the following variables to configure `rsync_options` in Direct Volume Migration:
+
+[width="100%",cols="15%,15%,20%,50%",options="header",]
+|===
+|Variable
+|Type
+|Default value
+|Description
+
+|`rsync_opt_bwlimit`
+|int
+|Not set
+|When set to a positive integer, `+--bwlimit=<int>+` option is added to Rsync command.
+
+|`rsync_opt_archive`
+|bool
+|`true`
+|Sets the `+--archive+` option in the Rsync command.
+
+|`rsync_opt_partial`
+|bool
+|`true`
+|Sets the `+--partial+` option in the Rsync command.
+
+|`rsync_opt_delete`
+|bool
+|`true`
+|Sets the `+--delete+` option in the Rsync command.
+
+|`rsync_opt_hardlinks`
+|bool
+|`true`
+|Sets the `+--hard-links+` option is the Rsync command.
+
+|`rsync_opt_info`
+|string
+|`COPY2`
+
+ `DEL2`
+
+ `REMOVE2`
+
+ `SKIP2`
+
+ `FLIST2`
+
+ `PROGRESS2`
+
+ `STATS2`
+|Enables detailed logging in Rsync Pod.
+
+|`rsync_opt_extras`
+|string
+|Empty
+|Reserved for any other arbitrary options.
+|===
+
+* Setting the options set through the variables above are _global_ for all migrations. The configuration will take effect for all future migrations as soon as the Operator successfully reconciles the `MigrationController` CR. Any ongoing migration can use the updated settings depending on which step it currently is in. Therefore, it is recommended that the settings be applied before running a migration. The users can always update the settings as needed.
+
+* Use the `rsync_opt_extras` variable with caution. Any options passed using this variable are appended to the `rsync` command, with addition. Ensure you add white spaces when specifying more than one option. Any error in specifying options can lead to a failed migration. However, you can update `MigrationController` CR as many times as you require for future migrations.
+
+* Customizing the `rsync_opt_info` flag can adversely affect the progress reporting capabilities in {mtc-short}. However, removing progress reporting can have a performance advantage. This option should only be used when the performance of Rsync operation is observed to be unacceptable.
+
+[NOTE]
+====
+The default configuration used by DVM is tested in various environments. It is acceptable for most production use cases provided the clusters are healthy and performing well.
+These configuration variables should be used in case the default settings do not work and the Rsync operation fails.
+====

modules/configuring-supplemental-groups-for-rsync-pods.adoc

@@ -0,0 +1,36 @@
+// Module included in the following assemblies:
+//
+// migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="configuring-supplemental-groups-for-rsync-pods_{context}"]
+= Supplemental group configuration for Rsync pods
+
+If Persistent Volume Claims (PVC) are using a shared storage, the access to storage can be configured by adding supplemental groups to Rsync pod definitions in order for the pods to allow access:
+
+[width="100%",cols="15%,10%,10%,55%",options="header",]
+|===
+|Variable
+|Type
+|Default
+|Description
+
+|`src_supplemental_groups`
+|string
+|Not Set
+|Comma separated list of supplemental groups for source Rsync pods
+
+|`target_supplemental_groups`
+|string
+|Not Set
+|Comma separated list of supplemental groups for target Rsync Pods
+|===
+
+For example, the `MigrationController` CR can be updated to set the previous values:
+
+[source,yaml]
+----
+spec:
+  src_supplemental_groups: "1000,2000"
+  target_supplemental_groups: "2000,3000"
+----

modules/mtc-mig-cluster-configuration.adoc

@@ -0,0 +1,71 @@
+// Module included in the following assemblies:
+//
+// migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="mtc-mig-cluster-configuration_{context}"]
+= MigCluster Configuration
+
+For every `MigCluster` resource created in MTC, a `ConfigMap` named `migration-cluster-config` is created in the Migration Operator's namespace on the cluster which MigCluster resource represents. 
+
+The `migration-cluster-config` allows you to configure MigCluster specific values. The Migration Operator manages the `migration-cluster-config`. 
+
+You can configure every value in the `ConfigMap` using the variables exposed in the `MigrationController` CR:
+
+[width="100%",cols="30%,10%,10%,50%",options="header",]
+|===
+|Variable
+|Type
+|Required
+|Description
+
+|`migration_stage_image_fqin`
+|string
+|No
+|Image to use for Stage Pods (applicable only to IndirectVolumeMigration)
+
+|`migration_registry_image_fqin`
+|string
+|No
+|Image to use for Migration Registry
+
+|`rsync_endpoint_type`
+|string
+|No
+|Type of endpoint for data transfer (`Route`, `ClusterIP`, `NodePort`)
+
+|`rsync_transfer_image_fqin`
+|string
+|No
+|Image to use for Rsync Pods (applicable only to DirectVolumeMigration)
+
+|`migration_rsync_privileged`
+|bool
+|No
+|Whether to run Rsync Pods as privileged or not
+
+|`migration_rsync_super_privileged`
+|bool
+|No
+|Whether to run Rsync Pods as super privileged containers (`spc_t` SELinux context) or not
+
+|`cluster_subdomain`
+|string
+|No
+|Cluster’s subdomain
+
+|`migration_registry_readiness_timeout`
+|int
+|No
+|Readiness timeout (in seconds) for Migration Registry Deployment
+
+|`migration_registry_liveness_timeout`
+|int
+|No
+|Liveness timeout (in seconds) for Migration Registry Deployment
+
+|`exposed_registry_validation_path`
+|string
+|No
+|Subpath to validate exposed registry in a MigCluster (for example /v2)
+|===

modules/ocp-running-rsync-root-or-non-root.adoc

@@ -0,0 +1,21 @@
+// Module included in the following assemblies:
+//
+// migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc
+
+:_mod-docs-content-type: CONCEPT
+[id="ocp-running-rsync-root-or-non-root_{context}"]
+= Running Rsync as either root or non-root
+
+{OCP} environments have the `PodSecurityAdmission` controller enabled by default. This controller requires cluster administrators to enforce Pod Security Standards by means of namespace labels. All workloads in the cluster are expected to run one of the following Pod Security Standard levels: `Privileged`, `Baseline` or `Restricted`. Every cluster has its own default policy set.
+
+To guarantee successful data transfer in all environments, {mtc-full} ({mtc-short}) 1.7.5 introduced changes in Rsync pods, including running Rsync pods as non-root user by default. This ensures that data transfer is possible even for workloads that do not necessarily require higher privileges. This change was made because it is best to run workloads with the lowest level of privileges possible.
+
+[id="manually-overriding-default-nonroot-operation_{context}"]
+== Manually overriding default non-root operation for data transfer
+
+Although running Rsync pods as non-root user works in most cases, data transfer might fail when you run workloads as root user on the source side. {mtc-short} provides two ways to manually override default non-root operation for data transfer:
+
+* Configure all migrations to run an Rsync pod as root on the destination cluster for all migrations.
+* Run an Rsync pod as root on the destination cluster per migration.
+
+In both cases, you must set the following labels on the source side of any namespaces that are running workloads with higher privileges before migration: `enforce`, `audit`, and `warn.`