Merge pull request #74823 from ShaunaDiaz/OSDOCS-9426

OSDOCS-9426: add supported CNIs multus MicroShift

Author: ShaunaDiaz

microshift_networking/microshift_multiple_networks/microshift-cni-multus.adoc

@@ -6,10 +6,23 @@ include::_attributes/attributes-microshift.adoc[]
 
 toc::[]
 
-In addition to the default OVN-Kubernetes Container Network Interface (CNI) plugin, {microshift-short} uses the Multus CNI to chain other CNI plugins.
+In addition to the default OVN-Kubernetes Container Network Interface (CNI) plugin, {microshift-short} uses an implementation of the Multus CNI to chain other CNI plugins.
 
 include::modules/microshift-multus-intro.adoc[leveloffset=+1]
 
-//TODO: add more detail on supported plugins
-
 include::modules/microshift-install-multus-running-cluster.adoc[leveloffset=+1]
+
+//OCP module, edit with conditionals and care
+include::modules/nw-multus-bridge-object.adoc[leveloffset=+1]
+//Q: do we need to remove VLAN from this reference for microshift?
+
+//OCP module, edit with conditionals and care
+include::modules/nw-multus-ipvlan-object.adoc[leveloffset=+1]
+
+//OCP module, edit with conditionals and care
+include::modules/nw-multus-macvlan-object.adoc[leveloffset=+1]
+
+[role="_additional-resources"]
+.Additional resources
+
+//* add cross refs to procedures

modules/microshift-multus-intro.adoc

@@ -6,21 +6,60 @@
 [id="microshift-multus-intro_{context}"]
 = Additional networks in {microshift-short}
 
-During cluster installation, the _default_ pod network is configured with default values unless you customize the configuration. The default network handles all ordinary network traffic for the cluster. Using the Multus CNI plugin, you can add additional interfaces to pods from other networks. This gives you flexibility when you configure pods that deliver network functionality, such as switching or routing.
+During cluster installation, the _default_ pod network is configured with default values unless you customize the configuration. The default network handles all ordinary network traffic for the cluster. Using the {microshift-short} Multus CNI plugin, you can add additional interfaces to pods from other networks. This gives you flexibility when you configure pods that deliver network functionality, such as switching or routing.
 
-[id="additional-network-use-cases"]
+[id="microshift-supported-additional-networks_{context}"]
+== Supported additional networks for network isolation
+The following additional networks are supported in {microshift-short} {product-version}:
+
+* Bridge: Allows pods on the same host to communicate with each other and the host.
+
+* IPVLAN: Allows pods on a host to communicate with other hosts.
+** This is similar to a MACVLAN-based additional network.
+** Each pod shares the same MAC address as the parent physical network interface, unlike a MACVLAN-based additional network.
+
+* MACVLAN: Allows pods on a host to communicate with other hosts and the pods on those other hosts by using a physical network interface. Each pod that is attached to a MACVLAN-based additional network is provided with a unique MAC address.
+
+[NOTE]
+====
+Setting network policies for additional networks is not supported.
+====
+
+[id="microshift-additional-network-use-cases_{context}"]
 == Use case: Additional networks for network isolation
 
-You can use an additional network in situations where network isolation is needed, including control plane and data plane separation. You can create additional interfaces for pods to connect to that network in addition to a default. For example, you can configure an additional interface if you want pods to access a network on the host and also communicate with devices deployed to the edge that are on an isolated operator network or are periodically disconnected.
+You can use an additional network in situations where network isolation is needed, including control plane and data plane separation. You can create additional interfaces for pods to connect to that network in addition to a default. For example, you can configure an additional interface if you want pods to access a network on the host and also communicate with devices deployed to the edge. These edge devices might be on an isolated operator network or are periodically disconnected.
 
 Isolating network traffic is useful for the following performance and security reasons:
 
 Performance:: You can send traffic on two different planes to manage the amount of traffic on each plane.
 Security:: You can send sensitive traffic onto a network plane that is managed specifically for security considerations, and you can separate private data that must not be shared between tenants or customers.
 
-[id="additional-network-how-implemented"]
+[IMPORTANT]
+====
+The Multus CNI plugin is deployed when the {microshift-short} service starts up. Therefore, a host restart is required if the `microshift-multus` RPM package is added after {microshift-short} has started. Restarting ensures that all containers are re-created with Multus annotations.
+====
+
+[id="microshift-additional-network-how-implemented_{context}"]
 == How additional networks are implemented
 
