CNV-13982: Add conceptual info on network bridges

Author: Bob Gaydos

_topic_maps/_topic_map.yml

@@ -3219,13 +3219,13 @@ Topics:
   - Name: Virtual machine networking
     Dir: vm_networking
     Topics:
-    - Name: Using the default pod network with OpenShift Virtualization
+    - Name: Configuring the virtual machine for the default pod network
       File: virt-using-the-default-pod-network-with-virt
       Distros: openshift-enterprise
-    - Name: Using the default pod network with OKD Virtualization
+    - Name: Configuring the virtual machine for the default pod network with OKD Virtualization
       File: virt-using-the-default-pod-network-with-virt
       Distros: openshift-origin
-    - Name: Attaching a virtual machine to multiple networks
+    - Name: Attaching a virtual machine to a Linux bridge network
       File: virt-attaching-vm-multiple-networks
     - Name: Configuring IP addresses for virtual machines
       File: virt-configuring-ip-for-vms
@@ -3311,7 +3311,7 @@ Topics:
     File: virt-live-migration-limits
   - Name: Migrating a virtual machine instance to another node
     File: virt-migrate-vmi
-  - Name: Migrating a virtual machine over a dedicated secondary network
+  - Name: Migrating a virtual machine over a dedicated additional network
     File: virt-migrating-vm-on-secondary-network
   - Name: Monitoring live migration of a virtual machine instance
     File: virt-monitor-vmi-migration

modules/virt-attaching-vm-secondary-network-cli.adoc

@@ -1,12 +1,12 @@
 // Module included in the following assemblies:
 //
-// * virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc
+// * virt/virtual_machines/vm_networking/virt-attaching-vm-external-network.adoc
 
 :_content-type: PROCEDURE
-[id="virt-attaching-vm-secondary-network-cli_{context}"]
-= Attaching a virtual machine to a secondary network in the CLI
+[id="virt-attaching-vm-additional-network-cli_{context}"]
+= Attaching a virtual machine to an additional network in the CLI
 
-Attach a virtual machine to a secondary network by adding a bridge interface and specifying a network attachment definition in the virtual machine configuration.
+Attach a virtual machine to an additional network by adding a bridge interface and specifying a network attachment definition in the virtual machine configuration.
 
 This procedure uses a YAML file to demonstrate editing the configuration and applying the updated file to the cluster. You can alternatively use the `oc edit <object> <name>` command to edit an existing virtual machine.
 
@@ -16,36 +16,37 @@ This procedure uses a YAML file to demonstrate editing the configuration and app
 
 .Procedure
 
-. Create or edit a virtual machine configuration that you want to connect to the bridge network. Add the bridge interface to the `spec.template.spec.domain.devices.interfaces` list and the network attachment definition to the `spec.template.spec.networks` list. The name of the `interfaces` entry must be the same as the `networks` entry. The following example adds a bridge interface called `bridge-net` that connects to the `a-bridge-network` network attachment definition:
+. Create or edit a configuration of a virtual machine that you want to connect to the bridge network.
+. Add the bridge interface to the `spec.template.spec.domain.devices.interfaces` list and the network attachment definition to the `spec.template.spec.networks` list. This example adds a bridge interface called `bridge-net` that connects to the `a-bridge-network` network attachment definition:
 +
 [source,yaml]
 ----
 apiVersion: kubevirt.io/v1
 kind: VirtualMachine
 metadata:
-    name: example-vm
+    name: <example-vm>
 spec:
   template:
     spec:
       domain:
         devices:
           interfaces:
             - masquerade: {}
-              name: default
+              name: <default>
             - bridge: {}
-              name: bridge-net <1>
+              name: <bridge-net> <1>
 ...
       networks:
-        - name: default
+        - name: <default>
           pod: {}
-        - name: bridge-net <2>
+        - name: <bridge-net> <2>
           multus:
             networkName: <network-namespace>/<a-bridge-network> <3>
 ...
 ----
 <1> The name of the bridge interface.
 <2> The name of the network. This value must match the `name` value of the corresponding `spec.template.spec.domain.devices.interfaces` entry.
-<3> The name of the network attachment definition, prefixed by the namespace where it exists. The namespace must be either the `default` namespace or the same namespace where the VM is to be created.
+<3> The name of the network attachment definition, prefixed by the namespace where it exists. The namespace must be either the `default` namespace or the same namespace where the VM is to be created. In this case, `multus` is used. Multus is a cloud network interface (CNI) plug-in that allows multiple CNIs to exist so that a pod or virtual machine can use the interfaces it needs.
 
 . Apply the configuration:
 +

modules/virt-creating-bridge-nad-cli.adoc

@@ -3,32 +3,33 @@
 // * virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc
 
 :_content-type: PROCEDURE
