Skip to content

Connecting a virtual machine to a Linux bridge network

By default, OpenShift Virtualization is installed with a single, internal pod network.

You can create a Linux bridge network and attach a virtual machine (VM) to the network by performing the following steps:

  1. Create a Linux bridge node network configuration policy (NNCP).

  2. Create a Linux bridge network attachment definition (NAD) by using the web console or the command line.

  3. Configure the VM to recognize the NAD by using the web console or the command line.

Note

OpenShift Virtualization does not support Linux bridge bonding modes 0, 5, and 6. For more information, see Which bonding modes work when used with a bridge that virtual machine guests or containers connect to?.

Creating a Linux bridge NNCP

You can create a NodeNetworkConfigurationPolicy (NNCP) manifest for a Linux bridge network.

Prerequisites

  • You have installed the Kubernetes NMState Operator.

Procedure

  • Create the NodeNetworkConfigurationPolicy manifest. This example includes sample values that you must replace with your own information.

    apiVersion: nmstate.io/v1
kind: NodeNetworkConfigurationPolicy
metadata:
  name: br1-eth1-policy
spec:
  desiredState:
    interfaces:
      - name: br1
        description: Linux bridge with eth1 as a port
        type: linux-bridge
        state: up
        ipv4:
          enabled: false
        bridge:
          options:
            stp:
              enabled: false
          port:
            - name: eth1

    • metadata.name defines the name of the node network configuration policy.

    • spec.desiredState.interfaces.name defines the name of the new Linux bridge.

    • spec.desiredState.interfaces.description is an optional field that can be used to define a human-readable description for the bridge.

    • spec.desiredState.interfaces.type defines the interface type. In this example, the type is a Linux bridge.

    • spec.desiredState.interfaces.state defines the requested state for the interface after creation.

    • spec.desiredState.interfaces.ipv4.enabled defines whether the ipv4 protocol is active. Setting this to false disables IPv4 addressing on this bridge.

    • spec.desiredState.interfaces.bridge.options.stp.enabled defines whether STP is active. Setting this to false disables STP on this bridge.

    • spec.desiredState.interfaces.bridge.port.name defines the node NIC to which the bridge is attached.

      Note

      To create the NNCP manifest for a Linux bridge using OSA with IBM Z®, you must disable VLAN filtering by the setting the rx-vlan-filter to false in the NodeNetworkConfigurationPolicy manifest.

      Alternatively, if you have SSH access to the node, you can disable VLAN filtering by running the following command:

      $ sudo ethtool -K <osa-interface-name> rx-vlan-filter off

Creating a Linux bridge NAD

You can create a Linux bridge network attachment definition (NAD) by using the OpenShift Container Platform web console or command line.

Creating a Linux bridge NAD by using the web console

You can create a network attachment definition (NAD) to provide layer-2 networking to pods and virtual machines by using the OpenShift Container Platform web console.

Warning

Configuring IP address management (IPAM) in a network attachment definition for virtual machines is not supported.

Procedure

  1. In the web console, click Networking → NetworkAttachmentDefinitions.

  2. Click Create Network Attachment Definition.

    Note

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

  3. Enter a unique Name and optional Description.

  4. Select CNV Linux bridge from the Network Type list.

  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.

    Note

    OSA interfaces on IBM Z® do not support VLAN filtering and VLAN-tagged traffic is dropped. Avoid using VLAN-tagged NADs with OSA interfaces.

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

  8. Click Create.

Creating a Linux bridge NAD by using the CLI

You can create a network attachment definition (NAD) to provide layer-2 networking to pods and virtual machines (VMs) by using the command line.

The NAD and the VM must be in the same namespace.

Warning

Configuring IP address management (IPAM) in a network attachment definition for virtual machines is not supported.

Prerequisites

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Add the VM to the NetworkAttachmentDefinition configuration, as in the following example:

    apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: bridge-network 
  annotations:
    k8s.v1.cni.cncf.io/resourceName: bridge.network.kubevirt.io/br1 
spec:
  config: |
    {
      "cniVersion": "0.3.1",
      "name": "bridge-network", 
      "type": "bridge", 
      "bridge": "br1", 
      "macspoofchk": false, 
      "vlan": 100, 
      "disableContainerInterface": true,
      "preserveDefaultVlan": false 
    }
    1. The name for the NetworkAttachmentDefinition object.
    2. Optional: Annotation key-value pair for node selection for the 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 defined 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) plugin 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. The name should match the interface bridge name defined in the NodeNetworkConfigurationPolicy manifest.
    6. Optional: A flag to enable the MAC spoof check. When set to true, you cannot change the MAC address of the pod or guest interface. This attribute allows only a single MAC address to exit the pod, which provides security against a MAC spoofing attack.
    7. Optional: The VLAN tag. No additional VLAN configuration is required on the node network configuration policy.

      Note

      OSA interfaces on IBM Z® do not support VLAN filtering and VLAN-tagged traffic is dropped. Avoid using VLAN-tagged NADs with OSA interfaces.

    8. Optional: Indicates whether the VM connects to the bridge through the default VLAN. The default value is true.

  2. Optional: If you want to connect a VM to the native network, configure the Linux bridge NetworkAttachmentDefinition manifest without specifying any VLAN:

    apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: bridge-network
  annotations:
    k8s.v1.cni.cncf.io/resourceName: bridge.network.kubevirt.io/br1
