From c1d325827c99e977fda4721aadd222d12184a50e Mon Sep 17 00:00:00 2001 From: dfitzmau Date: Mon, 8 Jun 2026 09:53:28 +0100 Subject: [PATCH] OSDOCS-16851-4-CQA: Fouth CQA for OVNK2 Egress Traffic and Gateway config --- modules/egressip_configure_failover_task.adoc | 7 +++--- modules/egressip_failover_concept.adoc | 4 +-- modules/egressip_failover_reference.adoc | 1 + modules/nw-egress-ips-assign.adoc | 11 ++++---- modules/nw-egress-ips-considerations.adoc | 9 ++++--- modules/nw-egress-ips-node.adoc | 15 +++++------ modules/nw-egress-ips-object-dual-stack.adoc | 3 ++- modules/nw-egress-ips-object.adoc | 14 +++++------ modules/nw-egress-router-cr.adoc | 4 ++- .../nw-egress-router-redirect-mode-ovn.adoc | 25 ++++++++----------- ...nwt-configure-egress-routing-policies.adoc | 9 ++++--- .../configuring-egress-ips-ovn.adoc | 2 +- .../configuring-gateway.adoc | 1 + 13 files changed, 57 insertions(+), 48 deletions(-) diff --git a/modules/egressip_configure_failover_task.adoc b/modules/egressip_configure_failover_task.adoc index ff693b2475f8..b83093b749c0 100644 --- a/modules/egressip_configure_failover_task.adoc +++ b/modules/egressip_configure_failover_task.adoc @@ -6,12 +6,13 @@ [id="egressip_configure_failover_task_{context}"] = Configuring the EgressIP failover time limit -Follow this procedure to configure the `reachabilityTotalTimeoutSeconds` parameter and control how quickly the system detects a failing `egressIP` node and initiates a failover. +[role="_abstract"] +You can configure the `reachabilityTotalTimeoutSeconds` parameter to control how quickly the system detects a failing `egressIP` node and initiates a failover. .Prerequisites -* Install the OpenShift CLI (`oc`). -* Log in to the cluster as a cluster administrator. +* You installed the {oc-first}. +* You logged in to the cluster as a cluster administrator. .Procedure diff --git a/modules/egressip_failover_concept.adoc b/modules/egressip_failover_concept.adoc index 13ed69126fac..67c0d3509702 100644 --- a/modules/egressip_failover_concept.adoc +++ b/modules/egressip_failover_concept.adoc @@ -6,6 +6,7 @@ [id="egressip_failover_concept_{context}"] = Understanding EgressIP failover control +[role="_abstract"] The `reachabilityTotalTimeoutSeconds` parameter controls how quickly the system detects a failing `egressIP` node and initiates a failover. This parameter directly determines the maximum time the platform waits before declaring a node unreachable. [IMPORTANT] @@ -14,6 +15,3 @@ When you configure `egressIP` with multiple egress nodes, the complete failover ==== To ensure traffic uses the correct external path, `egressIP` traffic on a node will always egress through the network interface on which the `egressIP` address has been assigned. - -// Next step: The user must perform a task to implement this configuration. -// See xref:egressip_configure_failover_task.adoc[Configuring the Failover Time Limit]. \ No newline at end of file diff --git a/modules/egressip_failover_reference.adoc b/modules/egressip_failover_reference.adoc index 169b16025872..6a69a1d50fb2 100644 --- a/modules/egressip_failover_reference.adoc +++ b/modules/egressip_failover_reference.adoc @@ -6,6 +6,7 @@ [id="egressip_failover_reference_{context}"] = EgressIP failover settings +[role="_abstract"] The `reachabilityTotalTimeoutSeconds` parameter defines the total time limit in seconds for the platform health check process before a node is declared down. The following table summarizes the acceptable values and their implications: diff --git a/modules/nw-egress-ips-assign.adoc b/modules/nw-egress-ips-assign.adoc index bc2fd988f15a..475558810c6f 100644 --- a/modules/nw-egress-ips-assign.adoc +++ b/modules/nw-egress-ips-assign.adoc @@ -6,13 +6,14 @@ [id="nw-egress-ips-assign_{context}"] = Assigning an egress IP address to a namespace +[role="_abstract"] You can assign one or more egress IP addresses to a namespace or to specific pods in a namespace. .Prerequisites -* Install the OpenShift CLI (`oc`). -* Log in to the cluster as a cluster administrator. -* Configure at least one node to host an egress IP address. +* The {oc-first} is installed. +* You are logged in to the cluster as a cluster administrator. +* At least one node is configured to host an egress IP address. .Procedure @@ -35,6 +36,7 @@ spec: namespaceSelector: matchLabels: env: qa +# ... ---- . To create the object, enter the following command. @@ -58,7 +60,7 @@ egressips.k8s.ovn.org/ created . Optional: Store the `.yaml` file so that you can make changes later. -. Add labels to the namespace that requires egress IP addresses. To add a label to the namespace of an `EgressIP` object defined in step 1, run the following command: +. Add labels to the namespace that requires egress IP addresses. To add a label to the namespace of an `EgressIP` object defined in a previous step, run the following command: + [source,terminal] ---- @@ -86,7 +88,6 @@ The command `oc get egressip` only returns one egress IP address regardless of h ==== + .Example output -+ [source,terminal] ---- # ... diff --git a/modules/nw-egress-ips-considerations.adoc b/modules/nw-egress-ips-considerations.adoc index 2be508ab90bf..25e48ecbbb38 100644 --- a/modules/nw-egress-ips-considerations.adoc +++ b/modules/nw-egress-ips-considerations.adoc @@ -2,11 +2,14 @@ // // * networking/ovn_kubernetes_network_provider/configuring-egress-ips-ovn.adoc -:_mod-docs-content-type: REFERENCE +:_mod-docs-content-type: CONCEPT [id="nw-egress-ips-considerations_{context}"] = Assignment of egress IPs to a namespace, nodes, and pods -To assign one or more egress IPs to a namespace or specific pods in a namespace, the following conditions must be satisfied: +[role="_abstract"] +To assign one or more egress IPs to a namespace or specific pods in a namespace, you must meet certain conditions. + +These conditions are listed as follows: - At least one node in your cluster must have the `k8s.ovn.org/egress-assignable: ""` label. - An `EgressIP` object exists that defines one or more egress IP addresses to use as the source IP address for traffic leaving the cluster from pods in a namespace. @@ -15,7 +18,7 @@ To assign one or more egress IPs to a namespace or specific pods in a namespace, ==== If you create `EgressIP` objects prior to labeling any nodes in your cluster for egress IP assignment, {product-title} might assign every egress IP address to the first node with the `k8s.ovn.org/egress-assignable: ""` label. -To ensure that egress IP addresses are widely distributed across nodes in the cluster, always apply the label to the nodes you intent to host the egress IP addresses before creating any `EgressIP` objects. +To ensure that egress IP addresses are widely distributed across nodes in the cluster, always apply the label to the nodes you intend to host the egress IP addresses before creating any `EgressIP` objects. ==== When creating an `EgressIP` object, the following conditions apply to nodes that are labeled with the `k8s.ovn.org/egress-assignable: ""` label: diff --git a/modules/nw-egress-ips-node.adoc b/modules/nw-egress-ips-node.adoc index 6548a52e655a..0cab8531ca28 100644 --- a/modules/nw-egress-ips-node.adoc +++ b/modules/nw-egress-ips-node.adoc @@ -6,17 +6,18 @@ [id="nw-egress-ips-node_{context}"] = Labeling a node to host egress IP addresses +[role="_abstract"] You can apply the `k8s.ovn.org/egress-assignable=""` label to a node in your cluster so that {product-title} can assign one or more egress IP addresses to the node. .Prerequisites ifndef::openshift-rosa[] -* Install the OpenShift CLI (`oc`). +* You installed the {oc-first}. endif::openshift-rosa[] ifdef::openshift-rosa[] -* Install the ROSA CLI (`rosa`). +* You installed the ROSA CLI (`rosa`). endif::openshift-rosa[] -* Log in to the cluster as a cluster administrator. +* You logged in to the cluster as a cluster administrator. .Procedure @@ -25,10 +26,10 @@ endif::openshift-rosa[] ifndef::openshift-rosa[] [source,terminal] ---- -$ oc label nodes k8s.ovn.org/egress-assignable="" <1> +$ oc label nodes k8s.ovn.org/egress-assignable="" ---- + -<1> The name of the node to label. +``:: Specifies the name of the node to label. + [TIP] ==== @@ -53,6 +54,6 @@ $ rosa edit machinepool --cluster= --labels "k8 + [IMPORTANT] ==== -This command replaces any exciting node labels on your machinepool. You should include any of the desired labels to the `--labels` field to ensure that your existing node labels persist. +This command replaces any existing node labels on your machinepool. You should include any of the desired labels to the `--labels` field to ensure that your existing node labels persist. ==== -endif::openshift-rosa[] \ No newline at end of file +endif::openshift-rosa[] diff --git a/modules/nw-egress-ips-object-dual-stack.adoc b/modules/nw-egress-ips-object-dual-stack.adoc index d735711fff4f..49c642af5b5f 100644 --- a/modules/nw-egress-ips-object-dual-stack.adoc +++ b/modules/nw-egress-ips-object-dual-stack.adoc @@ -6,6 +6,7 @@ [id="nw-egress-ips-object-dual-stack_{context}"] = Configuring dual-stack networking for an EgressIP object +[role="_abstract"] For a cluster configured for dual-stack networking, you can apply dual-stack networking to a single `EgressIP` object. The `EgressIP` object can then extend dual-stack networking capabilities to a pod. //// @@ -75,7 +76,7 @@ where: . Run a `curl` request from inside a pod to an external server. This action verifies that outbound traffic correctly uses an address that you specified in the `EgressIP` object. + -[source,source] +[source,terminal] ---- $ curl ---- diff --git a/modules/nw-egress-ips-object.adoc b/modules/nw-egress-ips-object.adoc index 962cf0ea8cbf..1caf2330e07b 100644 --- a/modules/nw-egress-ips-object.adoc +++ b/modules/nw-egress-ips-object.adoc @@ -7,7 +7,7 @@ = EgressIP object [role="_abstract"] -View the following YAML files to better understand how you can effectively configure an `EgressIP` object to better meet your needs. +You can view YAML files to better understand how you can effectively configure an `EgressIP` object to better meet your needs. When the `EgressIP` namespace selector matches the label on multiple namespaces, consider the following behaviors: @@ -41,13 +41,13 @@ spec: -- where: -``:: The name for the `EgressIPs` object. +``:: Specifies the name for the `EgressIPs` object. -``:: An array of one or more IP addresses. +``:: Specifies an array of one or more IP addresses. -``:: One or more selectors for the namespaces to associate the egress IP addresses with. +``:: Specifies one or more selectors for the namespaces to associate the egress IP addresses with. -``:: Optional parameter. One or more selectors for pods in the specified namespaces to associate egress IP addresses with. Applying these selectors allows for the selection of a subset of pods within a namespace. +``:: Optional parameter. Specifies one or more selectors for pods in the specified namespaces to associate egress IP addresses with. Applying these selectors allows for the selection of a subset of pods within a namespace. -- The following YAML describes the stanza for the namespace selector: @@ -63,7 +63,7 @@ namespaceSelector: -- where: -``:: One or more matching rules for namespaces. If more than one match rule is provided, all matching namespaces are selected. +``:: Specifies one or more matching rules for namespaces. If more than one match rule is provided, all matching namespaces are selected. -- The following YAML describes the optional stanza for the pod selector: @@ -79,7 +79,7 @@ podSelector: -- where: -``:: Optional parameter. One or more matching rules for pods in the namespaces that match the specified `namespaceSelector` rules. If specified, only pods that match are selected. Others pods in the namespace are not selected. +``:: Optional parameter. Specifies one or more matching rules for pods in the namespaces that match the specified `namespaceSelector` rules. If specified, only pods that match are selected. Others pods in the namespace are not selected. -- In the following example, the `EgressIP` object associates the `192.168.126.11` and `192.168.126.102` egress IP addresses with pods that have the `app` label set to `web` and are in the namespaces that have the `env` label set to `prod`: diff --git a/modules/nw-egress-router-cr.adoc b/modules/nw-egress-router-cr.adoc index d85489af909e..31cf86843940 100644 --- a/modules/nw-egress-router-cr.adoc +++ b/modules/nw-egress-router-cr.adoc @@ -13,7 +13,9 @@ endif::[] = Egress router custom resource [role="_abstract"] -Define the configuration for an egress router pod in an egress router custom resource. The following YAML describes the fields for the configuration of an egress router in {router-type} mode: +You can define the configuration for an egress router pod in an egress router custom resource. + +The following YAML describes the fields for the configuration of an egress router in {router-type} mode: // cluster-network-operator/manifests/0000_70_cluster-network-operator_01_egr_crd.yaml [source,yaml,subs="attributes+"] diff --git a/modules/nw-egress-router-redirect-mode-ovn.adoc b/modules/nw-egress-router-redirect-mode-ovn.adoc index 4093bea82a8d..7372a28df188 100644 --- a/modules/nw-egress-router-redirect-mode-ovn.adoc +++ b/modules/nw-egress-router-redirect-mode-ovn.adoc @@ -13,8 +13,8 @@ After you add an egress router, the client pods that need to use the reserved so .Prerequisites -* Install the {oc-first}. -* Log in as a user with `cluster-admin` privileges. +* You installed the {oc-first}. +* You logged in as a user with `cluster-admin` privileges. .Procedure @@ -37,14 +37,12 @@ spec: selector: app: egress-router-cni ---- -** `spec.selector`: Specifies the label for the egress router. The value shown is added by the Cluster Network Operator and is not configurable. +`spec.selector`: Specifies the label for the egress router. The value shown is added by the Cluster Network Operator and is not configurable. + After you create the service, your pods can connect to the service. The egress router pod redirects traffic to the corresponding port on the destination IP address. The connections originate from the reserved source IP address. .Verification -To verify that the Cluster Network Operator started the egress router, complete the following procedure: - . View the network attachment definition that the Operator created for the egress router: + [source,terminal] @@ -92,29 +90,28 @@ egress-router-cni-deployment-575465c75c-qkq6m 1/1 Running 0 18m ---- . View the logs and the routing table for the egress router pod. - -// Terminology from support-collecting-network-trace.adoc ++ .. Get the node name for the egress router pod: + [source,terminal] ---- $ POD_NODENAME=$(oc get pod -l app=egress-router-cni -o jsonpath="{.items[0].spec.nodeName}") ---- - ++ .. Enter into a debug session on the target node. This step instantiates a debug pod called `-debug`: + [source,terminal] ---- $ oc debug node/$POD_NODENAME ---- - ++ .. Set `/host` as the root directory within the debug shell. The debug pod mounts the root file system of the host in `/host` within the pod. By changing the root directory to `/host`, you can run binaries from the executable paths of the host: + [source,terminal] ---- # chroot /host ---- - ++ .. From within the `chroot` environment console, display the egress router logs: + [source,terminal] @@ -141,7 +138,7 @@ $ oc debug node/$POD_NODENAME ---- + The logging file location and logging level are not configurable when you start the egress router by creating an `EgressRouter` object as described in this procedure. - ++ .. From within the `chroot` environment console, get the container ID: + [source,terminal] @@ -155,7 +152,7 @@ The logging file location and logging level are not configurable when you start CONTAINER bac9fae69ddb6 ---- - ++ .. Determine the process ID of the container. In this example, the container ID is `bac9fae69ddb6`: + [source,terminal] @@ -168,14 +165,14 @@ bac9fae69ddb6 ---- 68857 ---- - ++ .. Enter the network namespace of the container: + [source,terminal] ---- # nsenter -n -t 68857 ---- - ++ .. Display the routing table: + [source,terminal] diff --git a/modules/nwt-configure-egress-routing-policies.adoc b/modules/nwt-configure-egress-routing-policies.adoc index e525df9b2717..a748447d5635 100644 --- a/modules/nwt-configure-egress-routing-policies.adoc +++ b/modules/nwt-configure-egress-routing-policies.adoc @@ -5,6 +5,7 @@ [id="nwt-configure-egress-routing-policies_{context}"] = Configuring egress routing policies +[role="_abstract"] As a cluster administrator you can configure egress routing policies by using the `gatewayConfig` specification in the Cluster Network Operator (CNO). You can use the following procedure to set the `routingViaHost` field to `true` or `false`. You can follow the optional step in the procedure to enable IP forwarding alongside the `routingViaHost=true` configuration 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 with IP forwarding include: @@ -17,7 +18,8 @@ You can follow the optional step in the procedure to enable IP forwarding alongs .Prerequisites -* You are logged in as a user with admin privileges. + +* You are logged in as a user with administrator privileges. .Procedure @@ -53,12 +55,13 @@ metadata: gatewayConfig: ipv4: {} ipv6: {} - routingViaHost: true <1> + routingViaHost: true genevePort: 6081 ipsecConfig: # ... ---- -<1> A value of `true` means that egress traffic gets routed through a specific local gateway on the node that hosts the pod. A value of `false` for the parameter means that a group of nodes share a single gateway so traffic does not get routed through a single host. ++ +** `routingViaHost`:: Specifies a value of `true` means that egress traffic gets routed through a specific local gateway on the node that hosts the pod. A value of `false` for the parameter means that a group of nodes share a single gateway so traffic does not get routed through a single host. . Optional: Enable IP forwarding globally by running the following command: + diff --git a/networking/ovn_kubernetes_network_provider/configuring-egress-ips-ovn.adoc b/networking/ovn_kubernetes_network_provider/configuring-egress-ips-ovn.adoc index ae50b4601879..5dd63ca82ef9 100644 --- a/networking/ovn_kubernetes_network_provider/configuring-egress-ips-ovn.adoc +++ b/networking/ovn_kubernetes_network_provider/configuring-egress-ips-ovn.adoc @@ -52,6 +52,7 @@ include::modules/nw-egress-ips-assign.adoc[leveloffset=+1] // START: Conditional block for EgressIP Failover Configuration (Replaces nw-egress-ips-config-object.adoc) ifndef::openshift-rosa,openshift-rosa-hcp[] + // Explains the 'Why' and 'What' of failover control (The Job to be Done) include::modules/egressip_failover_concept.adoc[leveloffset=+1] @@ -60,7 +61,6 @@ include::modules/egressip_configure_failover_task.adoc[leveloffset=+2] // REFERENCE: Describes the parameters (The table of values) include::modules/egressip_failover_reference.adoc[leveloffset=+2] - endif::openshift-rosa,openshift-rosa-hcp[] // Labeling a node to host egress IP addresses diff --git a/networking/ovn_kubernetes_network_provider/configuring-gateway.adoc b/networking/ovn_kubernetes_network_provider/configuring-gateway.adoc index 1dd3f3a0727e..21cca766bc7e 100644 --- a/networking/ovn_kubernetes_network_provider/configuring-gateway.adoc +++ b/networking/ovn_kubernetes_network_provider/configuring-gateway.adoc @@ -6,6 +6,7 @@ include::_attributes/common-attributes.adoc[] toc::[] +[role="_abstract"] 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` parameter to one of the following values: * `true` means that egress traffic routes through a specific local gateway on the node that hosts the pod. Egress traffic routes through the host and this traffic applies to the routing table of the host.