Clarify and expand content for additional networks

- openshift#16349

Author: jboxman

_topic_map.yml

@@ -299,6 +299,10 @@ Topics:
   Topics:
   - Name: Understanding multiple networks
     File: understanding-multiple-networks
+  - Name: Attaching a Pod to an additional network
+    File: attaching-pod
+  - Name: Removing a Pod from an additional network
+    File: removing-pod
   - Name: Configuring a bridge network
     File: configuring-bridge
   - Name: Configuring a macvlan network
@@ -309,6 +313,10 @@ Topics:
     File: configuring-host-device
   - Name: Configuring SR-IOV
     File: configuring-sr-iov
+  - Name: Editing an additional network
+    File: edit-additional-network
+  - Name: Removing an additional network
+    File: remove-additional-network
 - Name: OpenShift SDN
   Dir: openshift-sdn
   Topics:

modules/nw-multus-add-pod.adoc

@@ -1,14 +1,16 @@
 // Module included in the following assemblies:
 //
+// * networking/multiple-networks/attaching-pod.adoc
 
 [id="nw-multus-add-pod_{context}"]
 = Adding a Pod to an additional network
 
-You can add a Pod to an additional network. {product-title} will continue using
-the primary network for normal cluster related network traffic.
+You can add a Pod to an additional network. The Pod continues to send normal
+cluster related network traffic over the default network.
 
 .Prerequisites
 
+* The Pod must be in the same namespace as the additional network.
 * Install the OpenShift Command-line Interface (CLI), commonly known as `oc`.
 * You must log in to the cluster.
 
@@ -26,8 +28,7 @@ $ oc edit pod <name>
 
 . In the Pod resource definition, add the `k8s.v1.cni.cncf.io/networks`
 parameter to the Pod `metadata` mapping. The `k8s.v1.cni.cncf.io/networks`
-accepts a comma separated string of one or more `AdditionalNetworkDefinition`
-names:
+accepts a comma separated string of one or more NetworkAttachmentDefinition Custom Resource (CR) names:
 +
 [source,yaml] 
 ----
@@ -59,8 +60,47 @@ spec:
 ----
 
 . Optional: Confirm that the annotation exists in the Pod CR by running the
-following command:
+following command. Replace `<name>` with the name of the Pod.
 +
 ----
 $ oc describe pod <name>
 ----
++
+In the following example, the `example-pod` Pod is attached to the `net1`
+additional network:
++
+----
+$ oc get pod example-pod -o yaml
+apiVersion: v1
+kind: Pod
+metadata:
+  annotations:
+    k8s.v1.cni.cncf.io/networks: macvlan-bridge
+    k8s.v1.cni.cncf.io/networks-status: |- <1>
+      [{
+          "name": "openshift-sdn",
+          "interface": "eth0",
+          "ips": [
+              "10.128.2.14"
+          ],
+          "default": true,
+          "dns": {}
+      },{
+          "name": "macvlan-bridge",
+          "interface": "net1",
+          "ips": [
+              "20.2.2.100"
+          ],
+          "mac": "22:2f:60:a5:f8:00",
+          "dns": {}
+      }]
+  name: example-pod
+  namespace: default
+spec:
+  ...
+status:
+  ...
+----
+<1> The `k8s.v1.cni.cncf.io/networks-status` parameter is a JSON array of
+objects. Each object describes the status of an additional network attached
+to the Pod. The annotation value is stored as a plain text value.

modules/nw-multus-bridge-object.adoc

@@ -1,26 +1,44 @@
 // Module included in the following assemblies:
 //
+// * networking/multiple-networks/configuring-bridge.adoc
 
 [id="nw-multus-bridge-object_{context}"]
 = Configuration for bridge
 
-// TODO - duplicated in ipvlan, copy changes from there to here.
+The configuration for an additional network attachment that uses the bridge
+Container Network Interface (CNI) plug-in is provided in two parts:
 
-.bridge CNI plug-in YAML configuration
+* Cluster Network Operator (CNO) configuration
+* CNI plug-in configuration
+
+The CNO configuration specifies the name for the additional network attachment
+and the namespace to create the attachment in. The plug-in
+is configured by a JSON object specified by the `rawCNIConfig` parameter in
+the CNO configuration.
+
+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>
+rawCNIConfig: '{ <3>
+  ...  
+}'
 type: Raw
 ----
-<1> `name`: Specify the name of the `NetworkAttachmentDefinition` created from
-the `rawCNIConfig` JSON object.
+<1> Specify a name for the additional 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.
 
