OSDOCS-14023: Clarified secondary/additional networks

Author: dfitzmau

modules/cnf-assigning-a-secondary-network-to-a-vrf.adoc

@@ -4,16 +4,16 @@
 
 :_mod-docs-content-type: PROCEDURE
 [id="cnf-creating-an-additional-network-attachment-with-the-cni-vrf-plug-in_{context}"]
-= Creating an additional network attachment with the CNI VRF plugin
+= Creating a secondary network attachment with the CNI VRF plugin
 
-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.
+The Cluster Network Operator (CNO) manages secondary network definitions. When you specify a secondary network to create, the CNO creates the `NetworkAttachmentDefinition` custom resource (CR) automatically.
 
 [NOTE]
 ====
-Do not edit the `NetworkAttachmentDefinition` CRs that the Cluster Network Operator manages. Doing so might disrupt network traffic on your additional network.
+Do not edit the `NetworkAttachmentDefinition` CRs that the Cluster Network Operator manages. Doing so might disrupt network traffic on your secondary network.
 ====
 
-To create an additional network attachment with the CNI VRF plugin, perform the following procedure.
+To create a secondary network attachment with the CNI VRF plugin, perform the following procedure.
 
 .Prerequisites
 
@@ -22,7 +22,7 @@ To create an additional network attachment with the CNI VRF plugin, perform the
 
 .Procedure
 
-. Create the `Network` custom resource (CR) for the additional network attachment and insert the `rawCNIConfig` configuration for the additional network, as in the following example CR. Save the YAML as the file `additional-network-attachment.yaml`.
+. Create the `Network` custom resource (CR) for the additional network attachment and insert the `rawCNIConfig` configuration for the secondary network, as in the following example CR. Save the YAML as the file `additional-network-attachment.yaml`.
 +
 [source,yaml]
 ----
@@ -96,7 +96,7 @@ There might be a delay before the CNO creates the CR.
 
 .Verification
 
-. Create a pod and assign it to the additional network with the VRF instance:
+. Create a pod and assign it to the secondary network with the VRF instance:
 
 .. Create a YAML file that defines the `Pod` resource:
 +
@@ -119,7 +119,7 @@ spec:
    command: ["/bin/bash", "-c", "sleep 9000000"]
    image: centos:8
 ----
-<1> Specify the name of the additional network with the VRF instance.
+<1> Specify the name of the secondary network with the VRF instance.
 
 .. Create the `Pod` resource by running the following command:
 +
@@ -134,7 +134,7 @@ $ oc create -f pod-additional-net.yaml
 pod/test-pod created
 ----
 
-. Verify that the pod network attachment is connected to the VRF additional network. Start a remote session with the pod and run the following command:
+. Verify that the pod network attachment is connected to the VRF secondary network. Start a remote session with the pod and run the following command:
 +
 [source,terminal]
 ----
@@ -148,7 +148,7 @@ Name              Table
 -----------------------
 vrf-1             1001
 ----
-. Confirm that the VRF interface is the controller for the additional interface:
+. Confirm that the VRF interface is the controller for the secondary interface:
 +
 [source,terminal]
 ----

modules/configuration-ovnk-multi-network-policy.adoc

@@ -26,7 +26,7 @@ a|
 
 |====
 
-For example, the following multi-network policy is valid only if the `subnets` field is defined in the additional network CNI configuration for the additional network named `blue2`:
+For example, the following multi-network policy is valid only if the `subnets` field is defined in the secondary network CNI configuration for the secondary network named `blue2`:
 
 .Example multi-network policy that uses a pod selector
 [source,yaml]
@@ -44,7 +44,7 @@ spec:
     - podSelector: {}
 ----
 
-The following example uses the `ipBlock` network policy selector, which is always valid for an OVN-Kubernetes additional network:
+The following example uses the `ipBlock` network policy selector, which is always valid for an OVN-Kubernetes secondary network:
 
 .Example multi-network policy that uses an IP block selector
 [source,yaml]

modules/configuration-ovnk-network-plugin-json-object.adoc

@@ -63,6 +63,6 @@ A comma-separated list of CIDRs and IP addresses. IP addresses are removed from
 |`vlanID`
 |`integer`
 |
-If topology is set to `localnet`, the specified VLAN tag is assigned to traffic from this additional network. The default is to not assign a VLAN tag.
+If topology is set to `localnet`, the specified VLAN tag is assigned to traffic from this secondary network. The default is to not assign a VLAN tag.
 
 |====

modules/configuring-localnet-switched-topology.adoc

