Merge pull request #98460 from dfitzmau/OSDOCS-15470-hardware

OSDOCS-15470-hardware: Removed code blocks from Hardware networks doc

Author: dfitzmau

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

@@ -13,7 +13,7 @@ The SR-IOV Network Operator manages additional network definitions. When you spe
 Do not edit `NetworkAttachmentDefinition` custom resources that the SR-IOV Network Operator manages. Doing so might disrupt network traffic on your additional network.
 ====
 
-To create an additional SR-IOV network attachment with the CNI VRF plugin, perform the following procedure.
+To create an additional SR-IOV network attachment with the CNI virtual routing and forwarding (VRF) plugin, perform the following procedure.
 
 .Prerequisites
 
@@ -52,8 +52,8 @@ spec:
       "vrfname": "example-vrf-name" <2>
     }
 ----
-<1> `type` must be set to `vrf`.
-<2> `vrfname` is the name of the VRF that the interface is assigned to. If it does not exist in the pod, it is created.
+<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.
 
 . Create the `SriovNetwork` resource:
 +
@@ -82,8 +82,10 @@ There might be a delay before the SR-IOV Network Operator creates the CR.
 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 is connected to the SR-IOV additional network. Remote shell 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.
+
+. 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]
 ----
@@ -97,10 +99,5 @@ $ ip vrf show
 $ ip link
 ----
 +
-.Example output
-[source,terminal]
-----
-...
-5: net1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master red state UP mode
-...
-----
+Example output: `5: net1: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master red state UP mode`
+

modules/nw-enable-all-multicast-mode-sriov-network.adoc

@@ -133,7 +133,7 @@ $ oc get network-attachment-definitions -n <namespace> <1>
 There might be a delay before the SR-IOV Network Operator creates the CR.
 ====
 
-. Display information about the SR-IOV network resources by running the following command:
+* Display information about the SR-IOV network resources by running the following command:
 +
 [source,terminal]
 ----

modules/nw-multus-add-pod.adoc

@@ -58,7 +58,7 @@ endif::sriov[]
 .Procedure
 
 . Add an annotation to the `Pod` object. Only one of the following annotation formats can be used:
-
++
 .. To attach a secondary network without any customization, add an annotation with the following format. Replace `<network>` with the name of the secondary network to associate with the pod:
 +
 [source,yaml]
@@ -67,11 +67,8 @@ metadata:
   annotations:
     k8s.v1.cni.cncf.io/networks: <network>[,<network>,...] <1>
 ----
-<1> To specify more than one secondary network, separate each network
-with a comma. Do not include whitespace between the comma. If you specify
-the same secondary network multiple times, that pod will have multiple network
-interfaces attached to that network.
-
+<1> To specify more than one secondary network, separate each network with a comma. Do not include whitespace between the comma. If you specify the same secondary network multiple times, that pod will have multiple network interfaces attached to that network.
++
 .. To attach a secondary network with customizations, add an annotation with the following format:
 +
 [source,yaml]
@@ -83,7 +80,7 @@ metadata:
         {
           "name": "<network>", <1>
           "namespace": "<namespace>", <2>
-          "default-route": ["<default-route>"] <3>
+          "default-route": ["<default_route>"] <3>
         }
       ]
 ----

modules/nw-multus-advanced-annotations.adoc

@@ -38,12 +38,17 @@ $ oc edit pod <name>
 ----
 metadata:
   annotations:
-    k8s.v1.cni.cncf.io/networks: '[<network>[,<network>,...]]' <1>
+    k8s.v1.cni.cncf.io/networks: '[<network>[,<network>,...]]'
+# ...
 ----
-<1> Replace `<network>` with a JSON object as shown in the following examples. The single quotes are required.
++
+--
+where:
 
-. In the following example the annotation specifies which network attachment will have the default route,
-using the `default-route` parameter.
+`<network>`:: Replace with a JSON object as shown in the following examples. The single quotes are required.
+--
++
+In the following example the annotation specifies which network attachment will have the default route, using the `default-route` parameter.
 +
 [source,yaml]
 ----