-<2> `namespace`: Specify the namespace to create the network attachment in. If
-a value is not specified, the `default` namespace is used.
+<3> Specify the CNI plug-in configuration in JSON format, which
+is based on the following template.
 
-<3> `rawCNIConfig`: Specify the CNI plug-in configuration.
+The following object describes the configuration parameters for the bridge CNI
+plug-in:
 
 .bridge CNI plug-in JSON configuration object
 [source,json]
@@ -43,42 +61,65 @@ a value is not specified, the `default` namespace is used.
   "mtu": <mtu> <11>
 }
 ----
-<1> `name`: Specify the name of the `NetworkAttachmentDefinition`.
+<1> Specify the value for the `name` parameter you provided previously for
+the CNO configuration.
 
-<2> `bridge`: Specify the name of the virtual bridge to use. If the bridge
+<2> Specify the name of the virtual bridge to use. If the bridge
 interface does not exist on the host, it is created. The default value is
 `cni0`.
 
-<3> `ipam`: Specify a configuration object for the ipam CNI plug-in. The plug-in
+<3> Specify a configuration object for the ipam CNI plug-in. The plug-in
 manages IP address assignment for the network attachment definition.
 
-<4> `ipMasq`: Set to `true` to enable IP masquerading for traffic that leaves the
+<4> Set to `true` to enable IP masquerading for traffic that leaves the
 virtual network. The source IP address for all traffic is rewritten to the
 bridge's IP address. If the bridge does not have an IP address, this setting has
 no effect. The default value is `false`.
 
-<5> `isGateway`: Set to `true` to assign an IP address to the bridge. The
+<5> Set to `true` to assign an IP address to the bridge. The
 default value is `false`.
 
-<6> `isDefaultGateway`: Set to `true` to configure the bridge as the default
+<6> Set to `true` to configure the bridge as the default
 gateway for the virtual network. The default value is `false`. If
 `isDefaultGateway` is set to `true`, then `isGateway` is also set to `true`
 automatically. 
 
-<7> `forceAddress`: Set to `true` to allow assignment of a previously assigned
+<7> Set to `true` to allow assignment of a previously assigned
 IP address to the virtual bridge. When set to `false`, if an IPv4 address or an
 IPv6 address from overlapping subsets is assigned to the virtual bridge, an
 error occurs. The default value is `false`.
 
-<8> `hairpinMode`: Set to `true` to allow the virtual bridge to send an ethernet
+<8> Set to `true` to allow the virtual bridge to send an ethernet
 frame back through the virtual port it was received on. This mode is also known
 as _reflective relay_. The default value is `false`.
 
-<9> `promiscMode`: Set to `true` to enable promiscuous mode on the bridge. The
+<9> Set to `true` to enable promiscuous mode on the bridge. The
 default value is `false`.
 
-<10> `vlan`: Specify a virtual LAN (VLAN) tag as an integer value. By default,
+<10> Specify a virtual LAN (VLAN) tag as an integer value. By default,
 no VLAN tag is assigned.
 
-<11> `mtu`: Set the maximum transmission unit (MTU) to the specified value. The
-default value is automatically chosen by the kernel.
+<11> Set the maximum transmission unit (MTU) to the specified value. The
+default value is automatically set by the kernel.
+
+[id="nw-multus-bridge-config-example_{context}"]
+== bridge configuration example
+
+The following example configures an additional network named `bridge-net`:
+
+[source,yaml]
+----
+name: bridge-net
+type: Raw
+rawCNIConfig: '{ <1>
+  "cniVersion": "0.3.1",
+  "type": "bridge",
+  "master": "eth1",
+  "isGateway": true,
+  "vlan": 2,
+  "ipam": {
+    "type": "dhcp"
+    }
+}'
+----
+<1> The CNI configuration object is specified as a YAML string.

modules/nw-multus-create-network.adoc

@@ -1,5 +1,9 @@
 // Module included in the following assemblies:
 //
+// * networking/multiple-networks/configuring-macvlan.adoc
+// * networking/multiple-networks/configuring-ipvlan.adoc
+// * networking/multiple-networks/configuring-bridge.adoc
+// * networking/multiple-networks/configuring-host-device.adoc
 
 // Configuring Multus plug-ins using the Cluster Network Operator
 // is nearly identical in each case.
@@ -26,11 +30,11 @@ endif::[]
 
 The Cluster Network Operator (CNO) manages additional network definitions. When
 you specify an additional network to create, the CNO creates the
