Merge pull request #103433 from stevsmit/16834-osdocs

ADV error resolution for MNW

Author: dfitzmau

modules/nw-multus-add-pod.adoc

@@ -60,7 +60,7 @@ endif::sriov[]
 
 . 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:
+.. To attach a secondary network without any customization, add an annotation with the following format:
 +
 [source,yaml]
 ----
@@ -71,7 +71,7 @@ metadata:
 +
 where:
 +
-`k8s.v1.cni.cncf.io/networks`:: 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.
+`k8s.v1.cni.cncf.io/networks`:: Specifies the name of the secondary network to associate with the pod. 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:
 +
@@ -91,18 +91,20 @@ metadata:
 +
 where:
 +
-`name`:: Specify the name of the secondary network defined by a `NetworkAttachmentDefinition` object.
-`namespace`:: Specify the namespace where the `NetworkAttachmentDefinition` object is defined.
-`default-route`:: Optional parameter. Specify an override for the default route, such as `192.168.17.1`.
+`name`:: Specifies the name of the secondary network defined by a `NetworkAttachmentDefinition` object.
+`namespace`:: Specifies the namespace where the `NetworkAttachmentDefinition` object is defined.
+`default-route`:: Optional parameter. Specifies an override for the default route, such as `192.168.17.1`.
 
-. To create the pod, enter the following command. Replace `<name>` with the name of the pod.
+. Create the pod by entering the following command.
 +
 [source,terminal]
 ----
 $ oc create -f <name>.yaml
 ----
++
+Replace `<name>` with the name of the pod.
 
-. Optional: To Confirm that the annotation exists in the `Pod` CR, enter the following command, replacing `<name>` with the name of the pod.
+. Optional: Confirm that the annotation exists in the `pod` CR by entering the following command. Replace `<name>` with the name of the pod.
 +
 [source,terminal]
 ----
@@ -147,7 +149,7 @@ status:
 +
 where:
 +
-`k8s.v1.cni.cncf.io/network-status`:: The `k8s.v1.cni.cncf.io/network-status` parameter is a JSON array of
+`k8s.v1.cni.cncf.io/network-status`:: Specifies a JSON array of
 objects. Each object describes the status of a secondary network attached
 to the pod. The annotation value is stored as a plain text value.
 

modules/nw-multus-advanced-annotations.adoc

@@ -6,9 +6,9 @@
 [id="nw-multus-advanced-annotations_{context}"]
 = Specifying pod-specific addressing and routing options
 
-When attaching a pod to a secondary network, you may want to specify further properties
-about that network in a particular pod. This allows you to change some aspects of routing, as well
-as specify static IP addresses and MAC addresses. To accomplish this, you can use the JSON formatted annotations.
+[role="_abstract"]
+You can configure pod-specific addressing and routing options by using JSON-formatted annotations.
+Configuring these options enables you to set static IP addresses, MAC addresses, and default routes for the pod.
 
 .Prerequisites
 
@@ -21,8 +21,6 @@ endif::sriov[]
 
 .Procedure
 
-To add a pod to a secondary network while specifying addressing and/or routing options, complete the following steps:
-
 . Edit the `Pod` resource definition. If you are editing an existing `Pod` resource, run the
 following command to edit its definition in the default editor. Replace `<name>`
 with the name of the `Pod` resource to edit.
@@ -62,8 +60,8 @@ metadata:
       "name": "net1"
     },
     {
-      "name": "net2", <1>
-      "default-route": ["192.0.2.1"] <2>
+      "name": "net2",
+      "default-route": ["192.0.2.1"]
     }]'
 spec:
   containers:
@@ -75,9 +73,9 @@ spec:
 --
 where:
 
-`name`:: The `name` key is the name of the secondary network to associate
+`name`:: Specifies 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.
+`default-route`:: 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.
@@ -115,9 +113,9 @@ The following YAML describes the configuration parameters for the CNO:
 .Cluster Network Operator YAML configuration
 [source,terminal,subs="attributes+"]
 ----
-name: <name> <1>
-namespace: <namespace> <2>
-rawCNIConfig: '{ <3>
+name: <name>
+namespace: <namespace>
+rawCNIConfig: '{
   ...
 }'
 type: Raw
@@ -126,9 +124,9 @@ type: Raw
 --
 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.
+`name`:: Specifies a name for the secondary network attachment that you are creating. The name must be unique within the specified `namespace`.
+`namespace`:: Specifies the namespace to create the network attachment in. If you do not specify a value, then the `default` namespace is used.
+`rawCNIConfig`:: Specifies 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:
@@ -138,17 +136,17 @@ The following object describes the configuration parameters for utilizing static
 ----
 {
   "cniVersion": "0.3.1",
-  "name": "<name>", <1>
-  "plugins": [{ <2>
+  "name": "<name>",
+  "plugins": [{
       "type": "macvlan",
-      "capabilities": { "ips": true }, <3>
-      "master": "eth0", <4>
+      "capabilities": { "ips": true },
+      "master": "eth0",
       "mode": "bridge",
       "ipam": {
         "type": "static"
       }
     }, {
-      "capabilities": { "mac": true }, <5>
+      "capabilities": { "mac": true },
       "type": "tuning"
     }]
 }
@@ -165,8 +163,9 @@ where:
 --
 +
 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:
+
+
+. Edit the pod by entering the following command:
 +
 [source,terminal]
 ----
@@ -184,24 +183,22 @@ metadata:
   annotations:
     k8s.v1.cni.cncf.io/networks: '[
       {
-        "name": "<name>", <1>
-        "ips": [ "192.0.2.205/24" ], <2>
-        "mac": "CA:FE:C0:FF:EE:00" <3>
+        "name": "<name>",
+        "ips": [ "192.0.2.205/24" ],
+        "mac": "CA:FE:C0:FF:EE:00"
       }
     ]'
 ----
-<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.
++
+--
+where:
+
+`name`:: Specifies the name for the secondary network attachment to create. The name must be unique within the specified `namespace`. 
+`ips`:: Specifies an IP address including the subnet mask.
+`mac`:: Specifies 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.
+Static IP addresses and MAC addresses do not have to be used at the same time. You can 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.
-+
-[source,terminal]
-----
-$ oc exec -it <pod_name> -- ip a
-----

modules/nw-multus-delete-network.adoc

@@ -6,7 +6,8 @@
 [id="nw-multus-delete-network_{context}"]
 = Removing a secondary network attachment definition
 
-As a cluster administrator, you can remove a secondary network from your {product-title} cluster. The secondary network is not removed from any pods it is attached to.
+[role="_abstract"]
+As a cluster administrator, you can remove a secondary network from your {product-title} cluster. The secondary network is not removed from any pods that it is attached to.
 
 .Prerequisites
 
@@ -15,8 +16,6 @@ As a cluster administrator, you can remove a secondary network from your {produc
 
 .Procedure
 
-To remove a secondary network from your cluster, complete the following steps:
-
 . Edit the Cluster Network Operator (CNO) in your default text editor by running the following command:
 +
 [source,terminal]
@@ -33,17 +32,23 @@ kind: Network
 metadata:
   name: cluster
 spec:
-  additionalNetworks: [] <1>
+  additionalNetworks: []
 ----
-<1>  If you are removing the configuration mapping for the only secondary network attachment definition in the `additionalNetworks` collection, you must specify an empty collection.
++
+--
+where:
 
-. To remove a network attachment definition from the network of your cluster, enter the following command:
+`additionalNetworks`:: Specifies the secondary network attachment definition that you want to remove from the `additionalNetworks` collection. If you are removing the configuration mapping for the only secondary network attachment definition in the `additionalNetworks` collection, you must specify an empty collection.
+--
+
+. Remove a network attachment definition from the network of your cluster by entering the following command:
 +
 [source,terminal]
 ----
-$ oc delete net-attach-def <name_of_NAD> <1>
+$ oc delete net-attach-def <name_of_network_attachment_definition>
 ----
-<1> Replace `<name_of_NAD>` with the name of your network attachment definition.
++
+Replace `<name_of_network_attachment_definition>` with the name of the network attachment definition that you want to remove.
 
 . Save your changes and quit the text editor to commit your changes.
 

modules/nw-multus-edit-network.adoc

@@ -6,8 +6,9 @@
 [id="nw-multus-edit-network_{context}"]
 = Modifying a secondary network attachment definition
 
-As a cluster administrator, you can make changes to an existing secondary
-network. Any existing pods attached to the secondary network will not be updated.
+[role="_abstract"]
+You can modify a secondary network attachment definition.
+You modify the attachment definition to update network settings or change network parameters.
 
 .Prerequisites
 
@@ -17,26 +18,22 @@ network. Any existing pods attached to the secondary network will not be updated
 
 .Procedure
 
-To edit a secondary network for your cluster, complete the following steps:
-
-. Run the following command to edit the Cluster Network Operator (CNO) CR in
-your default text editor:
+. Edit the Cluster Network Operator (CNO) CR in your default text editor by running the following command:
 +
 [source,terminal]
 ----
 $ oc edit networks.operator.openshift.io cluster
 ----
 
-. In the `additionalNetworks` collection, update the secondary network with
-your changes.
+. In the `additionalNetworks` collection, update the secondary network with your changes.
 
 . Save your changes and quit the text editor to commit your changes.
 
-. Optional: Confirm that the CNO updated the `NetworkAttachmentDefinition` object by running the following command. Replace `<network-name>` with the name of the secondary network to display. There might be a delay before the CNO updates the `NetworkAttachmentDefinition` object to reflect your changes.
+. Optional: Confirm that the CNO updated the `NetworkAttachmentDefinition` object by running the following command. Replace `<network_name>` with the name of the secondary network to display. There might be a delay before the CNO updates the `NetworkAttachmentDefinition` object to reflect your changes.
 +
 [source,terminal]
 ----
-$ oc get network-attachment-definitions <network-name> -o yaml
+$ oc get network-attachment-definitions <network_name> -o yaml
 ----
 +
 For example, the following console output displays a `NetworkAttachmentDefinition` object that is named `net1`:

modules/nw-multus-remove-pod.adoc

@@ -3,12 +3,13 @@
 // * networking/multiple_networks/removing-pod.adoc
 // * microshift_networking/microshift_multiple_networks/microshift-cni-multus-using.adoc
 
-
 :_mod-docs-content-type: PROCEDURE
 [id="nw-multus-remove-pod_{context}"]
 = Removing a pod from a secondary network
 
-You can remove a pod from a secondary network only by deleting the pod.
+[role="_abstract"]
+You can remove a pod from a secondary network.
+You remove pods from secondary networks to disconnect them from specific network configurations.
 
 .Prerequisites
 
@@ -18,14 +19,16 @@ You can remove a pod from a secondary network only by deleting the pod.
 
 .Procedure
 
-* To delete the pod, enter the following command:
+* Delete the pod by entering the following command:
 +
 [source,terminal]
 ----
 $ oc delete pod <name> -n <namespace>
 ----
 +
 --
-* `<name>` is the name of the pod.
-* `<namespace>` is the namespace that contains the pod.
+where:
+
+`<name>`:: Specifies the name of the pod.
+`<namespace>`:: Specifies the namespace that contains the pod.
 --

networking/multiple_networks/secondary_networks/attaching-pod.adoc

@@ -6,7 +6,9 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-As a cluster user you can attach a pod to a secondary network.
+[role="_abstract"]
+You can attach a pod to a secondary network.
+Attaching a pod to a secondary network enables the pod to use additional network interfaces beyond the primary cluster network.
 
 include::modules/nw-multus-add-pod.adoc[leveloffset=+1]
 

networking/multiple_networks/secondary_networks/editing-additional-network.adoc

@@ -6,6 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-As a cluster administrator you can modify the configuration for an existing secondary network.
+[role="_abstract"]
+You can modify the configuration for an existing secondary network.
+You modify secondary networks to update network settings or change network parameters.
 
 include::modules/nw-multus-edit-network.adoc[leveloffset=+1]

networking/multiple_networks/secondary_networks/removing-additional-network.adoc

@@ -6,6 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-As a cluster administrator you can remove an additional network attachment.
+[role="_abstract"]
+You can remove an additional network attachment.
+You remove additional networks to clean up unused network configurations or free up network resources.
 
 include::modules/nw-multus-delete-network.adoc[leveloffset=+1]

networking/multiple_networks/secondary_networks/removing-pod.adoc

@@ -6,6 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-As a cluster user you can remove a pod from a secondary network.
+[role="_abstract"]
+You can remove a pod from a secondary network.
+You remove pods from secondary networks to disconnect them from specific network configurations.
 
 include::modules/nw-multus-remove-pod.adoc[leveloffset=+1]