-All of the pods in the cluster still use the cluster-wide default network to maintain connectivity across the cluster. Every pod has an `eth0` interface that is attached to the cluster-wide pod network. You can view the interfaces for a pod by using the `oc exec -it <pod_name> \-- ip a` command. If you add additional network interfaces that use Multus CNI, they are named `net1`, `net2`, ..., `netN`.
+All of the pods in the cluster still use the cluster-wide default network to maintain connectivity across the cluster. Every pod has an `eth0` interface that is attached to the cluster-wide pod network.
+
+* You can view the interfaces for a pod by using the `oc get pod <pod_name> -o=jsonpath='{ .metadata.annotations.k8s\.v1\.cni\.cncf\.io/network-status }'` command.
+* If you add additional network interfaces that use the {microshift-short} Multus CNI, they are named `net1`, `net2`, ..., `netN`.
+* The CNI configuration is created when the {microshift-short} Multus DaemonSet starts. This configuration is autogenerated and includes the primary CNI that is the default delegate. For {microshift-short}, the default CNI is OVN-Kubernetes.
+
+[id="microshift-additional-network-how-attached-pods_{context}"]
+== How to attached additional networks to pods
+
+To attach additional network interfaces to a pod, you must create and apply configurations that define how the interfaces are attached.
+
+* You must configure any additional networks you want to use. Because of individual differences in networks, no default configuration is provided.
+* You must apply YAML manifest to specify each interface by using a `NetworkAttachmentDefinition` custom resource (CR). A configuration inside each of these CRs defines how that interface is created.
+* CRI-O must be configured to use Multus. A default configuration is included in the `microshift-multus` RPM.
+** If the Multus CNI is installed on an existing {microshift-short} instance, the host must be restarted.
+** If the Multus CNI is installed alongside {microshift-short}, you can add CRs and pods and then start the {microshift-short} service. Restarting the host in this scenario is not needed.
 
-To attach additional network interfaces to a pod, you must create configurations that define how the interfaces are attached. You specify each interface by using a `NetworkAttachmentDefinition` custom resource (CR). A configuration inside each of these CRs defines how that interface is created.
+[id="microshift-config-examples-additional-networks_{context}"]
+== Configurations for additional network types
+The specific configuration fields for additional networks is described in the following sections.

modules/nw-multus-bridge-object.adoc

@@ -1,25 +1,34 @@
 // Module included in the following assemblies:
 //
 // * networking/multiple_networks/configuring-additional-network.adoc
+// * microshift_networking/microshift_multiple_networks/microshift_cni_multus.adoc
+
 :_mod-docs-content-type: REFERENCE
 [id="nw-multus-bridge-object_{context}"]
 = Configuration for a bridge additional network
 
-The following object describes the configuration parameters for the bridge CNI
-plugin:
+The following object describes the configuration parameters for the Bridge CNI plugin:
 
 .Bridge CNI plugin JSON configuration object
 [cols=".^2,.^2,.^6",options="header"]
 |====
 |Field|Type|Description
 
+ifndef::microshift[]
 |`cniVersion`
 |`string`
 |The CNI specification version. The `0.3.1` value is required.
 
 |`name`
 |`string`
 |The value for the `name` parameter you provided previously for the CNO configuration.
+endif::microshift[]
+
+ifdef::microshift[]
+|`cniVersion`
+|`string`
+|The CNI specification version. The `0.4.0` value is required.
+endif::microshift[]
 
 |`type`
 |`string`
@@ -57,6 +66,7 @@ plugin:
 |`boolean`
 |Optional: Set to `true` to enable promiscuous mode on the bridge. The default value is `false`.
 
+ifndef::microshift[]
 |`vlan`
 |`string`
 |Optional: Specify a virtual LAN (VLAN) tag as an integer value. By default, no VLAN tag is assigned.
@@ -68,6 +78,7 @@ plugin:
 |`vlanTrunk`
 |`list`
 |Optional: Assign a VLAN trunk tag. The default value is `none`.
+endif::microshift[]
 
 |`mtu`
 |`string`
@@ -82,25 +93,24 @@ plugin:
 |Optional: Enables mac spoof check, limiting the traffic originating from the container to the mac address of the interface. The default value is `false`.
 |====
 
+ifndef::microshift[]
 [NOTE]
 ====
 The VLAN parameter configures the VLAN tag on the host end of the `veth` and also enables the `vlan_filtering` feature on the bridge interface.
 ====
 
 [NOTE]
 ====
-To configure uplink for a L2 network you need to allow the vlan on the uplink interface by using the following command:
+To configure an uplink for an L2 network, you must allow the VLAN on the uplink interface by using the following command:
 
 [source,terminal]
 ----
 $  bridge vlan add vid VLAN_ID dev DEV
 ----
