Skip to content

Commit ce6622e

Browse files
stevsmitstevsmit
authored
Merge pull request #73269 from anarnold97/MIG-1531-Direct-Migration-Requirements
MIG-1531: MTC docs missing Direct Migration Requirements
2 parents fd59976 + 0b5635a commit ce6622e

9 files changed

+363
-1
lines changed

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3188,6 +3188,8 @@ Topics:
31883188
File: premigration-checklists-mtc
31893189
- Name: Network considerations
31903190
File: network-considerations-mtc
3191+
- Name: Direct Migration Requirements
3192+
File: mtc-direct-migration-requirements
31913193
- Name: Migrating your applications
31923194
File: migrating-applications-with-mtc
31933195
- Name: Advanced migration options

‎migration_toolkit_for_containers/installing-mtc.adoc

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,9 @@ include::modules/migration-configuring-proxies.adoc[leveloffset=+2]
2828

2929
For more information, see xref:../networking/enable-cluster-wide-proxy.adoc#nw-proxy-configure-object_config-cluster-wide-proxy[Configuring the cluster-wide proxy].
3030

31+
include::modules/ocp-running-rsync-root-or-non-root.adoc[leveloffset=+2]
32+
33+
////
3134
[id="migration-rsync-root-non-root_{context}"]
3235
=== Running Rsync as either root or non-root
3336

@@ -47,7 +50,8 @@ Although running Rsync pods as non-root user works in most cases, data transfer
4750
* Configure all migrations to run an Rsync pod as root on the destination cluster for all migrations.
4851
* Run an Rsync pod as root on the destination cluster per migration.
4952

50-
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.`
53+
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.`
54+
////
5155
5256
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].
5357