@@ -66,33 +71,36 @@ spec:
     command: ["/bin/bash", "-c", "sleep 2000000000000"]
     image: centos/tools
 ----
-<1> The `name` key is the name of the secondary network to associate
-with the pod.
-<2> The `default-route` key specifies a value of a gateway for traffic to be routed over if no other
-routing entry is present in the routing table. If more than one `default-route` key is specified,
-this will cause the pod to fail to become active.
++
+--
+where:
 
+`name`:: The `name` key is the name of the secondary network to associate
+with the pod.
+`default-route`:: The `default-route` key specifies a value of a gateway for traffic to be routed over if no other routing entry is present in the routing table. If more than one `default-route` key is specified, this will cause the pod to fail to become active.
+--
++
 The default route will cause any traffic that is not specified in other routes to be routed to the gateway.
-
++
 [IMPORTANT]
 ====
 Setting the default route to an interface other than the default network interface for {product-title}
 may cause traffic that is anticipated for pod-to-pod traffic to be routed over another interface.
 ====
-
++
 To verify the routing properties of a pod, the `oc` command may be used to execute the `ip` command within a pod.
-
++
 [source,terminal]
 ----
 $ oc exec -it <pod_name> -- ip route
 ----
-
++
 [NOTE]
 ====
 You may also reference the pod's `k8s.v1.cni.cncf.io/network-status` to see which secondary network has been
 assigned the default route, by the presence of the `default-route` key in the JSON-formatted list of objects.
 ====
-
++
 To set a static IP address or MAC address for a pod you can use the JSON formatted annotations. This requires you create networks that specifically allow for this functionality. This can be specified in a rawCNIConfig for the CNO.
 
 . Edit the CNO CR by running the following command:
@@ -101,9 +109,9 @@ To set a static IP address or MAC address for a pod you can use the JSON formatt
 ----
 $ oc edit networks.operator.openshift.io cluster
 ----
-
++
 The following YAML describes the configuration parameters for the CNO:
-
++
 .Cluster Network Operator YAML configuration
 [source,terminal,subs="attributes+"]
 ----
@@ -114,15 +122,17 @@ rawCNIConfig: '{ <3>
 }'
 type: Raw
 ----
-<1> Specify a name for the secondary network attachment that you are
-creating. The name must be unique within the specified `namespace`.
-<2> Specify the namespace to create the network attachment in. If
-you do not specify a value, then the `default` namespace is used.
-<3> Specify the CNI plugin configuration in JSON format, which
-is based on the following template.
++
+--
+where:
 
+`name`:: Specify a name for the secondary network attachment that you are creating. The name must be unique within the specified `namespace`.
+`namespace`:: Specify the namespace to create the network attachment in. If you do not specify a value, then the `default` namespace is used.
+`rawCNIConfig`:: Specify the CNI plugin configuration in JSON format, which is based on the following template.
+--
++
 The following object describes the configuration parameters for utilizing static MAC address and IP address using the macvlan CNI plugin:
-
++
 .macvlan CNI plugin JSON configuration object using static IP and MAC address
 [source,json]
 ----
@@ -143,28 +153,28 @@ The following object describes the configuration parameters for utilizing static
     }]
 }
 ----
