OCPBUGS-44255: Added important note to the Configuration for an VLAN additional network section

dfitzmau · dfitzmau · commit d7dc02358dd4 · 2024-12-16T11:24:49.000Z
diff --git a/modules/configuration-ovnk-network-plugin-json-object.adoc b/modules/configuration-ovnk-network-plugin-json-object.adoc
@@ -1,3 +1,7 @@
+// Module included in the following assemblies:
+//
+// * networking/multiple_networks/configuring-additional-network.adoc
+
 :_mod-docs-content-type: REFERENCE
 [id="configuration-ovnk-network-plugin-json-object_{context}"]
 = OVN-Kubernetes network plugin JSON configuration table
@@ -18,9 +22,9 @@ The CNI specification version. The required value is `0.3.1`.
 |`string`
 |
 The name of the network. These networks are not namespaced. For example, you can have a network named
-`l2-network` referenced from two different `NetworkAttachmentDefinitions` that exist on two different
-namespaces. This ensures that pods making use of the `NetworkAttachmentDefinition` on their own different
-namespaces can communicate over the same secondary network. However, those two different `NetworkAttachmentDefinitions` must also share the same network specific parameters such as `topology`, `subnets`, `mtu`, and `excludeSubnets`.
+`l2-network` referenced from two different `NetworkAttachmentDefinition` CRDs that exist on two different
+namespaces. This ensures that pods making use of the `NetworkAttachmentDefinition` CRD on their own different
+namespaces can communicate over the same secondary network. However, those two different `NetworkAttachmentDefinition` CRDs must also share the same network specific parameters such as `topology`, `subnets`, `mtu`, and `excludeSubnets`.
 
 |`type`
 |`string`
@@ -49,8 +53,8 @@ The maximum transmission unit (MTU). The default value, `1300`, is automatically
 |`netAttachDefName`
 |`string`
 |
-The metadata `namespace` and `name` of the network attachment definition object where this
-configuration is included. For example, if this configuration is defined in a `NetworkAttachmentDefinition` in namespace `ns1` named `l2-network`, this should be set to `ns1/l2-network`.
+The metadata `namespace` and `name` of the network attachment definition CRD where this
+configuration is included. For example, if this configuration is defined in a `NetworkAttachmentDefinition` CRD in namespace `ns1` named `l2-network`, this should be set to `ns1/l2-network`.
 
 |`excludeSubnets`
 |`string`
diff --git a/modules/configuring-localnet-switched-topology.adoc b/modules/configuring-localnet-switched-topology.adoc
@@ -10,7 +10,7 @@
 // is split with tags. The tag includes don't pull in the module header above.
 
 // tag::localnet-intro[]
-The switched `localnet` topology interconnects the workloads created as Network Attachment Definitions (NAD) through a cluster-wide logical switch to a physical network.
+The switched `localnet` topology interconnects the workloads created as Network Attachment Definitions (NADs) through a cluster-wide logical switch to a physical network.
 // end::localnet-intro[]
 
 // tag::localnet-content[]
@@ -44,7 +44,7 @@ spec:
 ----
 <1> The name for the configuration object.
 <2> A node selector that specifies the nodes to apply the node network configuration policy to.
-<3> The name for the additional network from which traffic is forwarded to the OVS bridge. This additional network must match the name of the `spec.config.name` field of the `NetworkAttachmentDefinition` object that defines the OVN-Kubernetes additional network.
+<3> The name for the additional network from which traffic is forwarded to the OVS bridge. This additional network must match the name of the `spec.config.name` field of the `NetworkAttachmentDefinition` CRD that defines the OVN-Kubernetes additional network.
 <4> The name of the OVS bridge on the node. This value is required only if you specify `state: present`.
 <5> The state for the mapping. Must be either `present` to add the bridge or `absent` to remove the bridge. The default value is `present`.
 
@@ -84,7 +84,7 @@ spec:
 <2> A node selector that specifies the nodes to apply the node network configuration policy to.
 <3> A new OVS bridge, separate from the default bridge used by OVN-Kubernetes for all cluster traffic.
 <4> A network device on the host system to associate with this new OVS bridge.
-<5> The name for the additional network from which traffic is forwarded to the OVS bridge. This additional network must match the name of the `spec.config.name` field of the `NetworkAttachmentDefinition` object that defines the OVN-Kubernetes additional network.
+<5> The name for the additional network from which traffic is forwarded to the OVS bridge. This additional network must match the name of the `spec.config.name` field of the `NetworkAttachmentDefinition` CRD that defines the OVN-Kubernetes additional network.
 <6> The name of the OVS bridge on the node. This value is required only if you specify `state: present`.
 <7> The state for the mapping. Must be either `present` to add the bridge or `absent` to remove the bridge. The default value is `present`.
 
diff --git a/modules/configuring-ovnk-additional-networks.adoc b/modules/configuring-ovnk-additional-networks.adoc
@@ -6,11 +6,11 @@
 [id="configuration-ovnk-additional-networks_{context}"]
 = Configuration for an OVN-Kubernetes additional network
 
-The {openshift-networking} OVN-Kubernetes network plugin allows the configuration of secondary network interfaces for pods. To configure secondary network interfaces, you must define the configurations in the `NetworkAttachmentDefinition` custom resource (CR).
+The {openshift-networking} OVN-Kubernetes network plugin allows the configuration of secondary network interfaces for pods. To configure secondary network interfaces, you must define the configurations in the `NetworkAttachmentDefinition` custom resource definition (CRD).
 
 [NOTE]
 ====
-Pod and multi-network policy creation might remain in a pending state until the OVN-Kubernetes control plane agent in the nodes processes the associated `network-attachment-definition` CR.
+Pod and multi-network policy creation might remain in a pending state until the OVN-Kubernetes control plane agent in the nodes processes the associated `network-attachment-definition` CRD.
 ====
 
 You can configure an OVN-Kubernetes additional network in either _layer 2_ or _localnet_ topologies.
@@ -22,7 +22,7 @@ The following sections provide example configurations for each of the topologies
 
 [NOTE]
 ====
-Networks names must be unique. For example, creating multiple `NetworkAttachmentDefinition` CRs with different configurations that reference the same network is unsupported.
+Networks names must be unique. For example, creating multiple `NetworkAttachmentDefinition` CRDs with different configurations that reference the same network is unsupported.
 ====
 
 [id="configuration-additional-network-types-supported-platforms_{context}"]
diff --git a/modules/configuring-pods-static-ip.adoc b/modules/configuring-pods-static-ip.adoc
@@ -40,7 +40,7 @@ spec:
     imagePullPolicy: IfNotPresent
     name: agnhost-container
 ----
-<1> The name of the network. This value must be unique across all `NetworkAttachmentDefinitions`.
+<1> The name of the network. This value must be unique across all `NetworkAttachmentDefinition` CRDs.
 <2> The MAC address to be assigned for the interface.
 <3> The name of the network interface to be created for the pod.
 <4> The IP addresses to be assigned to the network interface.
diff --git a/modules/nw-about-configuring-master-interface-container.adoc b/modules/nw-about-configuring-master-interface-container.adoc
@@ -3,12 +3,10 @@
 // * networking/multiple_networks/configuring-additional-network.adoc
 
 :_mod-docs-content-type: CONCEPT
-
 [id="nw-about-configuring-master-interface-container_{context}"]
 = About configuring the master interface in the container network namespace
 
-In {product-title} 4.14 and later, the ability to allow users to create a MAC-VLAN, IP-VLAN, and VLAN subinterface based on a master interface in a container namespace is now generally available.
-
-This feature allows you to create the master interfaces as part of the pod network configuration in a separate network attachment definition. You can then base the VLAN, MACVLAN, or IPVLAN on this interface without requiring the knowledge of the network configuration of the node.
+You can create a MAC-VLAN, an IP-VLAN, or a VLAN subinterface that is based on a `master` interface that exists in a container namespace. You can also create a `master` interface as part of the pod network configuration in a separate network attachment definition CRD.
 
-To ensure the use of a container namespace master interface, specify the `linkInContainer` and set the value to `true` in the VLAN, MACVLAN, or IPVLAN plugin configuration depending on the particular type of additional network.
+To use a container namespace `master` interface, you must specify `true` for the 
+`linkInContainer` parameter that exists in the subinterface configuration of the `NetworkAttachmentDefinition` CRD.
diff --git a/modules/nw-multus-configure-dualstack-ip-address.adoc b/modules/nw-multus-configure-dualstack-ip-address.adoc
@@ -3,7 +3,6 @@
 // * networking/multiple_networks/configuring-additional-network.adoc
 
 :_mod-docs-content-type: PROCEDURE
-
 [id="nw-multus-configure-dualstack-ip-address_{context}"]
 = Creating a configuration for assignment of dual-stack IP addresses dynamically
 