-
 ====
 
-
 [id="nw-multus-bridge-config-example_{context}"]
-== bridge configuration example
+== Bridge CNI plugin configuration example
 
 The following example configures an additional network named `bridge-net`:
 
@@ -117,3 +127,40 @@ The following example configures an additional network named `bridge-net`:
     }
 }
 ----
+endif::microshift[]
+
+ifdef::microshift[]
+[id="microshift-nw-multus-bridge-config-example_{context}"]
+== Bridge CNI plugin configuration example
+
+The following example configures an additional network named `bridge-conf` for use with the {microshift-short} Multus CNI:
+
+[source,json]
+----
+apiVersion: "k8s.cni.cncf.io/v1"
+kind: NetworkAttachmentDefinition
+metadata:
+  name: bridge-conf
+spec:
+  config: '{
+      "cniVersion": "0.4.0",
+      "type": "bridge",
+      "bridge": "test-bridge",
+      "mode": "bridge",
+      "ipam": {
+        "type": "host-local",
+        "ranges": [
+          [
+            {
+              "subnet": "10.10.0.0/16",
+              "rangeStart": "10.10.1.20",
+              "rangeEnd": "10.10.3.50",
+              "gateway": "10.10.0.254"
+            }
+          ]
+        ],
+        "dataDir": "/var/lib/cni/test-bridge"
+      }
+    }'
+----
+endif::microshift[]

modules/nw-multus-ipvlan-object.adoc

@@ -1,13 +1,14 @@
 // Module included in the following assemblies:
 //
 // * networking/multiple_networks/configuring-additional-network.adoc
+// * microshift_networking/microshift_multiple_networks/microshift_cni_multus.adoc
 
 //37.1. IPVLAN overview
 // https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/html/configuring_and_managing_networking/getting-started-with-ipvlan_configuring-and-managing-networking#ipvlan-overview_getting-started-with-ipvlan
 :_mod-docs-content-type: REFERENCE
 
 [id="nw-multus-ipvlan-object_{context}"]
-= Configuration for an IPVLAN additional network
+= Configuration for an ipvlan additional network
 
 The following object describes the configuration parameters for the IPVLAN CNI plugin:
 
@@ -50,15 +51,15 @@ The following object describes the configuration parameters for the IPVLAN CNI p
 
 |====
 
-[NOTE]
+[IMPORTANT]
 ====
-* The `ipvlan` object does not allow virtual interfaces to communicate with the `master` interface. Therefore the container will not be able to reach the host by using the `ipvlan` interface. Be sure that the container joins a network that provides connectivity to the host, such as a network supporting the Precision Time Protocol (`PTP`).
+* The `ipvlan` object does not allow virtual interfaces to communicate with the `master` interface. Therefore the container is not able to reach the host by using the `ipvlan` interface. Be sure that the container joins a network that provides connectivity to the host, such as a network supporting the Precision Time Protocol (`PTP`).
 * A single `master` interface cannot simultaneously be configured to use both `macvlan` and `ipvlan`.
 * For IP allocation schemes that cannot be interface agnostic, the `ipvlan` plugin can be chained with an earlier plugin that handles this logic. If the `master` is omitted, then the previous result must contain a single interface name for the `ipvlan` plugin to enslave. If `ipam` is omitted, then the previous result is used to configure the `ipvlan` interface.
 ====
 
 [id="nw-multus-ipvlan-config-example_{context}"]
-== ipvlan configuration example
+== IPVLAN CNI plugin configuration example
 
 The following example configures an additional network named `ipvlan-net`:
 

modules/nw-multus-macvlan-object.adoc

@@ -1,11 +1,13 @@
 // Module included in the following assemblies:
 //
 // * networking/multiple_networks/configuring-additional-network.adoc
+// * microshift_networking/microshift_multiple_networks/microshift_cni_multus.adoc
+
 :_mod-docs-content-type: REFERENCE
 [id="nw-multus-macvlan-object_{context}"]
-= Configuration for a MACVLAN additional network
+= Configuration for a macvlan additional network
 
-The following object describes the configuration parameters for the macvlan CNI plugin:
+The following object describes the configuration parameters for the MACVLAN CNI plugin:
 
 .MACVLAN CNI plugin JSON configuration object
 [cols=".^2,.^2,.^6",options="header"]
@@ -52,7 +54,7 @@ If you specify the `master` key for the plugin configuration, use a different ph
 ====
 
 [id="nw-multus-macvlan-config-example_{context}"]
-== macvlan configuration example
+== MACVLAN CNI plugin configuration example
 
 The following example configures an additional network named `macvlan-net`: