Merge pull request #103580 from stevsmit/16834-416-cp

[enterprise-4.16] ADV error resolution for MNW

Author: stevsmit

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]
 ----
@@ -148,7 +150,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 an additional 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 an additional 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.
@@ -65,8 +63,8 @@ metadata:
       "name": "net1"
     },
     {
-      "name": "net2", <1>
-      "default-route": ["192.0.2.1"] <2>
+      "name": "net2",
+      "default-route": ["192.0.2.1"]
     }]'
 spec:
   containers:
@@ -78,9 +76,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.
@@ -118,9 +116,9 @@ The following YAML describes the configuration parameters for the CNO:
 .Cluster Network Operator YAML configuration
 [source,yaml]
 ----
-name: <name> <1>
-namespace: <namespace> <2>
-rawCNIConfig: '{ <3>
+name: <name>
+namespace: <namespace>
+rawCNIConfig: '{
   ...
 }'
 type: Raw
@@ -129,9 +127,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:
@@ -141,17 +139,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"
     }]
 }
@@ -168,8 +166,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]
 ----
@@ -187,24 +186,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,9 +6,8 @@
 [id="nw-multus-delete-network_{context}"]
 = Removing an additional network attachment definition
 
-As a cluster administrator, you can remove an additional network from your
-{product-title} cluster. The additional 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
 
@@ -17,10 +16,7 @@ is attached to.
 
 .Procedure
 
-To remove an additional network from your cluster, complete the following steps:
-
-. Edit the Cluster Network Operator (CNO) in your default text editor by running
-the following command:
+. Edit the Cluster Network Operator (CNO) in your default text editor by running the following command:
 +
 [source,terminal]
 ----
@@ -37,11 +33,23 @@ kind: Network
 metadata:
   name: cluster
 spec:
-  additionalNetworks: [] <1>
+  additionalNetworks: []
 ----
-<1>  If you are removing the configuration mapping for the only additional
-network attachment definition in the `additionalNetworks` collection, you must
-specify an empty collection.
++
+--
+where:
+
+`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_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 an additional network attachment definition
 
-As a cluster administrator, you can make changes to an existing additional
-network. Any existing pods attached to the additional 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 additional network will not be update
 
 .Procedure
 
-To edit an additional 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 additional 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 additional 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 an additional network
 
-You can remove a pod from an additional 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 an additional 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/attaching-pod.adoc

@@ -6,7 +6,9 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-As a cluster user you can attach a pod to an additional 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]
 include::modules/nw-multus-advanced-annotations.adoc[leveloffset=+2]

networking/multiple_networks/edit-additional-network.adoc

@@ -6,7 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-As a cluster administrator you can modify the configuration for an existing
-additional 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/remove-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/removing-pod.adoc

@@ -6,6 +6,8 @@ include::_attributes/common-attributes.adoc[]
 
 toc::[]
 
-As a cluster user you can remove a pod from an additional 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]