diff --git a/modules/nw-multus-configuring-whereabouts-ip-reconciler-schedule.adoc b/modules/nw-multus-configuring-whereabouts-ip-reconciler-schedule.adoc
@@ -3,7 +3,6 @@
 // * networking/multiple_networks/configuring-additional-network.adoc
 
 :_mod-docs-content-type: PROCEDURE
-
 [id="nw-multus-configuring-whereabouts-ip-reconciler-schedule_{context}"]
 = Configuring the Whereabouts IP reconciler schedule
 
diff --git a/modules/nw-multus-create-master-interface-bridge-cni.adoc b/modules/nw-multus-create-master-interface-bridge-cni.adoc
@@ -6,22 +6,22 @@
 [id="nw-multus-create-master-interface-bridge-cni_{context}"]
 = Creating a subinterface based on a bridge master interface in a container namespace
 
-Creating a subinterface can be applied to other types of interfaces. Follow this procedure to create a subinterface based on a bridge master interface in a container namespace.
+You can create a subinterface based on a bridge `master` interface that exists in a container namespace. Creating a subinterface can be applied to other types of interfaces. 
 
 .Prerequisites
 * You have installed the OpenShift CLI (`oc`).
 * You are logged in to the {product-title} cluster as a user with `cluster-admin` privileges.
 
 .Procedure
 
-. Create a dedicated container namespace where you want to deploy your pod by running the following command:
+. Create a dedicated container namespace where you want to deploy your pod by entering the following command:
 +
 [source,terminal]
 ----
 $ oc new-project test-namespace
 ----
 
-. Using the following YAML example, create a bridge `NetworkAttachmentDefinition` custom resource (CR) file named `bridge-nad.yaml`:
+. Using the following YAML example, create a bridge `NetworkAttachmentDefinition` custom resource definition (CRD) file named `bridge-nad.yaml`:
 +
 [source,yaml]
 ----
@@ -46,14 +46,14 @@ spec:
   }'
 ----
 
-. Run the following command to apply the `NetworkAttachmentDefinition` CR to your {product-title} cluster:
+. Run the following command to apply the `NetworkAttachmentDefinition` CRD to your {product-title} cluster:
 +
 [source,terminal]
 ----
 $ oc apply -f bridge-nad.yaml
 ----
 
-.  Verify that the `NetworkAttachmentDefinition` CR has been created successfully by running the following command:
+.  Verify that you successfully created a `NetworkAttachmentDefinition` CRD by entering the following command:
 +
 [source,terminal]
 ----
@@ -90,7 +90,7 @@ spec:
 ----
 +
 <1> Specifies the ethernet interface to associate with the network attachment. This is subsequently configured in the pod networks annotation.
-<2> Specifies that the master interface is in the container network namespace.
+<2> Specifies that the `master` interface is in the container network namespace.
 
 . Apply the YAML file by running the following command:
 +
@@ -99,7 +99,7 @@ spec:
 $ oc apply -f ipvlan-additional-network-configuration.yaml
 ----
 
-. Verify that the `NetworkAttachmentDefinition` CR has been created successfully by running the following command:
+. Verify that the `NetworkAttachmentDefinition` CRD has been created successfully by running the following command:
 +
 [source,terminal]
 ----
@@ -149,7 +149,7 @@ spec:
         drop: [ALL]
 ----
 +
-<1> Specifies the name to be used as the master for the IPVLAN interface.
+<1> Specifies the name to be used as the `master` for the IPVLAN interface.
 
 . Apply the YAML file by running the following command:
 +
diff --git a/modules/nw-multus-create-multiple-vlans-sriov.adoc b/modules/nw-multus-create-multiple-vlans-sriov.adoc
@@ -126,7 +126,7 @@ spec:
     }
 ----
 +
-<1> The VLAN configuration needs to specify the master name. This can be configured in the pod networks annotation.
+<1> The VLAN configuration needs to specify the `master` name. This can be configured in the pod networks annotation.
 <2> The `linkInContainer` parameter must be specified.
 
 .. Apply the YAML file by running the following command:
@@ -194,7 +194,7 @@ spec:
         type: "RuntimeDefault"
 ----
 +
-<1> The name to be used as the master for the VLAN interface.
+<1> The name to be used as the `master` for the VLAN interface.
 
 .. Apply the YAML file by running the following command:
 +
diff --git a/modules/nw-multus-create-network-apply.adoc b/modules/nw-multus-create-network-apply.adoc
@@ -1,5 +1,6 @@
 // Module included in the following assemblies:
 //
