You can attach virtual machines to multiple networks by using Linux bridges. You can also import virtual machines with existing workloads that depend on access to multiple interfaces.

To attach a virtual machine to an additional network:

  1. Configure a Linux bridge.

  2. Configure a bridge network attachment definition for a namespace in the web console or CLI.

    The network attachment definition must be in the same namespace as the pod or virtual machine.

  3. Attach the virtual machine to the network attachment definition by using either the web console or the CLI:

    • In the web console, create a NIC for a new or existing virtual machine.

    • In the CLI, include the network information in the virtual machine configuration.

There are multiple methods for configuring a VLAN, including network attachment definition and node network configuration policy. However, a network attachment definition provides a more efficient and more manageable configuration.

OpenShift Virtualization networking glossary

OpenShift Virtualization provides advanced networking functionality by using custom resources and plug-ins.

The following terms are used throughout OpenShift Virtualization documentation:

Container Network Interface (CNI)

a Cloud Native Computing Foundation project, focused on container network connectivity. OpenShift Virtualization uses CNI plug-ins to build upon the basic Kubernetes networking functionality.


a "meta" CNI plug-in that allows multiple CNIs to exist so that a pod or virtual machine can use the interfaces it needs.

Custom resource definition (CRD)

a Kubernetes API resource that allows you to define custom resources, or an object defined by using the CRD API resource.

Network attachment definition (NAD)

a CRD introduced by the Multus project that allows you to attach pods, virtual machines, and virtual machine instances to one or more networks.

Node network configuration policy (NNCP)

a description of the requested network configuration on nodes. You update the node network configuration, including adding and removing interfaces, by applying a NodeNetworkConfigurationPolicy manifest to the cluster.

Preboot eXecution Environment (PXE)

an interface that enables an administrator to boot a client machine from a server over the network. Network booting allows you to remotely load operating systems and other software onto the client.

Configuring a Linux bridge

Creating a Linux bridge using a node network configuration policy

As a network administrator, you can create a Linux bridge interface on nodes in the cluster by applying a NodeNetworkConfigurationPolicy manifest to the cluster.

  1. 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.

apiVersion: nmstate.io/v1
kind: NodeNetworkConfigurationPolicy
  name: br1-eth1-policy (1)
      - name: br1 (2)
        description: Linux bridge with eth1 as a port (3)
        type: linux-bridge (4)
        state: up (5)
          enabled: false (6)
              enabled: false (7)
            - name: eth1 (8)
1 Name of the policy.
2 Name of the interface.
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.

For more information about scheduling, interface types, and other node networking activities, see the node networking section.

Creating a network attachment definition

Configuring ipam in a network attachment definition for virtual machines is not supported.

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.

  1. In the web console, click NetworkingNetwork Attachment Definitions.

  2. Click Create Network Attachment Definition .

  3. Enter a unique Name and optional Description.

  4. Click the Network Type list and select CNV Linux bridge.

  5. Enter the name of the bridge in the Bridge Name field.

  6. Optional: If the resource has VLAN IDs configured, enter the ID numbers in the VLAN Tag Number field.

  7. 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.

  8. Click Create.

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.

  • The node must support nftables and the nft binary must be deployed to enable MAC spoof check.

  1. Create a network attachment definition manifest. The manifest must have the following contents, modified to match your configuration:

    apiVersion: "k8s.cni.cncf.io/v1"
    kind: NetworkAttachmentDefinition
      name: <a-bridge-network> (1)
        k8s.v1.cni.cncf.io/resourceName: bridge.network.kubevirt.io/<bridge-interface> (2)
      config: '{
        "cniVersion": "0.3.1",
        "name": "<a-bridge-network>", (3)
        "type": "cnv-bridge", (4)
        "bridge": "<bridge-interface>", (5)
        "macspoofchk": true, (6)
        "vlan": 1 (7)
    1 The name for the NetworkAttachmentDefinition object.
    2 Optional: Annotation key-value pair for node selection, where bridge-interface must match the name of a bridge configured on some nodes. If you add this annotation to your network attachment definition, your virtual machine instances will only run on the nodes that have the bridge-interface bridge connected.
    3 The name for the configuration. It is recommended to match the configuration name to the name value of the network attachment definition.
    4 The actual name of the Container Network Interface (CNI) plug-in that provides the network for this network attachment definition. Do not change this field unless you want to use a different CNI.
    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.
  2. Create the network attachment definition:

    $ oc create -f <network-attachment-definition.yaml> (1)
    1 Where <network-attachment-definition.yaml> is the file name of the network attachment definition manifest.
  • 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:

    $ oc get network-attachment-definition <a-bridge-network> (1)
    1 Where <a-bridge-network> is the name specified in the network attachment definition config.

Attaching the virtual machine to the additional network

Creating a NIC for a virtual machine in the web console

Create and attach additional NICs to a virtual machine from the web console.

  1. In the correct project in the OpenShift Virtualization console, click WorkloadsVirtualization from the side menu.

  2. Click the Virtual Machines tab.

  3. Select a virtual machine to open the Virtual Machine Overview screen.

  4. Click Network Interfaces to display the NICs already attached to the virtual machine.

  5. Click Add Network Interface to create a new slot in the list.

  6. Use the Network drop-down list to select the network attachment definition for the additional network.

  7. Fill in the Name, Model, Type, and MAC Address for the new NIC.

  8. Click Add to save and attach the NIC to the virtual machine.

Networking fields

Name Description


Name for the network interface controller.


Indicates the model of the network interface controller. Supported values are e1000e and virtio.


List of available network attachment definitions.


List of available binding methods. For the default pod network, masquerade is the only recommended binding method. For secondary networks, use the bridge binding method. The masquerade method is not supported for non-default networks. Select SR-IOV if you configured an SR-IOV network device and defined that network in the namespace.

MAC Address

MAC address for the network interface controller. If a MAC address is not specified, one is assigned automatically.

Attaching a virtual machine to a secondary 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.

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.

  • Shut down the virtual machine before editing the configuration. If you edit a running virtual machine, you must restart the virtual machine for the changes to take effect.

  1. 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:

    apiVersion: kubevirt.io/v1
    kind: VirtualMachine
        name: example-vm
                - masquerade: {}
                  name: default
                - bridge: {}
                  name: bridge-net (1)
            - name: default
              pod: {}
            - name: bridge-net (2)
                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.
  2. Apply the configuration:

    $ oc apply -f <example-vm.yaml>
  3. Optional: If you edited a running virtual machine, you must restart it for the changes to take effect.