-[id="virt-creating-bridge-nad-cli_{context}"]
+[id="virt-creating-linux-bridge-nad-cli_{context}"]
 = Creating a Linux bridge network attachment definition in the CLI
 
-As a network administrator, you can configure a network attachment definition of type `cnv-bridge` to provide Layer-2 networking to pods and virtual machines.
+As a network administrator, you can configure a network attachment definition of type `cnv-bridge` to provide layer-2 networking to pods and virtual machines.
 
 .Prerequisites
 
 * The node must support nftables and the `nft` binary must be deployed to enable MAC spoof check.
 
 .Procedure
 
-. Create a network attachment definition manifest.
-The manifest must have the following contents, modified to match your configuration:
+. Create a network attachment definition in the same namespace as the virtual machine.
+
+. Add the virtual machine to the network attachment definition, as in the following example:
 +
 [source,yaml]
 ----
 apiVersion: "k8s.cni.cncf.io/v1"
 kind: NetworkAttachmentDefinition
 metadata:
-  name: <a-bridge-network> <1>
+  name: <bridge-network> <1>
   annotations:
     k8s.v1.cni.cncf.io/resourceName: bridge.network.kubevirt.io/<bridge-interface> <2>
 spec:
   config: '{
     "cniVersion": "0.3.1",
-    "name": "<a-bridge-network>", <3>
+    "name": "<bridge-network>", <3>
     "type": "cnv-bridge", <4>
     "bridge": "<bridge-interface>", <5>
     "macspoofchk": true, <6>
@@ -42,6 +43,11 @@ spec:
 <5> The name of the Linux bridge configured on the node.
 <6> Optional: Flag to enable MAC spoof check. When set to `true`, you cannot change the MAC address of the pod or guest interface. This attribute provides security against a MAC spoofing attack by allowing only a single MAC address to exit the pod.
 <7> Optional: The VLAN tag. No additional VLAN configuration is required on the node network configuration policy.
++
+[NOTE]
+====
+A Linux bridge network attachment definition is the most efficient method for connecting a virtual machine to a VLAN.
+====
 
 . Create the network attachment definition:
 +
@@ -53,10 +59,9 @@ $ oc create -f <network-attachment-definition.yaml> <1>
 
 .Verification
 
-* Verify that the network attachment definition is created by running either `oc get network-attachment-definition <name>` or `oc get net-attach-def <name>`. For example:
+* Verify that the network attachment definition was created by running the following command:
 +
 [source,terminal]
 ----
-$ oc get network-attachment-definition <a-bridge-network> <1>
+$ oc get network-attachment-definition <bridge-network>
 ----
-<1> Where `<a-bridge-network>` is the name specified in the network attachment definition config.

modules/virt-creating-bridge-nad-web.adoc

@@ -1,22 +1,32 @@
 // Module included in the following assemblies:
 //
 // * virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc
-
 //This file contains UI elements and/or package names that need to be updated.
 
 :_content-type: PROCEDURE
-[id="virt-creating-bridge-nad-web_{context}"]
+[id="virt-creating-linux-bridge-nad-web_{context}"]
 = Creating a Linux bridge network attachment definition in the web console
 
 Network administrators can create network attachment definitions to provide layer-2 networking to pods and virtual machines.
 
 .Procedure
 
 . In the web console, click *Networking* -> *Network Attachment Definitions*.
-. Click *Create Network Attachment Definition* .
+. Click *Create Network Attachment Definition*.
++
+[NOTE]
+====
+The network attachment definition must be in the same namespace as the pod or virtual machine.
+====
++
 . Enter a unique *Name* and optional *Description*.
 . Click the *Network Type* list and select *CNV Linux bridge*.
 . Enter the name of the bridge in the *Bridge Name* field.
 . Optional: If the resource has VLAN IDs configured, enter the ID numbers in the *VLAN Tag Number* field.
-. Optional: Select the *MAC Spoof Check* checkbox to enable MAC spoof filtering. This feature provides security against a MAC spoofing attack by allowing only a single MAC address to exit the pod.
+. Optional: Select *MAC Spoof Check* to enable MAC spoof filtering. This feature provides security against a MAC spoofing attack by allowing only a single MAC address to exit the pod.
 . Click *Create*.
++
+[NOTE]
+====
+A Linux bridge network attachment definition is the most efficient method for connecting a virtual machine to a VLAN.
+====

modules/virt-creating-linux-bridge-nncp.adoc

@@ -3,16 +3,16 @@
 // * virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc
 
 :_content-type: PROCEDURE
-[id="virt-configuring-linux-bridge-nncp_{context}"]
-= Creating a Linux bridge using a node network configuration policy
+[id="virt-creating-linux-bridge-nncp_{context}"]
 