spec:
  config: |
    {
      "cniVersion": "0.3.1",
      "name": "bridge-network",
      "type": "bridge",
      "bridge": "br1",
      "macspoofchk": false,
      "disableContainerInterface": true
    }

  3. Create the network attachment definition:

    $ oc create -f network-attachment-definition.yaml
    1. Where network-attachment-definition.yaml is the file name of the network attachment definition manifest.
Verification

  • Verify that the network attachment definition was created by running the following command:

    $ oc get network-attachment-definition bridge-network

Enabling port isolation for a Linux bridge NAD

You can enable port isolation for a Linux bridge network attachment definition (NAD) so that virtual machines (VMs) or pods that run on the same virtual LAN (VLAN) can operate in isolation from one another.

The Linux bridge NAD creates a virtual bridge, or virtual switch, between network interfaces and the physical network.

Isolating ports in this way can provide enhanced security for VM workloads that run on the same node.

Prerequisites

  • For VMs, you configured either a static or dynamic IP address for each VM. See "Configuring IP addresses for virtual machines".

  • You created a Linux bridge NAD by using either the web console or the command-line interface.

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Edit the Linux bridge NAD by setting portIsolation to true:

    apiVersion: "k8s.cni.cncf.io/v1"
kind: NetworkAttachmentDefinition
metadata:
  name: bridge-network
  annotations:
    k8s.v1.cni.cncf.io/resourceName: bridge.network.kubevirt.io/br1
spec:
  config: |
    {
      "cniVersion": "0.3.1",
      "name": "bridge-network", 
      "type": "bridge", 
      "bridge": "br1", 
      "preserveDefaultVlan": false,
      "vlan": 100,
      "disableContainerInterface": false,
      "portIsolation": true 
    }
# ...
    1. The name for the configuration. The name must match the value in the metadata.name of the NAD.
    2. The actual name of the Container Network Interface (CNI) plugin that provides the network for this network attachment definition. Do not change this field unless you want to use a different CNI.
    3. The name of the Linux bridge that is configured on the node. The name must match the interface bridge name defined in the NodeNetworkConfigurationPolicy manifest.
    4. Enables or disables port isolation on the virtual bridge. Default value is false. When set to true, each VM or pod is assigned to an isolated port. The virtual bridge prevents traffic from one isolated port from reaching another isolated port.

  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.

Additional resources

Configuring a VM network interface

You can configure a virtual machine (VM) network interface by using the OpenShift Container Platform web console or command line.

Configuring a VM network interface by using the web console

You can configure a network interface for a virtual machine (VM) by using the OpenShift Container Platform web console.

Prerequisites

  • You created a network attachment definition for the network.

Procedure

  1. Navigate to Virtualization → VirtualMachines.

  2. Click a VM to view the VirtualMachine details page.

  3. On the Configuration tab, click the Network interfaces tab.

  4. Click Add network interface.

  5. Enter the interface name and select the network attachment definition from the Network list.

  6. Click Save.

  7. Restart or live migrate the VM to apply the changes.

Networking fields

Name Description

Name

Name for the network interface controller.

Model

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

For IBM Z® (s390x) and ARM64 (arm64) systems, use the virtio NIC model option. The e1000e model is not supported on these architectures.

Network

List of available network attachment definitions.

Type

List of available binding methods. Select the binding method suitable for the network interface:

  • Default pod network: masquerade

  • Linux bridge network: bridge

  • SR-IOV network: SR-IOV

    On IBM Z®, SR-IOV is not supported.

MAC Address

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

Configuring a VM network interface by using the CLI

You can configure a virtual machine (VM) network interface for a bridge network by using the command line.

Prerequisites

  • You have installed the OpenShift CLI (oc).

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

Procedure

  1. Add the bridge interface and the network attachment definition to the VM configuration as in the following example:

    apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: example-vm
spec:
  template:
    spec:
      domain:
        devices:
          interfaces:
            - bridge: {}
              name: bridge-net
# ...
      networks:
        - name: bridge-net
          multus:
            networkName: bridge-network

    where:

    spec.template.spec.domain.devices.interface

    Specifies the name of the bridge interface.

    spec.template.spec.networks.name

    Specifies the name of the network. This value must match the name value of the corresponding spec.template.spec.domain.devices.interfaces entry.

    spec.template.spec.networks.multus.networkName

    Specifies the name of the network attachment definition.

  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.

    Note

    When running OpenShift Virtualization on IBM Z® using OSA, RoCE, or HiperSockets interfaces, you must register the MAC address of the device. For more information, see OSA interface traffic forwarding (IBM documentation).