‎migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
:_mod-docs-content-type: ASSEMBLY
2+
[id="mtc-direct-migration-requirements"]
3+
= Direct Migration Requirements
4+
include::_attributes/common-attributes.adoc[]
5+
include::_attributes/attributes-openshift-dedicated.adoc[]
6+
:context: mtc-direct-migration-requirements
7+
:mtc-direct-migration-requirements:
8+
9+
toc::[]
10+
11+
Direct Migration is available with {mtc-full} ({mtc-short}) 1.4.0 or later.
12+
13+
There are two parts of the Direct Migration:
14+
15+
* Direct Volume Migration
16+
17+
* Direct Image Migration
18+
19+
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).
20+
21+
== Prerequisites
22+
23+
* Expose the internal registries for both clusters (source and destination) involved in the migration for external traffic.
24+
25+
* Ensure the remote source and destination clusters can communicate using {OCP} routes on port 443.
26+
27+
* 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.
28+
+
29+
[NOTE]
30+
====
31+
* 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.
32+
33+
* The `spec.exposedRegistryPath` is required only for Direct Image Migration and not Direct Volume Migration.
34+
====
35+
36+
* 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`.
37+
38+
39+
The Direct Migration feature of {mtc-short} uses the Rsync utility.
40+
41+
include::modules/configuring-rsync-for-direct-volume-migration.adoc[leveloffset=+1]
42+
43+
include::modules/configuring-resource-limits-on-rsync-pods.adoc[leveloffset=+2]
44+
45+
include::modules/configuring-supplemental-groups-for-rsync-pods.adoc[leveloffset=+3]
46+
47+
include::modules/configuring-retries-for-rsync.adoc[leveloffset=+3]
48+
49+
include::modules/ocp-running-rsync-root-or-non-root.adoc[leveloffset=+3]
50+
51+
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].
52+
53+
include::modules/migration-rsync-migration-controller-root-non-root.adoc[leveloffset=+3]
54+
55+
include::modules/migration-rsync-mig-migration-root-non-root.adoc[leveloffset=+3]
56+
57+
include::modules/mtc-mig-cluster-configuration.adoc[leveloffset=+2]
58+
59+
:!mtc-direct-migration-requirements:

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

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
// Module included in the following assemblies:
2+
//
3+
// migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="configuring-resource-limits-on-rsync-pods_{context}"]
7+
= Resource limit configurations for Rsync pods
8+
9+
The `MigrationController` CR exposes following variables to configure resource usage requirements and limits on Rsync:
10+
11+
[width="100%",cols="30%,15%,15%,40%",options="header",]
12+
|===
13+
|Variable
14+
|Type
15+
|Default
16+
|Description
17+
18+
|`source_rsync_pod_cpu_limits`
19+
|string
20+
|`1`
21+
|Source rsync pod’s CPU limit
22+
23+
|`source_rsync_pod_memory_limits`
24+
|string
25+
|`1Gi`
26+
|Source rsync pod’s memory limit
27+
28+
|`source_rsync_pod_cpu_requests`
29+
|string
30+
|`400m`
31+
|Source rsync pod’s cpu requests
32+
33+
|`source_rsync_pod_memory_requests`
34+
|string
35+
|`1Gi`
36+
|Source rsync pod’s memory requests
37+
38+
|`target_rsync_pod_cpu_limits`
39+
|string
40+
|`1`
41+
|Target rsync pod’s cpu limit
42+
43+
|`target_rsync_pod_cpu_requests`
44+
|string
45+
|`400m`
46+
|Target rsync pod’s cpu requests
47+
48+
|`target_rsync_pod_memory_limits`
49+
|string
50+
|`1Gi`
51+
|Target rsync pod’s memory limit
52+
53+
|`target_rsync_pod_memory_requests`
54+
|string
55+
|`1Gi`
56+
|Target rsync pod’s memory requests
57+
58+
|===

‎modules/configuring-retries-for-rsync.adoc

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
// Module included in the following assemblies:
2+
//
3+
// migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="configuring-retries-for-rsync_{context}"]
7+
= Rsync retry configuration
8+
9+
With MTC 1.4.3 and later, a new ability of retrying a failed Rsync operation is introduced.
10+
11+
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+`.
12+
13+
For larger volumes, a limit of `+20+` retries may not be sufficient.
14+
15+
You can increase the retry limit by using the following variable in the `MigrationController` CR:
16+
17+
[source,yaml]
18+
----
19+
apiVersion: migration.openshift.io/v1alpha1
20+
kind: MigrationController
21+
metadata:
22+
name: migration-controller
23+
namespace: openshift-migration
24+
spec:
25+
[...]
26+
rsync_backoff_limit: 40
27+
----
28+
29+
In this example, the retry limit is increased to `40`.

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

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
// Module included in the following assemblies:
2+
//
3+
// migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="configuring-rsync-for-direct-volume-migration_{context}"]
7+
= Rsync configuration for direct volume migration
8+
9+
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.
10+
11+
Rsync is a command-line tool that allows you to transfer files and directories to local and remote destinations.
12+
13+
The `rsync` command used by DVM is optimized for clusters functioning as expected.
14+
15+
The `MigrationController` CR exposes the following variables to configure `rsync_options` in Direct Volume Migration:
16+
17+
[width="100%",cols="15%,15%,20%,50%",options="header",]
18+
|===
19+
|Variable
20+
|Type
21+
|Default value
22+
|Description
23+
24+
|`rsync_opt_bwlimit`
25+
|int
26+
|Not set
27+
|When set to a positive integer, `+--bwlimit=<int>+` option is added to Rsync command.
28+
29+
|`rsync_opt_archive`
30+
|bool
31+
|`true`
32+
|Sets the `+--archive+` option in the Rsync command.
33+
34+
|`rsync_opt_partial`
35+
|bool
36+
|`true`
37+
|Sets the `+--partial+` option in the Rsync command.
38+
39+
|`rsync_opt_delete`
40+
|bool
41+
|`true`
42+
|Sets the `+--delete+` option in the Rsync command.
43+
44+
|`rsync_opt_hardlinks`
45+
|bool
46+
|`true`
47+
|Sets the `+--hard-links+` option is the Rsync command.
48+
49+
|`rsync_opt_info`
50+
|string
51+
|`COPY2`
52+
53+
`DEL2`
54+
55+
`REMOVE2`
56+
57+
`SKIP2`
58+
59+
`FLIST2`
60+
61+
`PROGRESS2`
62+
63+
`STATS2`
64+
|Enables detailed logging in Rsync Pod.
65+
66+
|`rsync_opt_extras`
67+
|string
68+
|Empty
69+
|Reserved for any other arbitrary options.
70+
|===
71+
72+
* 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.
73+
74+
* 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.
75+
76+
* 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.
77+
78+
[NOTE]
79+
====
80+
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.
81+
These configuration variables should be used in case the default settings do not work and the Rsync operation fails.
82+
====

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

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// Module included in the following assemblies:
2+
//
3+
// migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="configuring-supplemental-groups-for-rsync-pods_{context}"]
7+
= Supplemental group configuration for Rsync pods
8+
9+
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:
10+
11+
[width="100%",cols="15%,10%,10%,55%",options="header",]
12+
|===
13+
|Variable
14+
|Type
15+
|Default
16+
|Description
17+
18+
|`src_supplemental_groups`
19+
|string
20+
|Not Set
21+
|Comma separated list of supplemental groups for source Rsync pods
22+
23+
|`target_supplemental_groups`
24+
|string
25+
|Not Set
26+
|Comma separated list of supplemental groups for target Rsync Pods
27+
|===
28+
29+
For example, the `MigrationController` CR can be updated to set the previous values:
30+
31+
[source,yaml]
32+
----
33+
spec:
34+
src_supplemental_groups: "1000,2000"
35+
target_supplemental_groups: "2000,3000"
36+
----