-`NetworkAttachmentDefinition` Custom Resource (CR) automatically.
+NetworkAttachmentDefinition Custom Resource (CR) automatically.
 
 [IMPORTANT]
 ====
-Do not edit the `NetworkAttachmentDefinition` CRs that the Cluster Network
+Do not edit the NetworkAttachmentDefinition CRs that the Cluster Network
 Operator manages. Doing so might disrupt network traffic on your additional
 network.
 ====
@@ -44,14 +48,14 @@ network.
 
 To create an additional network for your cluster, complete the following steps:
 
-. Run the following command to edit the CNO CR:
+. Edit the CNO CR by running the following command:
 +
 ----
 $ oc edit networks.operator.openshift.io cluster
 ----
 
 . Modify the CR that you are creating by adding the configuration for the
-additional network you are creating.
+additional network you are creating, as in the following example CR.
 +
 ifdef::yaml[]
 The following YAML configures the {plugin} CNI plug-in:
@@ -68,7 +72,10 @@ spec:
     type: SimpleMacvlan
     simpleMacvlanConfig:
       ipamConfig:
-        type: DHCP
+        type: static
+        staticIPAMConfig:
+          addresses:
+          - address: 10.1.1.0/24
 ----
 endif::yaml[]
 ifdef::json[]
@@ -91,8 +98,13 @@ spec:
       "type": "{plugin}",
       "master": "eth1",
       "ipam": {
-        "type": "dhcp"
-        }
+        "type": "static",
+        "addresses": [
+          {
+            "address": "191.168.1.1/24"
+          }
+        ]
+      }
     }'
 ----
 endif::[]
@@ -131,17 +143,21 @@ spec:
       "master": "eth1",
       "mode": "l2",
       "ipam": {
-        "type": "dhcp"
-        }
+        "type": "static",
+        "addresses": [
+          {
+            "address": "191.168.1.1/24"
+          }
+        ]
+      }
     }'
 ----
 endif::[]
-<1> `additionalNetworks`: Specify the configuration for the additional network
-attachment definition.
+<1> Specify the configuration for the additional network attachment definition.
 
 . Save your changes and quit the text editor to commit your changes.
 
-. Optional: Confirm that the CNO created the `NetworkAttachmentDefinition` CR by
+. Optional: Confirm that the CNO created the NetworkAttachmentDefinition CR by
 running the following command. There might be a delay before the CNO creates the
 CR.
 +

modules/nw-multus-delete-network.adoc

@@ -1,5 +1,6 @@
 // Module included in the following assemblies:
 //
+// * networking/multiple-networks/remove-additional-network.adoc
 
 [id="nw-multus-delete-network_{context}"]
 = Removing an additional network attachment definition
@@ -24,8 +25,8 @@ For more information, see link:https://bugzilla.redhat.com/show_bug.cgi?id=17559
 
 To remove an additional network from your cluster, complete the following steps:
 
-. Run the following command to edit the Cluster Network Operator (CNO) in your
-default text editor:
+. Edit the Cluster Network Operator (CNO) in your default text editor by running
+the following command:
 +
 ----
 $ oc edit networks.operator.openshift.io cluster

modules/nw-multus-edit-network.adoc

@@ -1,14 +1,16 @@
 // Module included in the following assemblies:
 //
+// * networking/multiple-networks/edit-additional-network.adoc
 
 [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.
+network. Any existing Pods attached to the additional network will not be updated.
 
 .Prerequisites
 
+* You have configured an additional network for your cluster.
 * Install the OpenShift Command-line Interface (CLI), commonly known as `oc`.
 * Log in as a user with `cluster-admin` privileges.
 
@@ -28,17 +30,17 @@ your changes.
 
 . Save your changes and quit the text editor to commit your changes.
 
-. Optional: Confirm that the CNO updated the `NetworkAttachmentDefinition` CR by
+. Optional: Confirm that the CNO updated the NetworkAttachmentDefinition CR 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` CR to reflect your changes.
+NetworkAttachmentDefinition CR to reflect your changes.
 +
 ----
 $ oc get network-attachment-definitions <network-name> -o yaml
 ----
 +
 For example, the following console output displays a
-`NetworkAttachmentDefinition` that is named `net1`:
+NetworkAttachmentDefinition that is named `net1`:
 +
 ----
 $ oc get network-attachment-definitions net1 -o go-template='{{printf "%s\n" .spec.config}}'