@@ -14,14 +14,14 @@ The switched `localnet` topology interconnects the workloads created as Network
 // end::localnet-intro[]
 
 // tag::localnet-content[]
-You must map an additional network to the OVN bridge to use it as an OVN-Kubernetes additional network. Bridge mappings allow network traffic to reach the physical network. A bridge mapping associates a physical network name, also known as an interface label, to a bridge created with Open vSwitch (OVS).
+You must map a secondary network to the OVN bridge to use it as an OVN-Kubernetes secondary network. Bridge mappings allow network traffic to reach the physical network. A bridge mapping associates a physical network name, also known as an interface label, to a bridge created with Open vSwitch (OVS).
 
-You can create an `NodeNetworkConfigurationPolicy` (NNCP) object, part of the `nmstate.io/v1` API group, to declaratively create the mapping. This API is provided by the NMState Operator. By using this API you can apply the bridge mapping to nodes that match your specified `nodeSelector` expression, such as `node-role.kubernetes.io/worker: ''`. With this declarative approach, the NMState Operator applies additional network configuration to all nodes specified by the node selector automatically and transparently.
+You can create an `NodeNetworkConfigurationPolicy` (NNCP) object, part of the `nmstate.io/v1` API group, to declaratively create the mapping. This API is provided by the NMState Operator. By using this API you can apply the bridge mapping to nodes that match your specified `nodeSelector` expression, such as `node-role.kubernetes.io/worker: ''`. With this declarative approach, the NMState Operator applies secondary network configuration to all nodes specified by the node selector automatically and transparently.
 
-When attaching an additional network, you can either use the existing `br-ex` bridge or create a new bridge. Which approach to use depends on your specific network infrastructure. Consider the following approaches:
+When attaching a secondary network, you can either use the existing `br-ex` bridge or create a new bridge. Which approach to use depends on your specific network infrastructure. Consider the following approaches:
 
 - If your nodes include only a single network interface, you must use the existing bridge. This network interface is owned and managed by OVN-Kubernetes and you must not remove it from the `br-ex` bridge or alter the interface configuration. If you remove or alter the network interface, your cluster network will stop working correctly.
-- If your nodes include several network interfaces, you can attach a different network interface to a new bridge, and use that for your additional network. This approach provides for traffic isolation from your primary cluster network.
+- If your nodes include several network interfaces, you can attach a different network interface to a new bridge, and use that for your secondary network. This approach provides for traffic isolation from your primary cluster network.
 
 The `localnet1` network is mapped to the `br-ex` bridge in the following example:
 
@@ -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` CRD that defines the OVN-Kubernetes additional network.
+<3> The name for the secondary network from which traffic is forwarded to the OVS bridge. This secondary network must match the name of the `spec.config.name` field of the `NetworkAttachmentDefinition` CRD that defines the OVN-Kubernetes secondary 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`.
 +
@@ -66,7 +66,7 @@ The following JSON example configures a localnet secondary network that is named
 }
 ----
 
-In the following example, the `localnet2` network interface is attached to the `ovs-br1` bridge. Through this attachment, the network interface is available to the OVN-Kubernetes network plugin as an additional network.
+In the following example, the `localnet2` network interface is attached to the `ovs-br1` bridge. Through this attachment, the network interface is available to the OVN-Kubernetes network plugin as a secondary network.
 
 .Example mapping for nodes with multiple interfaces
 [source,yaml]
@@ -104,7 +104,7 @@ spec:
 <3> Specifies a new OVS bridge that operates separately from the default bridge used by OVN-Kubernetes for cluster traffic.
 <4> Specifies whether to enable multicast snooping. When enabled, multicast snooping prevents network devices from flooding multicast traffic to all network members. By default, an OVS bridge does not enable multicast snooping. The default value is `false`.
 <5> Specifies the network device on the host system to associate with the new OVS bridge.
-<6> Specifies the name of the additional network that forwards traffic to the OVS bridge. This name must match the value of the `spec.config.name` field in the `NetworkAttachmentDefinition` CRD that defines the OVN-Kubernetes additional network.
+<6> Specifies the name of the secondary network that forwards traffic to the OVS bridge. This name must match the value of the `spec.config.name` field in the `NetworkAttachmentDefinition` CRD that defines the OVN-Kubernetes secondary network.
 <7> Specifies the name of the OVS bridge on the node. The value is required only when `state: present` is set.
 <8> Specifies the state of the mapping. Valid values are `present` to add the bridge or `absent` to remove the bridge. The default value is `present`.
 +

modules/configuring-ovnk-additional-networks.adoc

@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="configuration-ovnk-additional-networks_{context}"]
-= Configuration for an OVN-Kubernetes additional network
+= Configuration for an OVN-Kubernetes secondary 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 definition (CRD).
 