‎modules/mtc-mig-cluster-configuration.adoc

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
// Module included in the following assemblies:
2+
//
3+
// migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="mtc-mig-cluster-configuration_{context}"]
7+
= MigCluster Configuration
8+
9+
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. 
10+
11+
The `migration-cluster-config` allows you to configure MigCluster specific values. The Migration Operator manages the `migration-cluster-config`. 
12+
13+
You can configure every value in the `ConfigMap` using the variables exposed in the `MigrationController` CR:
14+
15+
[width="100%",cols="30%,10%,10%,50%",options="header",]
16+
|===
17+
|Variable
18+
|Type
19+
|Required
20+
|Description
21+
22+
|`migration_stage_image_fqin`
23+
|string
24+
|No
25+
|Image to use for Stage Pods (applicable only to IndirectVolumeMigration)
26+
27+
|`migration_registry_image_fqin`
28+
|string
29+
|No
30+
|Image to use for Migration Registry
31+
32+
|`rsync_endpoint_type`
33+
|string
34+
|No
35+
|Type of endpoint for data transfer (`Route`, `ClusterIP`, `NodePort`)
36+
37+
|`rsync_transfer_image_fqin`
38+
|string
39+
|No
40+
|Image to use for Rsync Pods (applicable only to DirectVolumeMigration)
41+
42+
|`migration_rsync_privileged`
43+
|bool
44+
|No
45+
|Whether to run Rsync Pods as privileged or not
46+
47+
|`migration_rsync_super_privileged`
48+
|bool
49+
|No
50+
|Whether to run Rsync Pods as super privileged containers (`spc_t` SELinux context) or not
51+
52+
|`cluster_subdomain`
53+
|string
54+
|No
55+
|Cluster’s subdomain
56+
57+
|`migration_registry_readiness_timeout`
58+
|int
59+
|No
60+
|Readiness timeout (in seconds) for Migration Registry Deployment
61+
62+
|`migration_registry_liveness_timeout`
63+
|int
64+
|No
65+
|Liveness timeout (in seconds) for Migration Registry Deployment
66+
67+
|`exposed_registry_validation_path`
68+
|string
69+
|No
70+
|Subpath to validate exposed registry in a MigCluster (for example /v2)
71+
|===

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

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
// Module included in the following assemblies:
2+
//
3+
// migration_toolkit_for_containers/mtc-direct-migration-requirements.adoc
4+
5+
:_mod-docs-content-type: CONCEPT
6+
[id="ocp-running-rsync-root-or-non-root_{context}"]
7+
= Running Rsync as either root or non-root
8+
9+
{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.
10+
11+
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.
12+
13+
[id="manually-overriding-default-nonroot-operation_{context}"]
14+
== Manually overriding default non-root operation for data transfer
15+
16+
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:
17+
18+
* Configure all migrations to run an Rsync pod as root on the destination cluster for all migrations.
19+
* Run an Rsync pod as root on the destination cluster per migration.
20+
21+
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.`

0 commit comments

Comments
 (0)