-
-<1> Specifies the name for the secondary network attachment to create. The name must be unique within the specified `namespace`.
-
-<2> Specifies an array of CNI plugin configurations. The first object specifies a macvlan plugin configuration and the second object specifies a tuning plugin configuration.
-
-<3> Specifies that a request is made to enable the static IP address functionality of the CNI plugin runtime configuration capabilities.
-
-<4> Specifies the interface that the macvlan plugin uses.
-
-<5> Specifies that a request is made to enable the static MAC address functionality of a CNI plugin.
-
++
+--
+where:
+
+`name`:: Specifies the name for the secondary network attachment to create. The name must be unique within the specified `namespace`.
+`plugins`:: Specifies an array of CNI plugin configurations. The first object specifies a macvlan plugin configuration and the second object specifies a tuning plugin configuration.
+`ips`:: Specifies that a request is made to enable the static IP address functionality of the CNI plugin runtime configuration capabilities.
+`master`:: Specifies the interface that the macvlan plugin uses.
+`mac`:: Specifies that a request is made to enable the static MAC address functionality of a CNI plugin.
+--
++
 The above network attachment can be referenced in a JSON formatted annotation, along with keys to specify which static IP and MAC address will be assigned to a given pod.
-
++
 Edit the pod with:
-
++
 [source,terminal]
 ----
 $ oc edit pod <name>
 ----
-
++
 .macvlan CNI plugin JSON configuration object using static IP and MAC address
-
++
 [source,yaml]
 ----
 apiVersion: v1
@@ -180,20 +190,17 @@ metadata:
       }
     ]'
 ----
-
 <1> Use the `<name>` as provided when creating the `rawCNIConfig` above.
-
 <2> Provide an IP address including the subnet mask.
-
 <3> Provide the MAC address.
-
++
 [NOTE]
 ====
 Static IP addresses and MAC addresses do not have to be used at the same time, you may use them individually, or together.
 ====
-
-To verify the IP address and MAC properties of a pod with secondary networks, use the `oc` command to execute the ip command within a pod.
-
++
+. To verify the IP address and MAC properties of a pod with secondary networks, use the `oc` command to execute the ip command within a pod.
++
 [source,terminal]
 ----
 $ oc exec -it <pod_name> -- ip a

modules/nw-multus-ipam-object.adoc

@@ -13,7 +13,7 @@
 [id="nw-multus-ipam-object_{context}"]
 = Configuration of IP address assignment for a network attachment
 
-For secondary networks, IP addresses can be assigned using an IP Address Management (IPAM) CNI plugin, which supports various assignment methods, including Dynamic Host Configuration Protocol (DHCP) and static assignment.
+For secondary networks, you can assign IP addresses by using an IP Address Management (IPAM) CNI plugin, which supports various assignment methods, including Dynamic Host Configuration Protocol (DHCP) and static assignment.
 
 The DHCP IPAM CNI plugin responsible for dynamic assignment of IP addresses operates with two distinct components:
 
@@ -22,17 +22,18 @@ The DHCP IPAM CNI plugin responsible for dynamic assignment of IP addresses oper
 
 For networks requiring `type: dhcp` in their IPAM configuration, ensure the following:
 
-* A DHCP server is available and running in the environment. The DHCP server is external to the cluster and is expected to be part of the customer's existing network infrastructure.
+* A DHCP server is available and running in the environment. 
+* The DHCP server is external to the cluster and you expect the server to form part of the existing network infrastructure for the customer.
 * The DHCP server is appropriately configured to serve IP addresses to the nodes.
 
-In cases where a DHCP server is unavailable in the environment, it is recommended to use the Whereabouts IPAM CNI plugin instead. The Whereabouts CNI provides similar IP address management capabilities without the need for an external DHCP server.
+In cases where a DHCP server is unavailable in the environment, consider using the Whereabouts IPAM CNI plugin instead. The Whereabouts CNI provides similar IP address management capabilities without the need for an external DHCP server.
 
 [NOTE]
 ====
-Use the Whereabouts CNI plugin when there is no external DHCP server or where static IP address management is preferred. The Whereabouts plugin includes a reconciler daemon to manage stale IP address allocations.
+Use the Whereabouts CNI plugin when no external DHCP server exists or where static IP address management is preferred. The Whereabouts plugin includes a reconciler daemon to manage stale IP address allocations.
 ====
 
