[enterprise-4.19] OSDOCS-10661:updates for local gateway mode

_topic_maps/_topic_map.yml

@@ -1610,6 +1610,8 @@ Topics:
     File: converting-to-dual-stack
   - Name: Configuring internal subnets
     File: configure-ovn-kubernetes-subnets
+  - Name: Configuring gateway mode
+    File: configuring-gateway-mode
   - Name: Configure an external gateway on the default network
     File: configuring-secondary-external-gateway
   - Name: Configuring an egress IP address

modules/nw-operator-cr.adoc

@@ -206,7 +206,7 @@ endif::operator[]
 
 |`gatewayConfig`
 |`object`
-|Optional: Specify a configuration object for customizing how egress traffic is sent to the node gateway.
+|Optional: Specify a configuration object for customizing how egress traffic is sent to the node gateway. Valid values are `Shared` and `Local`. The default value is `Shared`. In the default setting, the Open vSwitch (OVS) outputs traffic directly to the node IP interface. In the `Local` setting, it traverses the host network; consequently, it gets applied to the routing table of the host.
 
 [NOTE]
 ====

modules/nwt-gateway-mode.adoc

@@ -0,0 +1,91 @@
+// Module included in the following assemblies:
+//
+
+:_mod-docs-content-type: PROCEDURE
+[id="nwt-gateway-mode_{context}"]
+= Setting local and shared gateway modes
+
+As a cluster administrator you can configure the gateway mode using the `gatewayConfig` spec in the Cluster Network Operator. The following procedure can be used to set the `routingViaHost` field to `true` for local mode or  `false` for shared mode.
+
+You can follow the optional step 4 to enable IP forwarding alongside local gateway mode if you need the host network of the node to act as a router for traffic not related to OVN-Kubernetes. For example, possible use cases for combining local gateway mode with IP forwarding include:
+
+* Configuring all pod egress traffic to be forwarded via the node's IP
+
+* Integrating OVN-Kubernetes CNI with external network address translation (NAT) devices
+
+* Configuring OVN-Kubernetes CNI to use a kernel routing table
+
+
+.Prerequisites
+* You are logged in as a user with admin privileges.
+
+.Procedure
+
+. Back up the existing network configuration by running the following command:
++
+[source,terminal]
+----
+$ oc get network.operator cluster -o yaml > network-config-backup.yaml
+----
+
+. Set the `routingViaHost` paramemter to `true` for local gateway mode by running the following command:
++
+[source,terminal]
+----
+$ oc patch networks.operator.openshift.io cluster --type=merge -p '{"spec":{"defaultNetwork":{"ovnKubernetesConfig":{"gatewayConfig":{"routingViaHost": true}}}}}'
+----
+
+. Verify that local gateway mode has been set by running the following command:
++
+[source,terminal]
+----
+$ oc get networks.operator.openshift.io cluster -o yaml | grep -A 5 "gatewayConfig"
+----
++
+.Example output
+[source,terminal]
+----
+apiVersion: operator.openshift.io/v1
+kind: Network
+metadata:
+  name: cluster
+# ...
+gatewayConfig:
+        ipv4: {}
+        ipv6: {}
+        routingViaHost: true <1>
+      genevePort: 6081
+      ipsecConfig:
+# ...
+----
+<1> A value of `true` sets local gateway mode and a value of `false` sets shared gateway mode. In local gateway mode, traffic is routed through the host. In shared gateway mode, traffic is not routed through the host.
+
+. Optional: Enable IP forwarding globally by running the following command:
++
+[source,terminal]
+----
+$ oc patch network.operator cluster --type=merge -p '{"spec":{"defaultNetwork":{"ovnKubernetesConfig":{"gatewayConfig":{"ipForwarding": "Global"}}}}}'
+----
+.. Verify that the `ipForwarding` spec has been set to `Global` by running the following command:
++
+[source,terminal]
+----
+$ oc get networks.operator.openshift.io cluster -o yaml | grep -A 5 "gatewayConfig"
+----
++
+.Example output
+[source,terminal]
+----
+apiVersion: operator.openshift.io/v1
+kind: Network
+metadata:
+  name: cluster
+# ...
+gatewayConfig:
+        ipForwarding: Global
+        ipv4: {}
+        ipv6: {}
+        routingViaHost: true
+      genevePort: 6081
+# ...
+----

networking/ovn_kubernetes_network_provider/configuring-gateway-mode.adoc

@@ -0,0 +1,13 @@
+:_mod-docs-content-type: ASSEMBLY
+[id="configuring-gateway-mode"]
+= Configuring gateway mode
+include::_attributes/common-attributes.adoc[]
+:context: configuring-gateway-mode
+
+toc::[]
+
+As a cluster administrator you can configure the `gatewayConfig` object to manage how external traffic leaves the cluster. You do so by setting the `routingViaHost` spec to `true` for local mode or `false` for shared mode.
+
+In local gateway mode, traffic is routed through the host and is consequently applied to the routing table of the host. In shared gateway mode, traffic is not routed through the host. Instead, traffic the Open vSwitch (OVS) outputs traffic directly to the node IP interface.
+
+include::modules/nwt-gateway-mode.adoc[leveloffset=+1]