[enterprise-4.2] OSDOCS-475: Update content for multiple networks

_topic_map.yml

@@ -285,12 +285,25 @@ Topics:
   File: dns-operator
 - Name: Understanding the Ingress Operator
   File: ingress-operator
-- Name: Multiple networks
-  File: managing-multinetworking
-  Distros: openshift-enterprise,openshift-origin
 - Name: Configuring network policy
   File: configuring-networkpolicy
   Distros: openshift-origin,openshift-enterprise
+- Name: Multiple networks
+  Dir: multiple-networks
+  Distros: openshift-enterprise,openshift-origin
+  Topics:
+  - Name: Understanding multiple networks
+    File: understanding-multiple-networks
+  - Name: Configuring a bridge network
+    File: configuring-bridge
+  - Name: Configuring a macvlan network
+    File: configuring-macvlan
+  - Name: Configuring an ipvlan network
+    File: configuring-ipvlan
+  - Name: Configuring a host-device network
+    File: configuring-host-device
+  - Name: Configuring SR-IOV
+    File: configuring-sr-iov
 - Name: OpenShift SDN
   Dir: openshift-sdn
   Topics:

modules/nw-multus-add-pod.adoc

@@ -0,0 +1,66 @@
+// Module included in the following assemblies:
+//
+
+[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.
+
+.Prerequisites
+
+* Install the OpenShift Command-line Interface (CLI), commonly known as `oc`.
+* You must log in to the cluster.
+
+.Procedure
+
+To add a Pod to an additional network, complete the following steps:
+
+. Edit the Pod resource definition. If you are editing an existing Pod, run the
+following command to edit its definition in the default editor. Replace `<name>`
+with the name of the Pod to edit.
++
+----
+$ 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:
++
+[source,yaml] 
+----
+metadata:
+  annotations:
+    k8s.v1.cni.cncf.io/networks: <network>[,<network>,...] <1>
+----
+<1> Replace `<network>` with the name of the additional network to associate
+with the Pod. To specify more than one additional network, separate each network
+with a comma. Do not include whitespace between the comma. If you specify
+the same additional network multiple times, that Pod will have multiple network
+interfaces attached to that network.
++
+In the following example, two additional networks are attached to the Pod:
++
+[source,yaml]
+----
+apiVersion: v1
+kind: Pod
+metadata:
+  name: example-pod
+  annotations:
+    k8s.v1.cni.cncf.io/networks: net1,net2
+spec:
+  containers:
+  - name: example-pod
+    command: ["/bin/bash", "-c", "sleep 2000000000000"]
+    image: centos/tools
+----
+
+. Optional: Confirm that the annotation exists in the Pod CR by running the
+following command:
++
+----
+$ oc describe pod <name>
+----

modules/nw-multus-bridge-object.adoc

@@ -0,0 +1,84 @@
+// Module included in the following assemblies:
+//
+
+[id="nw-multus-bridge-object_{context}"]
+= Configuration for bridge
+
+// TODO - duplicated in ipvlan, copy changes from there to here.
+
+.bridge CNI plug-in YAML configuration
+[source,yaml]
+----
+name: <name> <1>
+namespace: <namespace> <2>
+rawCNIConfig: '' <3>
+type: Raw
+----
+<1> `name`: Specify the name of the `NetworkAttachmentDefinition` created from
+the `rawCNIConfig` JSON object.
+
+<2> `namespace`: Specify the namespace to create the network attachment in. If
+a value is not specified, the `default` namespace is used.
+
+<3> `rawCNIConfig`: Specify the CNI plug-in configuration.
+
+.bridge CNI plug-in JSON configuration object
+[source,json]
+----
+{
+  "cniVersion": "0.3.1",
+  "name": "<name>", <1>
+  "type": "bridge",
+  "bridge": "<bridge>", <2>
+  "ipam": { <3>
+    ...
+  },
+  "ipMasq": false, <4>
+  "isGateway": false, <5>
+  "isDefaultGateway": false, <6>
+  "forceAddress": false, <7>
+  "hairpinMode": false, <8>
+  "promiscMode": false, <9>
+  "vlan": <vlan>, <10>
+  "mtu": <mtu> <11>
+}
+----
+<1> `name`: Specify the name of the `NetworkAttachmentDefinition`.
+
+<2> `bridge`: 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
+manages IP address assignment for the network attachment definition.
+
+<4> `ipMasq`: 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
+default value is `false`.
+
+<6> `isDefaultGateway`: 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
+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
+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
+default value is `false`.
+
+<10> `vlan`: 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.

modules/nw-multus-create-network.adoc

@@ -0,0 +1,153 @@
+// Module included in the following assemblies:
+//
+
+// Configuring Multus plug-ins using the Cluster Network Operator
+// is nearly identical in each case.
+
+ifeval::["{context}" == "configuring-macvlan"]
+:plugin: macvlan
+:yaml:
+endif::[]
+ifeval::["{context}" == "configuring-ipvlan"]
+:plugin: ipvlan
+:json:
+endif::[]
+ifeval::["{context}" == "configuring-bridge"]
+:plugin: bridge
+:json:
+endif::[]
+ifeval::["{context}" == "configuring-host-device"]
+:plugin: host-device
+:json:
+endif::[]
+
+[id="nw-multus-create-network_{context}"]
+= Creating an additional network attachment with the {plugin} CNI plug-in
+
+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.
+
+[IMPORTANT]
+====
+Do not edit the `NetworkAttachmentDefinition` CRs that the Cluster Network
+Operator manages. Doing so might disrupt network traffic on your additional
+network.
+====
+
+.Prerequisites
+
+* Install the OpenShift Command-line Interface (CLI), commonly known as `oc`.
+* Log in as a user with `cluster-admin` privileges.
+
+.Procedure
+
+To create an additional network for your cluster, complete the following steps:
+
+. Run the following command to edit the CNO CR:
++
+----
+$ 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.
++
+ifdef::yaml[]
+The following YAML configures the {plugin} CNI plug-in:
++
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: Network
+metadata:
+  name: cluster
+spec:
+  additionalNetworks: <1>
+  - name: example-addn-network
+    type: SimpleMacvlan
+    simpleMacvlanConfig:
+      ipamConfig:
+        type: DHCP
+----
+endif::yaml[]
+ifdef::json[]
+The following YAML configures the {plugin} CNI plug-in:
+endif::json[]
++
+ifeval::["{plugin}" == "bridge"]
+[source,yaml,subs="attributes+"]
+----
+apiVersion: operator.openshift.io/v1
+kind: Network
+metadata:
+  name: cluster
+spec:
+  additionalNetworks: <1>
+  - name: test-network-1
+    type: Raw
+    rawCNIConfig: '{
+      "cniVersion": "0.3.1",
+      "type": "{plugin}",
+      "master": "eth1",
+      "ipam": {
+        "type": "dhcp"
+        }
+    }'
+----
+endif::[]
+ifeval::["{plugin}" == "host-device"]
+[source,yaml,subs="attributes+"]
+----
+apiVersion: operator.openshift.io/v1
+kind: Network
+metadata:
+  name: cluster
+spec:
+  additionalNetworks: <1>
+  - name: test-network-1
+    type: Raw
+    rawCNIConfig: '{
+      "cniVersion": "0.3.1",
+      "type": "{plugin}",
+      "device": "eth1"
+    }'
+----
+endif::[]
+ifeval::["{plugin}" == "ipvlan"]
+[source,yaml,subs="attributes+"]
+----
+apiVersion: operator.openshift.io/v1
+kind: Network
+metadata:
+  name: cluster
+spec:
+  additionalNetworks: <1>
+  - name: test-network-1
+    type: Raw
+    rawCNIConfig: '{
+      "cniVersion": "0.3.1",
+      "type": "{plugin}",
+      "master": "eth1",
+      "mode": "l2",
+      "ipam": {
+        "type": "dhcp"
+        }
+    }'
+----
+endif::[]
+<1> `additionalNetworks`: 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
+running the following command. There might be a delay before the CNO creates the
+CR.
++
+----
+$ oc get network-attachment-definitions
+NAME                 AGE
+example-network      14m
+example-macvlan      21m
+----

modules/nw-multus-delete-network.adoc

@@ -0,0 +1,43 @@
+// Module included in the following assemblies:
+//
+
+[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.
+
+.Prerequisites
+
+* Install the OpenShift Command-line Interface (CLI), commonly known as `oc`.
+* Log in as a user with `cluster-admin` privileges.
+
+.Procedure
+
+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:
++
+----
+$ oc edit networks.operator.openshift.io cluster
+----
+
+. Modify the CR by removing the configuration from the `additionalNetworks`
+collection for the network attachment definition you are removing.
++
+[source,yaml]
+----
+apiVersion: operator.openshift.io/v1
+kind: Network
+metadata:
+  name: cluster
+spec:
+  additionalNetworks: [] <1>
+----
+<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.
+
+. Save your changes and quit the text editor to commit your changes.