-A DHCP lease must be periodically renewed throughout the container's lifetime, so a separate daemon, the DHCP IPAM CNI Daemon, is required. To deploy the DHCP IPAM CNI daemon, modify the Cluster Network Operator (CNO) configuration to trigger the deployment of this daemon as part of the secondary network setup.
+Ensure the periodic renewal of a DHCP lease throughout the lifetime of a container by including a separate daemon, the DHCP IPAM CNI Daemon. To deploy the DHCP IPAM CNI daemon, change the Cluster Network Operator (CNO) configuration to trigger the deployment of this daemon as part of the secondary network setup.
 
 ////
 IMPORTANT: If you set the `type` parameter to the `DHCP` value, you cannot set any other parameters.
@@ -75,7 +76,7 @@ The `addresses` array requires objects with the following fields:
 
 |`address`
 |`string`
-|An IP address and network prefix that you specify. For example, if you specify `10.10.21.10/24`, then the secondary network is assigned an IP address of `10.10.21.10` and the netmask is `255.255.255.0`.
+|An IP address and network prefix that you specify. For example, if you specify `10.10.21.10/24`, the secondary network gets assigned an IP address of `10.10.21.10` and the netmask of `255.255.255.0`.
 
 |`gateway`
 |`string`
@@ -94,7 +95,7 @@ The `addresses` array requires objects with the following fields:
 
 |`gw`
 |`string`
-|The gateway where network traffic is routed.
+|The gateway that routes network traffic.
 
 |====
 
@@ -105,7 +106,7 @@ The `addresses` array requires objects with the following fields:
 
 |`nameservers`
 |`array`
-|An array of one or more IP addresses for to send DNS queries to.
+|An array of one or more IP addresses where DNS queries get sent.
 
 |`domain`
 |`array`
@@ -165,33 +166,10 @@ spec:
         "cniVersion": "0.3.1",
         "type": "bridge",
         "ipam": {
-          "type": "dhcp"
+          "type": "dhcp" <1>
         }
       }
   # ...
 ----
+<1> Specifies dynamic IP address (DHCP) assignment for the cluster.
 
-The following table describes the configuration parameters for dynamic IP address address assignment with DHCP.
-
-.`ipam` DHCP configuration object
-[cols=".^2,.^2,.^6",options="header"]
-|====
-|Field|Type|Description
-
-|`type`
-|`string`
-|The IPAM address type. The value `dhcp` is required.
-
-|====
-
-The following JSON example describes the configuration p for dynamic IP address address assignment with DHCP.
-
-.Dynamic IP address (DHCP) assignment configuration example
-[source,json]
-----
-{
-  "ipam": {
-    "type": "dhcp"
-  }
-}
-----

modules/nw-multus-whereabouts.adoc

@@ -10,7 +10,7 @@
 
 The Whereabouts CNI plugin helps the dynamic assignment of an IP address to a secondary network without the use of a DHCP server.
 
-The Whereabouts CNI plugin also supports overlapping IP address ranges and configuration of the same CIDR range multiple times within separate `NetworkAttachmentDefinition` CRDs. This provides greater flexibility and management capabilities in multi-tenant environments.
+The Whereabouts CNI plugin also supports overlapping IP address ranges and configuration of the same CIDR range multiple times within separate `NetworkAttachmentDefinition` CRDs. This provides greater flexibility and management capabilities in multitenant environments.
 
 [id="dynamic-ip-address-assignment-objects_{context}"]
 == Dynamic IP address configuration parameters
@@ -63,7 +63,7 @@ The following example shows a dynamic address assignment configuration in a NAD
 [id="dynamic-ip-address-assignment-whereabouts-overlapping-ip-ranges_{context}"]
 == Dynamic IP address assignment that uses Whereabouts with overlapping IP address ranges
 
-The following example shows a dynamic IP address assignment that uses overlapping IP address ranges for multi-tenant networks. 
+The following example shows a dynamic IP address assignment that uses overlapping IP address ranges for multitenant networks. 
 
 .NetworkAttachmentDefinition 1
 [source,json]