@@ -13,10 +13,7 @@ The {openshift-networking} OVN-Kubernetes network plugin allows the configuratio
 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.
-
-- A layer 2 topology supports east-west cluster traffic, but does not allow access to the underlying physical network.
-- A localnet topology allows connections to the physical network, but requires additional configuration of the underlying Open vSwitch (OVS) bridge on cluster nodes.
+You can configure an OVN-Kubernetes secondary network in layer 2, layer 3, or localnet topologies. For more information about features supported on these topologies, see "UserDefinedNetwork and NetworkAttachmentDefinition support matrix". 
 
 The following sections provide example configurations for each of the topologies that OVN-Kubernetes currently allows for secondary networks.
 
@@ -26,9 +23,9 @@ Networks names must be unique. For example, creating multiple `NetworkAttachment
 ====
 
 [id="configuration-additional-network-types-supported-platforms_{context}"]
-== Supported platforms for OVN-Kubernetes additional network
+== Supported platforms for OVN-Kubernetes secondary network
 
-You can use an OVN-Kubernetes additional network with the following supported platforms:
+You can use an OVN-Kubernetes secondary network with the following supported platforms:
 
 - Bare metal
 - {ibm-power-name}

modules/configuring-pods-secondary-network.adoc

@@ -4,7 +4,7 @@
 
 :_mod-docs-content-type: REFERENCE
 [id="configuring-pods-secondary-network_{context}"]
-= Configuring pods for additional networks
+= Configuring pods for secondary networks
 
 You must specify the secondary network attachments through the `k8s.v1.cni.cncf.io/networks` annotation.
 

modules/configuring-pods-static-ip.adoc

@@ -10,7 +10,7 @@ The following example provisions a pod with a static IP address.
 
 [NOTE]
 ====
-* You can specify the IP address for the secondary network attachment of a pod only when the additional network attachment, a namespaced-scoped object, uses a layer 2 or localnet topology.
+* You can specify the IP address for the secondary network attachment of a pod only when the secondary network attachment, a namespaced-scoped object, uses a layer 2 or localnet topology.
 * Specifying a static IP address for the pod is only possible when the attachment configuration does not feature subnets.
 ====
 

modules/microshift-multus-intro.adoc

@@ -4,31 +4,31 @@
 
 :_mod-docs-content-type: CONCEPT
 [id="microshift-multus-intro_{context}"]
-= Additional networks in {microshift-short}
+= Secondary 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 {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="microshift-supported-additional-networks_{context}"]
-== Supported additional networks for network isolation
-The following additional networks are supported in {microshift-short} {product-version}:
+== Supported secondary networks for network isolation
+The following secondary 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.
+** This is similar to a MACVLAN-based secondary network.
+** Each pod shares the same MAC address as the parent physical network interface, unlike a MACVLAN-based secondary 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.
+* 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 secondary network is provided with a unique MAC address.
 
 [NOTE]
 ====
-Setting network policies for additional networks is not supported.
+Setting network policies for secondary networks is not supported.
 ====
 
 [id="microshift-additional-network-use-cases_{context}"]
-== Use case: Additional networks for network isolation
+== Use case: Secondary networks for network isolation
 
-You can use an additional network in situations where network isolation is needed, including control plane and data plane separation. 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.
+You can use an secondary network in situations where network isolation is needed, including control plane and data plane separation. For example, you can configure an secondary 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:
 
@@ -41,25 +41,25 @@ The Multus CNI plugin is deployed when the {microshift-short} service starts up.
 ====
 
 [id="microshift-additional-network-how-implemented_{context}"]
-== How additional networks are implemented
+== How secondary 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 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`.
+* If you add secondary 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
+== How to attached secondary networks to pods
 
-To attach additional network interfaces to a pod, you must create and apply configurations that define how the interfaces are attached.
+To attach secondary 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 configure any secondary 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.
 
 [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.
+== Configurations for secondary network types
+The specific configuration fields for secondary networks is described in the following sections.

modules/nw-multi-network-policy-differences.adoc

@@ -18,7 +18,7 @@ kind: MultiNetworkPolicy
 
 * You must use the `multi-networkpolicy` resource name when using the CLI to interact with multi-network policies. For example, you can view a multi-network policy object with the `oc get multi-networkpolicy <name>` command where `<name>` is the name of a multi-network policy.
 
-* You must specify an annotation with the name of the network attachment definition that defines the additional network:
+* You must specify an annotation with the name of the network attachment definition that defines the secondary network:
 +
 [source,yaml]
 ----