From 8a435a8d4bc806e0e46af165dfddd7be8614978b Mon Sep 17 00:00:00 2001 From: RichardHoch Date: Mon, 9 May 2022 11:18:26 +0300 Subject: [PATCH] Document downstream network policy configuration compatibility with DVM --- .../advanced-migration-options-3-4.adoc | 3 +- migrating_from_ocp_3_to_4/installing-3-4.adoc | 3 +- .../installing-restricted-3-4.adoc | 3 +- .../advanced-migration-options-mtc.adoc | 3 +- .../installing-mtc-restricted.adoc | 3 +- .../installing-mtc.adoc | 3 +- .../migration-about-configuring-proxies.adoc | 133 ++++++++++++++++++ modules/migration-configuring-proxies.adoc | 20 +-- 8 files changed, 147 insertions(+), 24 deletions(-) create mode 100644 modules/migration-about-configuring-proxies.adoc diff --git a/migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc b/migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc index 512ecd9dc2..e7962ab751 100644 --- a/migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc +++ b/migrating_from_ocp_3_to_4/advanced-migration-options-3-4.adoc @@ -25,7 +25,8 @@ You can migrate applications with the {mtc-short} API by using the command line include::modules/migration-prerequisites.adoc[leveloffset=+2] include::modules/migration-creating-registry-route-for-dim.adoc[leveloffset=+2] -include::modules/migration-configuring-proxies.adoc[leveloffset=+2] +include::modules/migration-about-configuring-proxies.adoc[leveloffset=+2] +include::modules/migration-configuring-proxies.adoc[leveloffset=+3] include::modules/migration-migrating-applications-api.adoc[leveloffset=+2] include::modules/migration-state-migration-cli.adoc[leveloffset=+2] diff --git a/migrating_from_ocp_3_to_4/installing-3-4.adoc b/migrating_from_ocp_3_to_4/installing-3-4.adoc index f210be3114..f22b2e7ce4 100644 --- a/migrating_from_ocp_3_to_4/installing-3-4.adoc +++ b/migrating_from_ocp_3_to_4/installing-3-4.adoc @@ -20,7 +20,8 @@ To uninstall {mtc-short}, see xref:../migrating_from_ocp_3_to_4/installing-3-4.a include::modules/migration-compatibility-guidelines.adoc[leveloffset=+1] include::modules/migration-installing-legacy-operator.adoc[leveloffset=+1] include::modules/migration-installing-mtc-on-ocp-4.adoc[leveloffset=+1] -include::modules/migration-configuring-proxies.adoc[leveloffset=+1] +include::modules/migration-about-configuring-proxies.adoc[leveloffset=+1] +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]. diff --git a/migrating_from_ocp_3_to_4/installing-restricted-3-4.adoc b/migrating_from_ocp_3_to_4/installing-restricted-3-4.adoc index 23dadc401a..2f26cd5426 100644 --- a/migrating_from_ocp_3_to_4/installing-restricted-3-4.adoc +++ b/migrating_from_ocp_3_to_4/installing-restricted-3-4.adoc @@ -24,7 +24,8 @@ To uninstall {mtc-short}, see xref:../migrating_from_ocp_3_to_4/installing-restr include::modules/migration-compatibility-guidelines.adoc[leveloffset=+1] include::modules/migration-installing-mtc-on-ocp-4.adoc[leveloffset=+1] include::modules/migration-installing-legacy-operator.adoc[leveloffset=+1] -include::modules/migration-configuring-proxies.adoc[leveloffset=+1] +include::modules/migration-about-configuring-proxies.adoc[leveloffset=+1] +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]. diff --git a/migration_toolkit_for_containers/advanced-migration-options-mtc.adoc b/migration_toolkit_for_containers/advanced-migration-options-mtc.adoc index a52824891f..65b150a366 100644 --- a/migration_toolkit_for_containers/advanced-migration-options-mtc.adoc +++ b/migration_toolkit_for_containers/advanced-migration-options-mtc.adoc @@ -17,7 +17,8 @@ You can migrate applications with the {mtc-short} API by using the command line include::modules/migration-prerequisites.adoc[leveloffset=+2] include::modules/migration-creating-registry-route-for-dim.adoc[leveloffset=+2] -include::modules/migration-configuring-proxies.adoc[leveloffset=+2] +include::modules/migration-about-configuring-proxies.adoc[leveloffset=+2] +include::modules/migration-configuring-proxies.adoc[leveloffset=+3] include::modules/migration-migrating-applications-api.adoc[leveloffset=+2] include::modules/migration-state-migration-cli.adoc[leveloffset=+2] diff --git a/migration_toolkit_for_containers/installing-mtc-restricted.adoc b/migration_toolkit_for_containers/installing-mtc-restricted.adoc index 4efb3efe72..d61d9a6e0a 100644 --- a/migration_toolkit_for_containers/installing-mtc-restricted.adoc +++ b/migration_toolkit_for_containers/installing-mtc-restricted.adoc @@ -32,7 +32,8 @@ To uninstall {mtc-short}, see xref:../migration_toolkit_for_containers/installin include::modules/migration-compatibility-guidelines.adoc[leveloffset=+1] include::modules/migration-installing-mtc-on-ocp-4.adoc[leveloffset=+1] include::modules/migration-installing-legacy-operator.adoc[leveloffset=+1] -include::modules/migration-configuring-proxies.adoc[leveloffset=+1] +include::modules/migration-about-configuring-proxies.adoc[leveloffset=+1] +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]. diff --git a/migration_toolkit_for_containers/installing-mtc.adoc b/migration_toolkit_for_containers/installing-mtc.adoc index 8ee2dedfd0..ba73fb295c 100644 --- a/migration_toolkit_for_containers/installing-mtc.adoc +++ b/migration_toolkit_for_containers/installing-mtc.adoc @@ -23,7 +23,8 @@ To uninstall {mtc-short}, see xref:../migration_toolkit_for_containers/installin include::modules/migration-compatibility-guidelines.adoc[leveloffset=+1] include::modules/migration-installing-legacy-operator.adoc[leveloffset=+1] include::modules/migration-installing-mtc-on-ocp-4.adoc[leveloffset=+1] -include::modules/migration-configuring-proxies.adoc[leveloffset=+1] +include::modules/migration-about-configuring-proxies.adoc[leveloffset=+1] +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]. diff --git a/modules/migration-about-configuring-proxies.adoc b/modules/migration-about-configuring-proxies.adoc new file mode 100644 index 0000000000..2607e0d29c --- /dev/null +++ b/modules/migration-about-configuring-proxies.adoc @@ -0,0 +1,133 @@ +// Module included in the following assemblies: +// +// * migrating_from_ocp_3_to_4/installing-3-4.adoc +// * migrating_from_ocp_3_to_4/installing-restricted-3-4.adoc +// * migration_toolkit_for_containers/installing-mtc.adoc +// * migration_toolkit_for_containers/installing-mtc-restricted.adoc + +:_content-type: CONCEPT +[id="migration-about-configuring-proxies_{context}"] += Proxy configuration + +For {product-title} 4.1 and earlier versions, you must configure proxies in the `MigrationController` custom resource (CR) manifest after you install the {mtc-full} Operator because these versions do not support a cluster-wide `proxy` object. + +For {product-title} 4.2 to {product-version}, the {mtc-full} ({mtc-short}) inherits the cluster-wide proxy settings. You can change the proxy parameters if you want to override the cluster-wide proxy settings. + +[id="direct-volume-migration_{context}"] +== Direct volume migration + +Direct Volume Migration (DVM) was introduced in MTC 1.4.2. DVM supports only one proxy. The source cluster cannot access the route of the target cluster if the target cluster is also behind a proxy. + +If you want to perform a DVM from a source cluster behind a proxy, you must configure a TCP proxy that works at the transport layer and forwards the SSL connections transparently without decrypting and re-encrypting them with their own SSL certificates. A Stunnel proxy is an example of such a proxy. + +[id="tcp-proxy-setup-for-dvm_{context}"] +=== TCP proxy setup for DVM + +You can set up a direct connection between the source and the target cluster through a TCP proxy and configure the `stunnel_tcp_proxy` variable in the `MigrationController` CR to use the proxy: + +[source, yaml] +---- +apiVersion: migration.openshift.io/v1alpha1 +kind: MigrationController +metadata: + name: migration-controller + namespace: openshift-migration +spec: + [...] + stunnel_tcp_proxy: http://username:password@ip:port +---- + +Direct volume migration (DVM) supports only basic authentication for the proxy. Moreover, DVM works only from behind proxies that can tunnel a TCP connection transparently. HTTP/HTTPS proxies in man-in-the-middle mode do not work. The existing cluster-wide proxies might not support this behavior. As a result, the proxy settings for DVM are intentionally kept different from the usual proxy configuration in {mtc-short}. + +[id="why-tcp-proxy-instead-of-an-http-https-proxy_{context}"] +=== Why use a TCP proxy instead of an HTTP/HTTPS proxy? + +You can enable DVM by running Rsync between the source and the target cluster over an OpenShift route. Traffic is encrypted using Stunnel, a TCP proxy. The Stunnel running on the source cluster initiates a TLS connection with the target Stunnel and transfers data over an encrypted channel. + +Cluster-wide HTTP/HTTPS proxies in OpenShift are usually configured in man-in-the-middle mode where they negotiate their own TLS session with the outside servers. However, this does not work with Stunnel. Stunnel requires that its TLS session be untouched by the proxy, essentially making the proxy a transparent tunnel which simply forwards the TCP connection as-is. Therefore, you must use a TCP proxy. + +[id="dvm-known-issues_{context}"] +=== Known issue + +.Migration fails with error `Upgrade request required` + +The migration Controller uses the SPDY protocol to execute commands within remote pods. If the remote cluster is behind a proxy or a firewall that does not support the SPDY protocol, the migration controller fails to execute remote commands. The migration fails with the error message `Upgrade request required`. +Workaround: Use a proxy that supports the SPDY protocol. + +In addition to supporting the SPDY protocol, the proxy or firewall also must pass the `Upgrade` HTTP header to the API server. The client uses this header to open a websocket connection with the API server. If the `Upgrade` header is blocked by the proxy or firewall, the migration fails with the error message `Upgrade request required`. +Workaround: Ensure that the proxy forwards the `Upgrade` header. + +[id="tuning-network-policies-for-migrations_{context}"] +== Tuning network policies for migrations + +OpenShift supports restricting traffic to or from pods using _NetworkPolicy_ or _EgressFirewalls_ based on the network plugin used by the cluster. If any of the source namespaces involved in a migration use such mechanisms to restrict network traffic to pods, the restrictions might inadvertently stop traffic to Rsync pods during migration. + +Rsync pods running on both the source and the target clusters must connect to each other over an OpenShift Route. Existing _NetworkPolicy_ or _EgressNetworkPolicy_ objects can be configured to automatically exempt Rsync pods from these traffic restrictions. + +[id="dvm-network-policy-configuration_{context}"] +=== NetworkPolicy configuration + +[id="egress-traffic-from-rsync-pods_{context}"] +==== Egress traffic from Rsync pods + +You can use the unique labels of Rsync pods to allow egress traffic to pass from them if the `NetworkPolicy` configuration in the source or destination namespaces blocks this type of traffic. The following policy allows *all* egress traffic from Rsync pods in the namespace: + +[source, yaml] +---- +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: allow-all-egress-from-rsync-pods +spec: + podSelector: + matchLabels: + owner: directvolumemigration + app: directvolumemigration-rsync-transfer + egress: + - {} + policyTypes: + - Egress +---- + +[id="ingress-traffic-to-rsync-pods_{context}"] +==== Ingress traffic to Rsync pods + +[source, yaml] +---- +apiVersion: networking.k8s.io/v1 +kind: NetworkPolicy +metadata: + name: allow-all-egress-from-rsync-pods +spec: + podSelector: + matchLabels: + owner: directvolumemigration + app: directvolumemigration-rsync-transfer + ingress: + - {} + policyTypes: + - Ingress +---- + +[id="egressnetworkpolicy-config_{context}"] +=== EgressNetworkPolicy configuration + +The `EgressNetworkPolicy` object or _Egress Firewalls_ are OpenShift constructs designed to block egress traffic leaving the cluster. + +Unlike the `NetworkPolicy` object, the Egress Firewall works at a project level because it applies to all pods in the namespace. Therefore, the unique labels of Rsync pods do not exempt only Rsync pods from the restrictions. However, you can add the CIDR ranges of the source or target cluster to the _Allow_ rule of the policy so that a direct connection can be setup between two clusters. + +Based on which cluster the Egress Firewall is present in, you can add the CIDR range of the other cluster to allow egress traffic between the two: + +[source, yaml] +---- +apiVersion: network.openshift.io/v1 +kind: EgressNetworkPolicy +metadata: + name: test-egress-policy + namespace: +spec: + egress: + - to: + cidrSelector: + type: Deny +---- diff --git a/modules/migration-configuring-proxies.adoc b/modules/migration-configuring-proxies.adoc index bfbf4fd95b..0af1804f97 100644 --- a/modules/migration-configuring-proxies.adoc +++ b/modules/migration-configuring-proxies.adoc @@ -9,18 +9,6 @@ [id="migration-configuring-proxies_{context}"] = Configuring proxies -For {product-title} 4.1 and earlier versions, you must configure proxies in the `MigrationController` custom resource (CR) manifest after you install the {mtc-full} Operator because these versions do not support a cluster-wide `proxy` object. - -For {product-title} 4.2 to {product-version}, the {mtc-full} ({mtc-short}) inherits the cluster-wide proxy settings. You can change the proxy parameters if you want to override the cluster-wide proxy settings. - -You must configure the proxies to allow the `HTTP/2` protocol and to forward the `Upgrade HTTP` header to the API server. Otherwise, an `Upgrade request required` error is displayed. The `MigrationController` CR uses `HTTP/2` to run commands within remote pods. The `Upgrade HTTP` header is required in order to open a websocket connection with the API server. - -.Direct volume migration - -If you are performing a direct volume migration (DVM) from a source cluster behind a proxy, you must configure an Stunnel proxy. Stunnel creates a transparent tunnel between the source and target clusters for the TCP connection without changing the certificates. - -DVM supports only one proxy. The source cluster cannot access the route of the target cluster if the target cluster is also behind a proxy. - .Prerequisites * You must be logged in as a user with `cluster-admin` privileges on all clusters. @@ -46,14 +34,10 @@ metadata: ... spec: stunnel_tcp_proxy: http://:@: <1> - httpProxy: http://:@: <2> - httpsProxy: http://:@: <3> - noProxy: example.com <4> + noProxy: example.com <2> ---- <1> Stunnel proxy URL for direct volume migration. -<2> Proxy URL for creating HTTP connections outside the cluster. The URL scheme must be `http`. -<3> Proxy URL for creating HTTPS connections outside the cluster. If this is not specified, then `httpProxy` is used for both HTTP and HTTPS connections. -<4> Comma-separated list of destination domain names, domains, IP addresses, or other network CIDRs to exclude proxying. +<2> Comma-separated list of destination domain names, domains, IP addresses, or other network CIDRs to exclude proxying. + Preface a domain with `.` to match subdomains only. For example, `.y.com` matches `x.y.com`, but not `y.com`. Use `*` to bypass proxy for all destinations. If you scale up workers that are not included in the network defined by the `networking.machineNetwork[].cidr` field from the installation configuration, you must add them to this list to prevent connection issues.