1. Documentation
×

Connecting a virtual machine to an OVN-Kubernetes secondary network

You can connect a virtual machine (VM) to an OVN-Kubernetes secondary network. OKD Virtualization supports the layer2 and localnet topologies for OVN-Kubernetes.

  • A layer2 topology connects workloads by a cluster-wide logical switch. The OVN-Kubernetes Container Network Interface (CNI) plugin uses the Geneve (Generic Network Virtualization Encapsulation) protocol to create an overlay network between nodes. You can use this overlay network to connect VMs on different nodes, without having to configure any additional physical networking infrastructure.

  • A localnet topology connects the secondary network to the physical underlay. This enables both east-west cluster traffic and access to services running outside the cluster, but it requires additional configuration of the underlying Open vSwitch (OVS) system on cluster nodes.

An OVN-Kubernetes secondary network is compatible with the multi-network policy API which provides the MultiNetworkPolicy custom resource definition (CRD) to control traffic flow to and from VMs. You can use the ipBlock attribute to define network policy ingress and egress rules for specific CIDR blocks.

To configure an OVN-Kubernetes secondary network and attach a VM to that network, perform the following steps:

  1. Configure an OVN-Kubernetes secondary network by creating a network attachment definition (NAD).

    For localnet topology, you must configure an OVS bridge by creating a NodeNetworkConfigurationPolicy object before creating the NAD.

  2. Connect the VM to the OVN-Kubernetes secondary network by adding the network details to the VM specification.

Creating an OVN-Kubernetes NAD

You can create an OVN-Kubernetes network attachment definition (NAD) by using the OKD web console or the CLI.

Configuring IP address management (IPAM) by specifying the spec.config.ipam.subnet attribute in a network attachment definition for virtual machines is not supported.

Creating a NAD for layer 2 topology using the CLI

You can create a network attachment definition (NAD) which describes how to attach a pod to the layer 2 overlay network.

Prerequisites

  • You have access to the cluster as a user with cluster-admin privileges.

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Create a NetworkAttachmentDefinition object:

    apiVersion: k8s.cni.cncf.io/v1
kind: NetworkAttachmentDefinition
metadata:
  name: l2-network
  namespace: my-namespace
spec:
  config: |-
    {
            "cniVersion": "0.3.1", (1)
            "name": "my-namespace-l2-network", (2)
            "type": "ovn-k8s-cni-overlay", (3)
            "topology":"layer2", (4)
            "mtu": 1300, (5)
            "netAttachDefName": "my-namespace/l2-network" (6)
    }
    1 The CNI specification version. The required value is 0.3.1.
    2 The name of the network. This attribute is not namespaced. For example, you can have a network named l2-network referenced from two different NetworkAttachmentDefinition objects that exist in two different namespaces. This feature is useful to connect VMs in different namespaces.
    3 The name of the CNI plug-in to be configured. The required value is ovn-k8s-cni-overlay.
    4 The topological configuration for the network. The required value is layer2.
    5 Optional: The maximum transmission unit (MTU) value. The default value is automatically set by the kernel.
    6 The value of the namespace and name fields in the metadata stanza of the NetworkAttachmentDefinition object.

    The above example configures a cluster-wide overlay without a subnet defined. This means that the logical switch implementing the network only provides layer 2 communication. You must configure an IP address when you create the virtual machine by either setting a static IP address or by deploying a DHCP server on the network for a dynamic IP address.

  2. Apply the manifest:

    $ oc apply -f <filename>.yaml

Creating a NAD for localnet topology using the CLI

You can create a network attachment definition (NAD) which describes how to attach a pod to the underlying physical network.

Prerequisites

  • You have access to the cluster as a user with cluster-admin privileges.

  • You have installed the OpenShift CLI (oc).

  • You have installed the Kubernetes NMState Operator.

Procedure

  1. Create a NodeNetworkConfigurationPolicy object to map the OVN-Kubernetes secondary network to an Open vSwitch (OVS) bridge:

    apiVersion: nmstate.io/v1
kind: NodeNetworkConfigurationPolicy
metadata:
  name: mapping (1)
spec:
  nodeSelector:
    node-role.kubernetes.io/worker: '' (2)
  desiredState:
    ovn:
      bridge-mappings:
      - localnet: localnet-network (3)
        bridge: br-ex (4)
        state: present (5)
    1 The name of the configuration object.
    2 Specifies the nodes to which the node network configuration policy is to be applied. The recommended node selector value is node-role.kubernetes.io/worker: ''.
    3 The name of the additional network from which traffic is forwarded to the OVS bridge. This attribute must match the value of the spec.config.name field of the NetworkAttachmentDefinition object that defines the OVN-Kubernetes additional network.
    4 The name of the OVS bridge on the node. This value is required if the state attribute is present.
    5 The state of the mapping. Must be either present to add the mapping or absent to remove the mapping. The default value is present.

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

  2. Create a NetworkAttachmentDefinition object:

    apiVersion: k8s.cni.cncf.io/v1
kind: NetworkAttachmentDefinition
metadata:
  name: localnet-network
  namespace: default
spec:
  config: |-
    {
            "cniVersion": "0.3.1", (1)
            "name": "localnet-network", (2)
            "type": "ovn-k8s-cni-overlay", (3)
            "topology": "localnet", (4)
            "netAttachDefName": "default/localnet-network" (5)
    }
    1 The CNI specification version. The required value is 0.3.1.
    2 The name of the network. This attribute must match the value of the spec.desiredState.ovn.bridge-mappings.localnet field of the NodeNetworkConfigurationPolicy object that defines the OVS bridge mapping.
    3 The name of the CNI plug-in to be configured. The required value is ovn-k8s-cni-overlay.
    4 The topological configuration for the network. The required value is localnet.
    5 The value of the namespace and name fields in the metadata stanza of the NetworkAttachmentDefinition object.

  3. Apply the manifest:

    $ oc apply -f <filename>.yaml

Creating a NAD for layer 2 topology by using the web console

You can create a network attachment definition (NAD) that describes how to attach a pod to the layer 2 overlay network.

Prerequisites

  • You have access to the cluster as a user with cluster-admin privileges.

Procedure

  1. Go to Networking → NetworkAttachmentDefinitions in the web console.

  2. Click Create Network Attachment Definition. The network attachment definition must be in the same namespace as the pod or virtual machine using it.

  3. Enter a unique Name and optional Description.

  4. Select OVN Kubernetes L2 overlay network from the Network Type list.

  5. Click Create.

Creating a NAD for localnet topology using the web console

You can create a network attachment definition (NAD) to connect workloads to a physical network by using the OKD web console.

Prerequisites

  • You have access to the cluster as a user with cluster-admin privileges.

  • Use nmstate to configure the localnet to OVS bridge mappings.

Procedure

  1. Navigate to Networking → NetworkAttachmentDefinitions in the web console.

  2. Click Create Network Attachment Definition. The network attachment definition must be in the same namespace as the pod or virtual machine using it.

  3. Enter a unique Name and optional Description.

  4. Select OVN Kubernetes secondary localnet network from the Network Type list.

  5. Enter the name of your pre-configured localnet identifier in the Bridge mapping field.

  6. Optional: You can explicitly set MTU to the specified value. The default value is chosen by the kernel.

  7. Optional: Encapsulate the traffic in a VLAN. The default value is none.

  8. Click Create.

Attaching a virtual machine to the OVN-Kubernetes secondary network

You can attach a virtual machine (VM) to the OVN-Kubernetes secondary network interface by using the OKD web console or the CLI.

Attaching a virtual machine to an OVN-Kubernetes secondary network using the CLI

You can connect a virtual machine (VM) to the OVN-Kubernetes secondary network by including the network details in the VM configuration.

Prerequisites

  • You have access to the cluster as a user with cluster-admin privileges.

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Edit the VirtualMachine manifest to add the OVN-Kubernetes secondary network interface details, as in the following example:

    apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: vm-server
spec:
  running: true
  template:
    spec:
      domain:
        devices:
          interfaces:
          - name: secondary (1)
            bridge: {}
        resources:
          requests:
            memory: 1024Mi
      networks:
      - name: secondary  (2)
        multus:
          networkName: <nad_name> (3)
      nodeSelector:
        node-role.kubernetes.io/worker: '' (4)
# ...
    1 The name of the OVN-Kubernetes secondary interface.
    2 The name of the network. This must match the value of the spec.template.spec.domain.devices.interfaces.name field.
    3 The name of the NetworkAttachmentDefinition object.
    4 Specifies the nodes on which the VM can be scheduled. The recommended node selector value is node-role.kubernetes.io/worker: ''.

  2. Apply the VirtualMachine manifest:

    $ oc apply -f <filename>.yaml

  3. Optional: If you edited a running virtual machine, you must restart it for the changes to take effect.

Additional resources