OSDOCS-16851-1: First CQA for OVNK-2: Egress Traffic and Gateway Conf…

modules/example-secondary-external-gateway-configurations.adoc

@@ -0,0 +1,90 @@
+// Module included in the following assemblies:
+//
+// * networking/ovn_kubernetes_network_provider/configuring-secondary-external-gateway.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="example-secondary-external-gateway-configurations_{context}"]
+= Example secondary external gateway configurations
+
+[role="_abstract"]
+Reference the `AdminPolicyBasedExternalRoute` objects to better understand secondary external gateway configurations.
+
+In the following example, the `AdminPolicyBasedExternalRoute` object configures two static IP addresses as external gateways for pods in namespaces with the `kubernetes.io/metadata.name: novxlan-externalgw-ecmp-4059` label:
+
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: AdminPolicyBasedExternalRoute
+metadata:
+  name: default-route-policy
+spec:
+  from:
+    namespaceSelector:
+      matchLabels:
+        kubernetes.io/metadata.name: novxlan-externalgw-ecmp-4059
+  nextHops:
+    static:
+    - ip: "172.18.0.8"
+    - ip: "172.18.0.9"
+# ...
+----
+
+In the following example, the `AdminPolicyBasedExternalRoute` object configures a dynamic external gateway. The IP addresses used for the external gateway are derived from the additional network attachments associated with each of the selected pods.
+
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: AdminPolicyBasedExternalRoute
+metadata:
+  name: shadow-traffic-policy
+spec:
+  from:
+    namespaceSelector:
+      matchLabels:
+        externalTraffic: ""
+  nextHops:
+    dynamic:
+    - podSelector:
+        matchLabels:
+          gatewayPod: ""
+      namespaceSelector:
+        matchLabels:
+          shadowTraffic: ""
+      networkAttachmentName: shadow-gateway
+    - podSelector:
+        matchLabels:
+          gigabyteGW: ""
+      namespaceSelector:
+        matchLabels:
+          gatewayNamespace: ""
+      networkAttachmentName: gateway
+# ...
+----
+
+In the following example, the `AdminPolicyBasedExternalRoute` object configures both static and dynamic external gateways:
+
+[source,yaml]
+----
+apiVersion: k8s.ovn.org/v1
+kind: AdminPolicyBasedExternalRoute
+metadata:
+  name: multi-hop-policy
+spec:
+  from:
+    namespaceSelector:
+      matchLabels:
+        trafficType: "egress"
+  nextHops:
+    static:
+    - ip: "172.18.0.8"
+    - ip: "172.18.0.9"
+    dynamic:
+    - podSelector:
+        matchLabels:
+          gatewayPod: ""
+      namespaceSelector:
+        matchLabels:
+          egressTraffic: ""
+      networkAttachmentName: gigabyte
+# ...
+----

modules/nw-secondary-ext-gw-about.adoc

@@ -2,20 +2,23 @@
 //
 // * networking/ovn_kubernetes_network_provider/configuring-secondary-external-gateway.adoc
 
-:_mod-docs-content-type: PROCEDURE
+:_mod-docs-content-type: CONCEPT
 [id="nw-secondary-ext-gw-about_{context}"]
 = How {product-title} determines the external gateway IP address
 
-You configure a secondary external gateway with the `AdminPolicyBasedExternalRoute` custom resource (CR) from the `k8s.ovn.org` API group. The CR supports static and dynamic approaches to specifying an external gateway's IP address.
+[role="_abstract"]
+You configure a secondary external gateway with the `AdminPolicyBasedExternalRoute` custom resource (CR) from the `k8s.ovn.org` API group. The CR supports static and dynamic approaches for specifying an IP address for an external gateway.
 
-Each namespace that a `AdminPolicyBasedExternalRoute` CR targets cannot be selected by any other `AdminPolicyBasedExternalRoute` CR. A namespace cannot have concurrent secondary external gateways.
+Each namespace that an `AdminPolicyBasedExternalRoute` CR targets cannot be selected by any other `AdminPolicyBasedExternalRoute` CR. A namespace cannot have concurrent secondary external gateways.
 
-Changes to policies are isolated in the controller. If a policy fails to apply, changes to other policies do not trigger a retry of other policies. Policies are only re-evaluated, applying any differences that might have occurred by the change, when updates to the policy itself or related objects to the policy such as target namespaces, pod gateways, or namespaces hosting them from dynamic hops are made.
+Changes to policies are isolated in the controller. If a policy fails to apply, changes to other policies do not trigger a retry of other policies. Policies are re-evaluated when updates occur to the policy or to related objects such as target namespaces, pod gateways, or the namespaces that host them from dynamic hops. When re-evaluated, the policy applies any differences from the changes.
 
 Static assignment:: You specify an IP address directly.
 Dynamic assignment:: You specify an IP address indirectly, with namespace and pod selectors, and an optional network attachment definition.
-+
---
-- If the name of a network attachment definition is provided, the external gateway IP address of the network attachment is used.
-- If the name of a network attachment definition is not provided, the external gateway IP address for the pod itself is used. However, this approach works only if the pod is configured with `hostNetwork` set to `true`.
---
+
+[IMPORTANT]
+====
+If the name of a network attachment definition is provided, the external gateway IP address of the network attachment is used.
+
+If the name of a network attachment definition is not provided, the external gateway IP address for the pod itself is used. However, this approach works only if the pod is configured with `hostNetwork` set to `true`.
+====

modules/nw-secondary-ext-gw-configure.adoc

@@ -6,28 +6,26 @@
 [id="nw-secondary-ext-gw-configure_{context}"]
 = Configure a secondary external gateway
 
+[role="_abstract"]
 You can configure an external gateway on the default network for a namespace in your cluster.
 
 .Prerequisites
 
-* You installed the OpenShift CLI (`oc`).
+* You installed the {oc-first}.
 * You are logged in to the cluster with a user with `cluster-admin` privileges.
 
 .Procedure
 
-. Create a YAML file that contains an `AdminPolicyBasedExternalRoute` object.
+. Create a YAML file that contains an `AdminPolicyBasedExternalRoute` object. For more information, see "AdminPolicyBasedExternalRoute object configuration".
+
 . To create an admin policy based external route, enter the following command:
 +
 [source,terminal]
 ----
 $ oc create -f <file>.yaml
 ----
 +
---
-where:
-
-`<file>`:: Specifies the name of the YAML file that you created in the previous step.
---
+** `<file>`: Specifies the name of the YAML file that you created in a previous step.
 +
 .Example output
 [source,text]
@@ -42,11 +40,7 @@ adminpolicybasedexternalroute.k8s.ovn.org/default-route-policy created
 $ oc describe apbexternalroute <name> | tail -n 6
 ----
 +
---
-where:
-
-`<name>`:: Specifies the name of the `AdminPolicyBasedExternalRoute` object.
---
+** `<name>`: Specifies the name of the `AdminPolicyBasedExternalRoute` object.
 +
 .Example output
 [source,text]

modules/nw-secondary-ext-gw-object.adoc

@@ -2,11 +2,16 @@
 //
 // * networking/ovn_kubernetes_network_provider/configuring-secondary-external-gateway.adoc
 
-:_mod-docs-content-type: CONCEPT
+:_mod-docs-content-type: REFERENCE
 [id="nw-secondary-ext-gw-object_{context}"]
 = AdminPolicyBasedExternalRoute object configuration
 
-You can define an `AdminPolicyBasedExternalRoute` object, which is cluster scoped, with the following properties. A namespace can be selected by only one `AdminPolicyBasedExternalRoute` CR at a time.
+[role="_abstract"]
+You can define an `AdminPolicyBasedExternalRoute` object, which is cluster scoped, with specific properties.
+
+A namespace can be selected by only one `AdminPolicyBasedExternalRoute` CR at a time.
+
+The following tables detail supported fields for objects.
 
 .`AdminPolicyBasedExternalRoute` object
 [cols=".^3,.^2,.^5a",options="header"]
@@ -16,13 +21,11 @@ You can define an `AdminPolicyBasedExternalRoute` object, which is cluster scope
 
 |`metadata.name`
 |`string`
-|
-Specifies the name of the  `AdminPolicyBasedExternalRoute` object.
+|Specifies the name of the  `AdminPolicyBasedExternalRoute` object.
 
 |`spec.from`
 |`string`
-|
-Specifies a namespace selector that the routing policies apply to. Only `namespaceSelector` is supported for external traffic. For example:
+|Specifies a namespace selector that the routing policies apply to. Only `namespaceSelector` is supported for external traffic. For example:
 
 [source,yaml]
 ----
@@ -32,12 +35,11 @@ from:
       kubernetes.io/metadata.name: novxlan-externalgw-ecmp-4059
 ----
 
-A namespace can only be targeted by one `AdminPolicyBasedExternalRoute` CR. If a namespace is selected by more than one `AdminPolicyBasedExternalRoute` CR, a `failed` error status occurs on the second and subsequent CRs that target the same namespace. To apply updates, you must change the policy itself or related objects to the policy such as target namespaces, pod gateways, or namespaces hosting them from dynamic hops in order for the policy to be re-evaluated and your changes to be applied.
+A namespace can only be targeted by one `AdminPolicyBasedExternalRoute` CR. If a namespace is selected by more than one `AdminPolicyBasedExternalRoute` CR, a `failed` error status occurs on the second and subsequent CRs that target the same namespace. To apply updates, you must change the policy itself or related objects such as target namespaces, pod gateways, or namespaces hosting them from dynamic hops. The policy is then re-evaluated and your changes are applied.
 
 |`spec.nextHops`
 |`object`
-|
-Specifies the destinations where the packets are forwarded to. Must be either or both of `static` and `dynamic`. You must have at least one next hop defined.
+| Specifies the destinations where the packets are forwarded to. Must be either or both of `static` and `dynamic`. You must have at least one next hop defined.
 
 |====
 
@@ -69,7 +71,7 @@ Specifies the destinations where the packets are forwarded to. Must be either or
 
 |`bfdEnabled`
 |`boolean`
-|Optional: Specifies whether Bi-Directional Forwarding Detection (BFD) is supported by the network. The default value is `false`.
+|Optional field. Specifies whether Bi-Directional Forwarding Detection (BFD) is supported by the network. The default value is `false`.
 
 |====
 
@@ -80,101 +82,19 @@ Specifies the destinations where the packets are forwarded to. Must be either or
 
 |`podSelector`
 |`string`
-|
-Specifies a [set-based](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement) label selector to filter the pods in the namespace that match this network configuration.
+|Specifies a set-based label selector to filter the pods in the namespace that match this network configuration. For more information, see "Set-based requirement" in the _Additional resources_ section.
 
 |`namespaceSelector`
 |`string`
-| Specifies a `set-based` selector to filter the namespaces that the `podSelector` applies to. You must specify a value for this field.
+|Specifies a `set-based` selector to filter the namespaces that the `podSelector` applies to. You must specify a value for this field.
 
 
 |`bfdEnabled`
 |`boolean`
-|Optional: Specifies whether Bi-Directional Forwarding Detection (BFD) is supported by the network. The default value is `false`.
+|Optional field. Specifies whether Bi-Directional Forwarding Detection (BFD) is supported by the network. The default value is `false`.
 
 |`networkAttachmentName`
 |`string`
-|
-Optional: Specifies the name of a network attachment definition. The name must match the list of logical networks associated with the pod. If this field is not specified, the host network of the pod is used. However, the pod must be configure as a host network pod to use the host network.
+|Optional field. Specifies the name of a network attachment definition. The name must match the list of logical networks associated with the pod. If this field is not specified, the host network of the pod is used. However, the pod must be configured as a host network pod to use the host network.
 
 |====
-
-[id="example-secondary-external-gateway-configurations_{context}"]
-== Example secondary external gateway configurations
-
-In the following example, the `AdminPolicyBasedExternalRoute` object configures two static IP addresses as external gateways for pods in namespaces with the `kubernetes.io/metadata.name: novxlan-externalgw-ecmp-4059` label.
-
-[source,yaml]
-----
-apiVersion: k8s.ovn.org/v1
-kind: AdminPolicyBasedExternalRoute
-metadata:
-  name: default-route-policy
-spec:
-  from:
-    namespaceSelector:
-      matchLabels:
-        kubernetes.io/metadata.name: novxlan-externalgw-ecmp-4059
-  nextHops:
-    static:
-    - ip: "172.18.0.8"
-    - ip: "172.18.0.9"
-----
-
-In the following example, the `AdminPolicyBasedExternalRoute` object configures a dynamic external gateway. The IP addresses used for the external gateway are derived from the additional network attachments associated with each of the selected pods.
-
-[source,yaml]
-----
-apiVersion: k8s.ovn.org/v1
-kind: AdminPolicyBasedExternalRoute
-metadata:
-  name: shadow-traffic-policy
-spec:
-  from:
-    namespaceSelector:
-      matchLabels:
-        externalTraffic: ""
-  nextHops:
-    dynamic:
-    - podSelector:
-        matchLabels:
-          gatewayPod: ""
-      namespaceSelector:
-        matchLabels:
-          shadowTraffic: ""
-      networkAttachmentName: shadow-gateway
-    - podSelector:
-        matchLabels:
-          gigabyteGW: ""
-      namespaceSelector:
-        matchLabels:
-          gatewayNamespace: ""
-      networkAttachmentName: gateway
-----
-
-In the following example, the `AdminPolicyBasedExternalRoute` object configures both static and dynamic external gateways.
-
-[source,yaml]
-----
-apiVersion: k8s.ovn.org/v1
-kind: AdminPolicyBasedExternalRoute
-metadata:
-  name: multi-hop-policy
-spec:
-  from:
-    namespaceSelector:
-      matchLabels:
-        trafficType: "egress"
-  nextHops:
-    static:
-    - ip: "172.18.0.8"
-    - ip: "172.18.0.9"
-    dynamic:
-    - podSelector:
-        matchLabels:
-          gatewayPod: ""
-      namespaceSelector:
-        matchLabels:
-          egressTraffic: ""
-      networkAttachmentName: gigabyte
-----

networking/ovn_kubernetes_network_provider/configuring-secondary-external-gateway.adoc

@@ -6,6 +6,7 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 As a cluster administrator, you can configure an external gateway on the default network.
 
 This feature offers the following benefits:
@@ -24,11 +25,16 @@ include::modules/nw-secondary-ext-gw-about.adoc[leveloffset=+1]
 
 include::modules/nw-secondary-ext-gw-object.adoc[leveloffset=+1]
 
-include::modules/nw-secondary-ext-gw-configure.adoc[leveloffset=+1]
+[role="_additional-resources"]
+[id="additional-resources_{context}"]
+== Additional resources
+
+* link:https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/#set-based-requirement[Set-based requirement (Kubernetes)]
 
-// TODO - Resolve this after OCP 4.14 is released
-//include::modules/nw-secondary-ext-gw-status.adoc[leveloffset=+1]
+include::modules/example-secondary-external-gateway-configurations.adoc[leveloffset=+1]
+
+include::modules/nw-secondary-ext-gw-configure.adoc[leveloffset=+1]
 
-[id="{context}_additional-resources"]
+[role="_additional-resources"]
 == Additional resources
 * xref:../../networking/multiple_networks/understanding-multiple-networks.adoc#understanding-multiple-networks[Understanding multiple networks]