-As a network administrator, you can create a Linux bridge interface on nodes in the cluster by applying a `NodeNetworkConfigurationPolicy` manifest to the cluster.
+= Creating a Linux bridge node network configuration policy
 
-.Procedure
+Use a `NodeNetworkConfigurationPolicy` manifest YAML file to create the Linux bridge.
 
-. Create the `NodeNetworkConfigurationPolicy` manifest. This YAML file is an example of a manifest for a Linux bridge interface.
-It includes samples values that you must replace with your own information.
+.Procedure
 
+* Create the `NodeNetworkConfigurationPolicy` manifest. This example includes sample values that you must replace with your own information.
++
 [source,yaml]
 ----
 apiVersion: nmstate.io/v1
@@ -40,6 +40,6 @@ spec:
 <3> Optional: Human-readable description of the interface.
 <4> The type of interface. This example creates a bridge.
 <5> The requested state for the interface after creation.
-<6> Disables ipv4 in this example.
-<7> Disables stp in this example.
-<8> The node NIC to which the bridge attaches.
+<6> Disables IPv4 in this example.
+<7> Disables STP in this example.
+<8> The node NIC to which the bridge is attached.

modules/virt-template-vm-config.adoc

@@ -3,7 +3,7 @@
 // * virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc
 
 [id="virt-template-vm-config_{context}"]
-= Template: Virtual machine configuration file
+= Virtual machine configuration file
 
 [source,yaml]
 ----

modules/virt-template-windows-vm.adoc

@@ -3,7 +3,7 @@
 // * virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc
 
 [id="virt-template-windows-vm_{context}"]
-= Template: Windows virtual machine configuration file
+= Windows virtual machine configuration file
 
 [source,yaml]
 ----

virt/live_migration/virt-migrating-vm-on-secondary-network.adoc

@@ -1,12 +1,12 @@
 :_content-type: ASSEMBLY
 [id="virt-migrating-vm-on-secondary-network"]
-= Migrating a virtual machine over a dedicated secondary network
+= Migrating a virtual machine over a dedicated additional network
 include::_attributes/common-attributes.adoc[]
 :context: virt-migrating-vm-on-secondary-network
 
 toc::[]
 
-You can configure a dedicated xref:../../virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc#attaching-to-multiple-networks[secondary Multus network] for live migration. A dedicated network minimizes disruption to tenant workloads due to network saturation when virtual machine live migration is triggered.
+You can configure a dedicated xref:../../virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc#virt-attaching-vm-multiple-networks[Multus network] for live migration. A dedicated network minimizes the effects of network saturation on tenant workloads during live migration.
 
 
 include::modules/virt-configuring-secondary-network-vm-live-migration.adoc[leveloffset=+1]

virt/virt-learn-more-about-openshift-virtualization.adoc

@@ -46,7 +46,7 @@ Use the following tables to find content to help you learn about and use {VirtPr
 |Learn |Deploy |Manage |Use
 
 | xref:../virt/about-virt.adoc#about-virt[Learn about {VirtProductName}]
-| Connecting virtual machines to the xref:../virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc#virt-using-the-default-pod-network-with-virt[default pod network for virtual machines] and xref:../virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc#attaching-to-multiple-networks[multiple networks]
+| Connecting virtual machines to the xref:../virt/virtual_machines/vm_networking/virt-using-the-default-pod-network-with-virt.adoc#virt-using-the-default-pod-network-with-virt[default pod network for virtual machines] and xref:../virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc#virt-attaching-vm-multiple-networks[external networks]
 | xref:../virt/install/virt-enabling-virtctl.adoc#virt-enabling-virtctl[Enabling the `virtctl` client]
 | xref:../migration_toolkit_for_containers/about-mtc.adoc#about-mtc[Importing virtual machines with the Migration Toolkit for containers]
 

virt/virtual_machines/advanced_vm_management/virt-configuring-pxe-booting.adoc

@@ -14,12 +14,12 @@ image from a PXE server when deploying a new host.
 
 == Prerequisites
 
-* A Linux bridge must be xref:../../../virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc#attaching-to-multiple-networks[connected].
+* A Linux bridge must be xref:../../../virt/virtual_machines/vm_networking/virt-attaching-vm-multiple-networks.adoc#virt-attaching-vm-multiple-networks[connected].
 
 * The PXE server must be connected to the same VLAN as the bridge.
 
-include::modules/virt-networking-glossary.adoc[leveloffset=+1]
-
 include::modules/virt-pxe-booting-with-mac-address.adoc[leveloffset=+1]
 
 include::modules/virt-template-vm-pxe-config.adoc[leveloffset=+1]
+
+include::modules/virt-networking-glossary.adoc[leveloffset=+1]