Merge pull request #29426 from jboxman/gh-28357

GH#28357 - Clarify selectors for EgressIP objects

Author: jboxman

modules/nw-egress-ips-about.adoc

@@ -73,29 +73,60 @@ When a pod matches the selector for multiple `EgressIP` objects, there is no gua
 [id="nw-egress-ips-node-architecture_{context}"]
 == Architectural diagram of an egress IP address configuration
 
-The following diagram depicts an egress IP address configuration. The diagram describes the relationship between three nodes in a cluster and four pods running on that cluster in two different namespaces.
+The following diagram depicts an egress IP address configuration. The diagram describes four pods in two different namespaces running on three nodes in a cluster. The nodes are assigned IP addresses from the `192.168.126.0/18` CIDR block on the host network.
 
 // Source: https://github.com/redhataccess/documentation-svg-assets/blob/master/for-web/121_OpenShift/121_OpenShift_engress_IP_Topology_1020.svg
 image::nw-egress-ips-diagram.svg[Architectural diagram for the egress IP feature.]
 
 Both Node 1 and Node 3 are labeled with `k8s.ovn.org/egress-assignable: ""` and thus available for the assignment of egress IP addresses.
 
-The following `EgressIP` object describes a configuration that selects all pods in the `namespace1` namespace, with the `192.168.126.10` and `192.168.126.102` egress IP addresses specified.
+The dashed lines in the diagram depict the traffic flow from pod1, pod2, and pod3 traveling through the pod network to egress the cluster from Node 1 and Node 3. When an external service receives traffic from any of the pods selected by the example `EgressIP` object, the source IP address is either `192.168.126.10` or `192.168.126.102`.
+
+The following resources from the diagram are illustrated in detail:
+
+`Namespace` objects::
++
+--
+The namespaces are defined in the following manifest:
+
+.Namespace objects
+[source,yaml]
+----
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: namespace1
+  labels:
+    env: prod
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: namespace2
+  labels:
+    env: prod
+----
+--
+
+`EgressIP` object::
++
+--
+The following `EgressIP` object describes a configuration that selects all pods in any namespace with the `env` label set to `prod`. The egress IP addresses for the selected pods are `192.168.126.10` and `192.168.126.102`.
 
 .`EgressIP` object
 [source,yaml]
 ----
 apiVersion: k8s.ovn.org/v1
 kind: EgressIP
 metadata:
-  name: egressips
+  name: egressips-prod
 spec:
   egressIPs:
   - 192.168.126.10
   - 192.168.126.102
   namespaceSelector:
     matchLabels:
-      name: namespace1
+      env: prod
 status:
   assignments:
   - node: node1
@@ -104,9 +135,8 @@ status:
     egressIP: 192.168.126.102
 ----
 
-After creating the `EgressIP` object, {product-title} assigns both egress IP addresses to the available nodes. The `status` field reflects the whether and where the egress IP addresses are assigned.
-
-The dashed lines in the diagram depict the traffic flow from `pod1`, `pod2`, and `pod3` traveling through the pod network to egress the cluster from Node 1 and Node 3. When an external service receives traffic from any of the pods selected by the example `EgressIP` object, the source IP address is either `192.168.126.10` or `192.168.126.102`.
+For the configuration in the previous example, {product-title} assigns both egress IP addresses to the available nodes. The `status` field reflects whether and where the egress IP addresses are assigned.
+--
 endif::ovn[]
 
 ifdef::openshift-sdn[]

modules/nw-egress-ips-assign.adoc

@@ -31,7 +31,7 @@ spec:
   - 192.168.127.11
   namespaceSelector:
     matchLabels:
-      name: project1
+      env: qa
 ----
 
 . To create the object, enter the following command.

modules/nw-egress-ips-object.adoc

@@ -36,7 +36,7 @@ The following YAML describes the stanza for the namespace selector:
 ----
 namespaceSelector: <1>
   matchLabels:
-    name: <namespace_name>
+    <label_name>: <label_value>
 ----
 <1> One or more matching rules for namespaces. If more than one match rule is provided, all matching namespaces are selected.
 
@@ -47,11 +47,11 @@ The following YAML describes the optional stanza for the pod selector:
 ----
 podSelector: <1>
   matchLabels:
-    name: <pod_name>
+    <label_name>: <label_value>
 ----
 <1> Optional: 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 the pod that is named `my-pod` in the namespace that is named `my-namespace`:
+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`:
 
 .Example `EgressIP` object
 [source,yaml]
@@ -66,10 +66,10 @@ spec:
   - 192.168.126.102
   podSelector:
     matchLabels:
-      name: my-pod
+      app: web
   namespaceSelector:
     matchLabels:
-      name: my-namespace
+      env: prod
 ----
 
 In the following example, the `EgressIP` object associates the `192.168.127.30` and `192.168.127.40` egress IP addresses with any pods that do not have the `environment` label set to `development`: