Merge pull request #102739 from dfitzmau/OSDOCS-16835

OSDOCS-16835: Completed the CQA2.0 for Secondary Network Advanced Con…

Author: dfitzmau

microshift_networking/microshift_network_policy/microshift-creating-network-policy.adoc

@@ -7,9 +7,9 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 You can create a network policy for a namespace.
 
-//OCP modules, edit using conditions and with care (check OCP previews, too)
 include::modules/nw-networkpolicy-object.adoc[leveloffset=+1]
 
 include::modules/nw-networkpolicy-create-cli.adoc[leveloffset=+1]

microshift_networking/microshift_network_policy/microshift-deleting-network-policy.adoc

@@ -7,6 +7,7 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 You can delete a network policy from a namespace.
 
 include::modules/nw-networkpolicy-delete-cli.adoc[leveloffset=+1]

microshift_networking/microshift_network_policy/microshift-editing-network-policy.adoc

@@ -7,9 +7,11 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-You can edit an existing network policy for a namespace. Typical edits might include changes to the pods to which the policy applies, allowed ingress traffic, and the destination ports on which to accept traffic. The `apiVersion`, `kind`, and `name` fields must not be changed when editing `NetworkPolicy` objects, as these define the resource itself.
+[role="_abstract"]
+You can edit an existing network policy for a namespace. 
+
+Typical edits might include changes to the pods to which the policy applies, allowed ingress traffic, and the destination ports on which to accept traffic. The `apiVersion`, `kind`, and `name` fields must not be changed when editing `NetworkPolicy` objects, as these define the resource itself.
 
-//OCP modules, edit using conditionals
 include::modules/nw-networkpolicy-edit.adoc[leveloffset=+1]
 
 include::modules/nw-networkpolicy-object.adoc[leveloffset=+1]

microshift_networking/microshift_network_policy/microshift-viewing-network-policy.adoc

@@ -7,6 +7,7 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
+[role="_abstract"]
 Use the following procedure to view a network policy for a namespace.
 
 include::modules/nw-networkpolicy-view-cli.adoc[leveloffset=+1]

modules/cnf-assigning-a-secondary-network-to-a-vrf.adoc

@@ -6,23 +6,22 @@
 [id="cnf-creating-an-additional-network-attachment-with-the-cni-vrf-plug-in_{context}"]
 = Creating a secondary network attachment with the CNI VRF plugin
 
-The Cluster Network Operator (CNO) manages secondary network definitions. When you specify a secondary network to create, the CNO creates the `NetworkAttachmentDefinition` custom resource (CR) automatically.
+[role="_abstract"] 
+The Cluster Network Operator (CNO) manages secondary network definitions. When you specify a secondary network in the cluster-scoped `Network` custom resource (CR), the CNO automatically creates the `NetworkAttachmentDefinition` CR.
 
 [NOTE]
 ====
 Do not edit the `NetworkAttachmentDefinition` CRs that the Cluster Network Operator manages. Doing so might disrupt network traffic on your secondary network.
 ====
 
-To create a secondary network attachment with the CNI VRF plugin, perform the following procedure.
-
 .Prerequisites
 
-* Install the {product-title} CLI (oc).
-* Log in to the OpenShift cluster as a user with cluster-admin privileges.
+* Install the {oc-first}.
+* Log in to the cluster as a user with `cluster-admin` privileges.
 
 .Procedure
 
-. Create the `Network` custom resource (CR) for the additional network attachment and insert the `rawCNIConfig` configuration for the secondary network, as in the following example CR. Save the YAML as the file `additional-network-attachment.yaml`.
+. Create the `Network` CR for the additional network attachment and insert the `rawCNIConfig` configuration for the secondary network. Save as the `additional-network-attachment.yaml` file.
 +
 [source,yaml]
 ----
@@ -38,7 +37,7 @@ spec:
       rawCNIConfig: '{
         "cniVersion": "0.3.1",
         "name": "macvlan-vrf",
-        "plugins": [  <1>
+        "plugins": [
         {
           "type": "macvlan", 
           "master": "eth1",
@@ -52,16 +51,19 @@ spec:
           }
         },
         {
-          "type": "vrf", <2>
-          "vrfname": "vrf-1",  <3>
-          "table": 1001   <4>
+          "type": "vrf",
+          "vrfname": "vrf-1",
+          "table": 1001
         }]
       }'
 ----
-<1> `plugins` must be a list. The first item in the list must be the secondary network underpinning the VRF network. The second item in the list is the VRF plugin configuration.
-<2> `type` must be set to `vrf`.
-<3> `vrfname` is the name of the VRF that the interface is assigned to. If it does not exist in the pod, it is created.
-<4> Optional. `table` is the routing table ID. By default, the `tableid` parameter is used. If it is not specified, the CNI assigns a free routing table ID to the VRF.
++
+where:
++
+`plugins`:: You must specify a list. The first item in the list must be the secondary network underpinning the VRF network. The second item in the list is the VRF plugin configuration.
+`type`:: You must set this parameter to `vrf`.
+`vrfname`:: The name of the VRF that the interface is assigned to. If the VRF does not exist in the pod, the CNI creates the VRF.
+`table`:: Optional parameter. Specify the routing table ID. By default, the `tableid` parameter is used. If you do not specify a table ID, the CNI assigns a free routing table ID to the VRF.
 +
 [NOTE]
 ====
@@ -84,16 +86,15 @@ $ oc get network-attachment-definitions -n <namespace>
 +
 [NOTE]
 ====
-There might be a delay before the CNO creates the CR.
+A delay might exist before the CNO creates the CR.
 ====
 
 .Verification
 
-. Create a pod and assign it to the secondary network with the VRF instance:
-
-.. Create a YAML file that defines the `Pod` resource:
+. Create a pod and assign the pod to the secondary network that includes the VRF plugin configuration.
++
+.. Create a YAML file that defines the `Pod` resource, as demonstrated in the following `pod-additional-net.yaml` file:
 +
-.Example `pod-additional-net.yaml` file
 [source,yaml]
 ----
 apiVersion: v1
@@ -112,30 +113,32 @@ spec:
    command: ["/bin/bash", "-c", "sleep 9000000"]
    image: centos:8
 ----
-<1> Specify the name of the secondary network with the VRF instance.
-
++
+where:
++
+`name`:: Specify the name of the secondary network that includes the VRF plugin configuration.
++
 .. Create the `Pod` resource by running the following command. The expected output shows the name of the `Pod` resource and the creation age in minutes.
 +
 [source,terminal]
 ----
 $ oc create -f pod-additional-net.yaml
 ----
 
-. Verify that the pod network attachment is connected to the VRF secondary network. Start a remote session with the pod and run the following command. The expected output shows the name of the VRF interface and its unique ID in the routing table.
+. Verify that the pod network attachment connects to the VRF secondary network. Start a remote session with the pod and run the following command. The expected output shows the name of the VRF interface and its unique ID in the routing table.
 +
 [source,terminal]
 ----
 $ ip vrf show
 ----
 
-. Confirm that the VRF interface is the controller for the secondary interface:
+. Confirm that the VRF interface is the controller for the secondary interface by entering the following command:
 +
 [source,terminal]
 ----
 $ ip link
 ----
 +
-.Example output
 [source,terminal]
 ----
 5: net1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master red state UP mode

modules/cnf-creating-an-additional-sriov-network-with-vrf-plug-in.adoc

@@ -6,6 +6,7 @@
 [id="cnf-creating-an-additional-sriov-network-with-vrf-plug-in_{context}"]
 = Creating an additional SR-IOV network attachment with the CNI VRF plugin
 
+[role="_abstract"]
 The SR-IOV Network Operator manages additional network definitions. When you specify an additional SR-IOV network to create, the SR-IOV Network Operator creates the `NetworkAttachmentDefinition` custom resource (CR) automatically.
 
 [NOTE]
@@ -17,14 +18,13 @@ To create an additional SR-IOV network attachment with the CNI virtual routing a
 
 .Prerequisites
 
-* Install the {product-title} CLI (oc).
+* Install the {oc-first}.
 * Log in to the {product-title} cluster as a user with cluster-admin privileges.
 
 .Procedure
 
 . Create the `SriovNetwork` custom resource (CR) for the additional SR-IOV network attachment and insert the `metaPlugins` configuration, as in the following example CR. Save the YAML as the file `sriov-network-attachment.yaml`.
 +
-.Example `SriovNetwork` custom resource (CR) example
 [source,yaml]
 ----
 apiVersion: sriovnetwork.openshift.io/v1
@@ -49,11 +49,14 @@ spec:
   metaPlugins : |
     {
       "type": "vrf", <1>
-      "vrfname": "example-vrf-name" <2>
+      "vrfname": "example-vrf-name"
     }
 ----
-<1> Set the `type` parameter to `vrf`.
-<2> Specify a name for the VRF in the `vrfname` parameter. An interface gets assigned to the VRF. If you do not specify a name for the VRF in a pod, the SR-IOV Network Operator automatically generates a name for the VRF.
++
+where:
++
+`metaPlugins.type`:: Set the `type` parameter to `vrf`.
+`metaPlugins.vrfname`:: Specify a name for the VRF in the `vrfname` parameter. An interface gets assigned to the VRF. If you do not specify a name for the VRF in a pod, the SR-IOV Network Operator automatically generates a name for the VRF.
 
 . Create the `SriovNetwork` resource:
 +
@@ -62,42 +65,39 @@ spec:
 $ oc create -f sriov-network-attachment.yaml
 ----
 
-.Verifying that the `NetworkAttachmentDefinition` CR is successfully created
+.Verification
 
-* Confirm that the SR-IOV Network Operator created the `NetworkAttachmentDefinition` CR by running the following command. The expected output shows the name of the NAD CR and the creation age in minutes.
+. Confirm that the SR-IOV Network Operator created the `NetworkAttachmentDefinition` CR by running the following command. The expected output shows the name of the NAD CR and the creation age in minutes.
 +
 [source,terminal]
 ----
-$ oc get network-attachment-definitions -n <namespace> <1>
+$ oc get network-attachment-definitions -n <namespace>
 ----
-<1> Replace `<namespace>` with the namespace that you specified when configuring the network attachment, for example, `additional-sriov-network-1`.
++
+* `<namespace>`: Replace `<namespace>` with the namespace that you specified when configuring the network attachment, for example, `additional-sriov-network-1`.
 +
 [NOTE]
 ====
 There might be a delay before the SR-IOV Network Operator creates the CR.
 ====
 
-.Verifying that the additional SR-IOV network attachment is successful
-
-To verify that the VRF CNI is correctly configured and that the additional SR-IOV network attachment is attached, do the following:
-
-. Create an SR-IOV network that uses the VRF CNI.
-
-. Assign the network to a pod.
-
-. Verify that the pod network attachment connects to the SR-IOV additional network. Ensure that you remote shell login into the pod and run the following command. The expected output shows the name of the VRF interface and its unique ID in the routing table.
+. To verify that the VRF CNI is correctly configured and that the additional SR-IOV network attachment is attached, do the following:
++
+.. Create an SR-IOV network that uses the VRF CNI.
++
+.. Assign the network to a pod.
++
+.. Verify that the pod network attachment connects to the SR-IOV additional network. Ensure that you remote shell login into the pod and run the following command. The expected output shows the name of the VRF interface and its unique ID in the routing table.
 +
 [source,terminal]
 ----
 $ ip vrf show
 ----
-
-. Confirm that the VRF interface is `master` of the secondary interface by running the following command:
++
+.. Confirm that the VRF interface is `master` for the secondary interface by running the following command. Example output shows `5: net1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master red state UP mode`.
 +
 [source,terminal]
 ----
 $ ip link
 ----
-+
-Example output: `5: net1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master red state UP mode`
 

modules/configuration-ovnk-multi-network-policy.adoc

@@ -2,13 +2,17 @@
 //
 // * networking/multiple_networks/secondary_networks/creating-secondary-nwt-ovnk.adoc
 
-:_mod-docs-content-type: CONCEPT
+:_mod-docs-content-type: REFERENCE
 [id="compatibility-with-multi-network-policy_{context}"]
 = Compatibility with multi-network policy
 
-The multi-network policy API, which is provided by the `MultiNetworkPolicy` custom resource definition (CRD) in the `k8s.cni.cncf.io` API group, is compatible with an OVN-Kubernetes secondary network. When defining a network policy, the network policy rules that can be used depend on whether the OVN-Kubernetes secondary network defines the `subnets` field. Refer to the following table for details:
+[role="_abstract"] 
+When defining a network policy, the network policy rules that can be used depend on whether the OVN-Kubernetes secondary network defines the `subnets` field. 
+
+The multi-network policy API, which is provided by the `MultiNetworkPolicy` custom resource definition (CRD) in the `k8s.cni.cncf.io` API group, is compatible with an OVN-Kubernetes secondary network. 
+
+Refer to the following table that details supported multi-network policy selectors that are based on a `subnets` CNI configuration:
 
-.Supported multi-network policy selectors based on `subnets` CNI configuration
 [cols=".^3,.^7",options="header"]
 |====
 a|`subnets` field specified|Allowed multi-network policy selectors
@@ -26,9 +30,8 @@ a|
 
 |====
 
-You can use the `k8s.v1.cni.cncf.io/policy-for` annotation on a `MultiNetworkPolicy` object to point to a `NetworkAttachmentDefinition` (NAD) custom resource (CR). The NAD CR defines the network to which the policy applies. The following example multi-network policy is valid only if the `subnets` field is defined in the secondary network CNI configuration for the secondary network named `blue2`:
+You can use the `k8s.v1.cni.cncf.io/policy-for` annotation on a `MultiNetworkPolicy` object to point to a `NetworkAttachmentDefinition` (NAD) custom resource (CR). The NAD CR defines the network to which the policy applies. The following example multi-network policy that uses a pod selector is valid only if the `subnets` field is defined in the secondary network CNI configuration for the secondary network named `blue2`:
 
-.Example multi-network policy that uses a pod selector
 [source,yaml]
 ----
 apiVersion: k8s.cni.cncf.io/v1beta1
@@ -44,7 +47,7 @@ spec:
     - podSelector: {}
 ----
 
-The following example uses the `ipBlock` network policy selector, which is always valid for an OVN-Kubernetes secondary network:
+The following example uses the `ipBlock` network multi-network policy that is always valid for an OVN-Kubernetes secondary network:
 
 .Example multi-network policy that uses an IP block selector
 [source,yaml]

modules/configuration-ovnk-network-plugin-json-object.adoc

@@ -6,7 +6,8 @@
 [id="configuration-ovnk-network-plugin-json-object_{context}"]
 = OVN-Kubernetes network plugin JSON configuration table
 
-The following table describes the configuration parameters for the OVN-Kubernetes CNI network plugin:
+[role="_abstract"]
+The OVN-Kubernetes network plugin JSON configuration object describes the configuration parameters for the OVN-Kubernetes CNI network plugin. The following table details these parameters:
 
 .OVN-Kubernetes network plugin JSON configuration table
 [cols=".^2,.^2,.^6",options="header"]
@@ -21,9 +22,7 @@ The CNI specification version. The required value is `0.3.1`.
 |`name`
 |`string`
 |
-The name of the network. These networks are not namespaced. For example, a network named `l2-network` can be referenced by `NetworkAttachmentDefinition` custom resources (CRs) that exist in different namespaces.
-This configuration allows pods that use the `NetworkAttachmentDefinition` CR in different namespaces to communicate over the same secondary network.
-However, the `NetworkAttachmentDefinition` CRs must share the same network-specific parameters, such as `topology`, `subnets`, `mtu`, `excludeSubnets`, and `vlanID`. The `vlanID` parameter applies only when the `topology` field is set to `localnet`.
+The name of the network. These networks are not namespaced. For example, a network named `l2-network` can be referenced by `NetworkAttachmentDefinition` custom resources (CRs) that exist in different namespaces. This configuration allows pods that use the `NetworkAttachmentDefinition` CR in different namespaces to communicate over the same secondary network. However, the `NetworkAttachmentDefinition` CRs must share the same network-specific parameters, such as `topology`, `subnets`, `mtu`, `excludeSubnets`, and `vlanID`. The `vlanID` parameter applies only when the `topology` field is set to `localnet`.
 
 |`type`
 |`string`
@@ -52,8 +51,7 @@ The maximum transmission unit (MTU). If you do not set a value, the Cluster Netw
 |`netAttachDefName`
 |`string`
 |
-The metadata `namespace` and `name` of the network attachment definition CRD where this
-configuration is included. For example, if this configuration is defined in a `NetworkAttachmentDefinition` CRD in namespace `ns1` named `l2-network`, this should be set to `ns1/l2-network`.
+The metadata `namespace` and `name` of the network attachment definition CRD where this configuration is included. For example, if this configuration is defined in a `NetworkAttachmentDefinition` CRD in namespace `ns1` named `l2-network`, this should be set to `ns1/l2-network`.
 
 |`excludeSubnets`
 |`string`

modules/configuring-layer-two-switched-topology.adoc

@@ -6,6 +6,7 @@
 [id="configuration-layer-two-switched-topology_{context}"]
 = Configuration for a layer 2 switched topology
 
+[role="_abstract"]
 The switched (layer 2) topology networks interconnect the workloads through a cluster-wide logical switch. This configuration can be used for IPv6 and dual-stack deployments.
 
 [NOTE]