+// * networking/multiple_networks/configuring-additional-network.adoc
 
 :_mod-docs-content-type: PROCEDURE
 [id="nw-multus-create-network-apply_{context}"]
diff --git a/modules/nw-multus-create-network.adoc b/modules/nw-multus-create-network.adoc
@@ -6,15 +6,11 @@
 [id="nw-multus-create-network_{context}"]
 = Creating an additional network attachment with the Cluster Network Operator
 
-The Cluster Network Operator (CNO) manages additional network definitions. When
-you specify an additional network to create, the CNO creates the
-`NetworkAttachmentDefinition` object automatically.
+The Cluster Network Operator (CNO) manages additional network definitions. When you specify an additional network to create, the CNO creates the `NetworkAttachmentDefinition` CRD automatically.
 
 [IMPORTANT]
 ====
-Do not edit the `NetworkAttachmentDefinition` objects that the Cluster Network
-Operator manages. Doing so might disrupt network traffic on your additional
-network.
+Do not edit the `NetworkAttachmentDefinition` CRDs that the Cluster Network Operator manages. Doing so might disrupt network traffic on your additional network.
 ====
 
 .Prerequisites
@@ -75,7 +71,7 @@ spec:
 
 .Verification
 
-* Confirm that the CNO created the `NetworkAttachmentDefinition` object by running the following command. There might be a delay before the CNO creates the object.
+* Confirm that the CNO created the `NetworkAttachmentDefinition` CRD by running the following command. There might be a delay before the CNO creates the CRD.
 +
 [source,terminal]
 ----
diff --git a/modules/nw-multus-creating-whereabouts-reconciler-daemon-set.adoc b/modules/nw-multus-creating-whereabouts-reconciler-daemon-set.adoc
@@ -3,15 +3,14 @@
 // * networking/multiple_networks/configuring-additional-network.adoc
 
 :_mod-docs-content-type: PROCEDURE
-
 [id="nw-multus-creating-whereabouts-reconciler-daemon-set_{context}"]
 = Creating a whereabouts-reconciler daemon set
 
 The Whereabouts reconciler is responsible for managing dynamic IP address assignments for the pods within a cluster by using the Whereabouts IP Address Management (IPAM) solution. It ensures that each pod gets a unique IP address from the specified IP address range. It also handles IP address releases when pods are deleted or scaled down.
 
 [NOTE]
 ====
-You can also use a `NetworkAttachmentDefinition` custom resource (CR) for dynamic IP address assignment.
+You can also use a `NetworkAttachmentDefinition` custom resource definition (CRD) for dynamic IP address assignment.
 ====
 
 The `whereabouts-reconciler` daemon set is automatically created when you configure an additional network through the Cluster Network Operator. It is not automatically created when you configure an additional network from a YAML manifest.
diff --git a/modules/nw-multus-ipam-object.adoc b/modules/nw-multus-ipam-object.adoc
@@ -194,7 +194,7 @@ spec:
 
 The Whereabouts CNI plugin allows the dynamic assignment of an IP address to an additional network without the use of a DHCP server. 
 
-The Whereabouts CNI plugin also supports overlapping IP address ranges and configuration of the same CIDR range multiple times within separate `NetworkAttachmentDefinitions`. This provides greater flexibility and management capabilities in multi-tenant environments.
+The Whereabouts CNI plugin also supports overlapping IP address ranges and configuration of the same CIDR range multiple times within separate `NetworkAttachmentDefinition` CRDs. This provides greater flexibility and management capabilities in multi-tenant environments.
 
 [id="dynamic-ip-address-assignment-objects_{context}"]
 === Dynamic IP address configuration objects
@@ -260,7 +260,7 @@ The following example shows a dynamic IP address assignment that uses overlappin
   }
 }
 ----
-<1> Optional. If set, must match the `network_name` of NetworkAttachmentDefinition 2.
+<1> Optional. If set, must match the `network_name` of `NetworkAttachmentDefinition 2`.
 
 .NetworkAttachmentDefinition 2
 [source,json]
@@ -273,7 +273,7 @@ The following example shows a dynamic IP address assignment that uses overlappin
   }
 }
 ----
-<1> Optional. If set, must match the `network_name` of NetworkAttachmentDefinition 1. 
+<1> Optional. If set, must match the `network_name` of `NetworkAttachmentDefinition 1`. 
 
 ifdef::sr-iov[]
 :!sr-iov:
diff --git a/modules/nw-multus-ipvlan-object.adoc b/modules/nw-multus-ipvlan-object.adoc
@@ -8,9 +8,9 @@
 :_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:
+The following object describes the configuration parameters for the IPVLAN, `ipvlan`, CNI plugin:
 
 .IPVLAN CNI plugin JSON configuration object
 [cols=".^2,.^2,.^6",options="header"]
@@ -47,7 +47,7 @@ The following object describes the configuration parameters for the IPVLAN CNI p
 
 |`linkInContainer`
 |`boolean`
-|Optional: Specifies whether the master interface is in the container network namespace or the main network namespace. Set the value to `true` to request the use of a container namespace master interface.
+|Optional: Specifies whether the `master` interface is in the container network namespace or the main network namespace. Set the value to `true` to request the use of a container namespace `master` interface.
 
 |====
 
diff --git a/modules/nw-multus-macvlan-object.adoc b/modules/nw-multus-macvlan-object.adoc
@@ -44,7 +44,7 @@ The following object describes the configuration parameters for the MACVLAN CNI
 
 |`linkInContainer`
 |`boolean`
-|Optional: Specifies whether the master interface is in the container network namespace or the main network namespace. Set the value to `true` to request the use of a container namespace master interface.
+|Optional: Specifies whether the `master` interface is in the container network namespace or the main network namespace. Set the value to `true` to request the use of a container namespace `master` interface.
 
 |====
 
diff --git a/modules/nw-multus-vlan-object.adoc b/modules/nw-multus-vlan-object.adoc
@@ -6,9 +6,9 @@
 //
 :_mod-docs-content-type: REFERENCE
 [id="nw-multus-vlan-object_{context}"]
-= Configuration for an VLAN additional network
+= Configuration for a VLAN additional network
 
-The following object describes the configuration parameters for the VLAN CNI plugin:
+The following object describes the configuration parameters for the VLAN, `vlan`, CNI plugin:
 
 .VLAN CNI plugin JSON configuration object
 [cols=".^2,.^2,.^6",options="header"]
@@ -33,7 +33,7 @@ The following object describes the configuration parameters for the VLAN CNI plu
 
 |`vlanId`
 |`integer`
-|Set the id of the vlan.
+|Set the ID of the `vlan`.
 
 |`ipam`
 |`object`
@@ -45,18 +45,23 @@ The following object describes the configuration parameters for the VLAN CNI plu
 
 |`dns`
 |`integer`
-|Optional: DNS information to return, for example, a priority-ordered list of DNS nameservers.
+|Optional: DNS information to return. For example, a priority-ordered list of DNS nameservers.
 
 |`linkInContainer`
 |`boolean`
-|Optional: Specifies whether the master interface is in the container network namespace or the main network namespace. Set the value to `true` to request the use of a container namespace master interface.
+|Optional: Specifies whether the `master` interface is in the container network namespace or the main network namespace. Set the value to `true` to request the use of a container namespace `master` interface.
 
 |====
 
+[IMPORTANT]
+====
+A `NetworkAttachmentDefinition` custom resource definition (CRD) with a `vlan` configuration can be used only on a single pod in a node because the CNI plugin cannot create multiple `vlan` subinterfaces with the same `vlanId` on the same `master` interface.
+====
+
 [id="nw-multus-vlan-config-example_{context}"]
-== vlan configuration example
+== VLAN configuration example
 
-The following example configures an additional network named `vlan-net`:
+The following example demonstrates a `vlan` configuration with an additional network that is named `vlan-net`:
 
 [source,json]
 ----
diff --git a/networking/multiple_networks/configuring-additional-network.adoc b/networking/multiple_networks/configuring-additional-network.adoc

Original file line number	Diff line number	Diff line change
`@@ -126,7 +126,7 @@ spec:`
`126`	`126`	`}`
`127`	`127`	`----`
`128`	`128`	`+`
`129`		`-<1> The VLAN configuration needs to specify the master name. This can be configured in the pod networks annotation.`
	`129`	+<1> The VLAN configuration needs to specify the `master` name. This can be configured in the pod networks annotation.
`130`	`130`	<2> The `linkInContainer` parameter must be specified.
`131`	`131`
`132`	`132`	`.. Apply the YAML file by running the following command:`
`@@ -194,7 +194,7 @@ spec:`
`194`	`194`	`type: "RuntimeDefault"`
`195`	`195`	`----`
`196`	`196`	`+`
`197`		`-<1> The name to be used as the master for the VLAN interface.`
	`197`	+<1> The name to be used as the `master` for the VLAN interface.
`198`	`198`
`199`	`199`	`.. Apply the YAML file by running the following command:`
`200`	`200`	`+`