This is a cache of https://docs.okd.io/4.19/virt/vm_networking/virt-connecting-vm-to-secondary-udn.html. It is a snapshot of the page at 2025-07-01T21:46:38.387+0000.
Connecting a VM to a secondary localnet <strong>user</strong>-defined network - Networking | Virtualization | OKD 4.19
  1. Documentation
×

Connecting a virtual machine to a secondary localnet user-defined network

You can connect a virtual machine (VM) to an OVN-Kubernetes localnet secondary network by using the CLI. Cluster administrators can use the ClusteruserDefinedNetwork (CUDN) custom resource definition (CRD) to create a shared OVN-Kubernetes network across multiple namespaces.

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 must use the ipBlock attribute to define network policy ingress and egress rules for specific CIDR blocks. Using pod or namespace selector policy peers is not supported.

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.

Creating a user-defined-network for localnet topology by using the CLI

You can create a secondary cluster-scoped user-defined-network (CUDN) for the localnet network topology by using the CLI.

Prerequisites

  • You are logged in to the cluster as a user with cluster-admin privileges.

  • You have installed the OpenShift CLI (oc).

  • You installed the Kubernetes NMState Operator.

Procedure

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

    Example NodeNetworkConfigurationPolicy manifest
    apiVersion: nmstate.io/v1
kind: NodeNetworkConfigurationPolicy
metadata:
  name: mapping (1)
spec:
  nodeSelector:
    node-role.kubernetes.io/worker: '' (2)
  desiredState:
    ovn:
      bridge-mappings:
      - localnet: tenantblue (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 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.network.localnet.physicalNetworkName field of the ClusteruserDefinedNetwork object that defines the OVN-Kubernetes additional network. This example uses the name tenantblue.
    4 The name of the OVS bridge on the node. This value is required if the state attribute is present or not specified.
    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. Apply the NodeNetworkConfigurationPolicy manifest by running the following command:

    $ oc apply -f <filename>.yaml

    where:

    <filename>

    Specifies the name of your NodeNetworkConfigurationPolicy manifest YAML file.

  3. Create a ClusteruserDefinedNetwork object to create a localnet secondary network:

    Example ClusteruserDefinedNetwork manifest
    apiVersion: k8s.ovn.org/v1
kind: ClusteruserDefinedNetwork
metadata:
  name: cudn-localnet (1)
spec:
  namespaceSelector: (2)
    matchExpressions: (3)
    - key: kubernetes.io/metadata.name
      operator: In (4)
      values: ["red", "blue"]
  network:
    topology: Localnet (5)
    localnet:
        role: Secondary (6)
        physicalNetworkName: tenantblue (7)
        ipam:
          mode: Disabled (8)
# ...
    1 The name of the ClusteruserDefinedNetwork custom resource.
    2 The set of namespaces that the cluster UDN applies to. The namespace selector must not point to the following values: default; an openshift-* namespace; or any global namespaces that are defined by the Cluster Network Operator (CNO).
    3 The type of selector. In this example, the matchExpressions selector selects objects that have the label kubernetes.io/metadata.name with the value red or blue.
    4 The type of operator. Possible values are In, NotIn, and Exists.
    5 The topological configuration of the network. A Localnet topology connects the logical network to the physical underlay.
    6 Specifies whether the UDN is primary or secondary. The required value is Secondary for topology: Localnet.
    7 The name of the OVN-Kubernetes bridge mapping that is configured on the node. This value must match the spec.desiredState.ovn.bridge-mappings.localnet field in the NodeNetworkConfigurationPolicy manifest that you previously created. This ensures that you are bridging to the intended segment of your physical network.
    8 Specifies whether IP address management (IPAM) is enabled or disabled. The required value is Disabled. OKD Virtualization does not support configuring IPAM for virtual machines.

  4. Apply the ClusteruserDefinedNetwork manifest by running the following command:

    $ oc apply -f <filename>.yaml

    where:

    <filename>

    Specifies the name of your ClusteruserDefinedNetwork manifest YAML file.

Creating a namespace for secondary user-defined networks by using the CLI

You can create a namespace to be used with an existing secondary cluster-scoped user-defined network (CUDN) by using the CLI.

Prerequisites

  • You are logged in to the cluster as a user with cluster-admin permissions.

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Create a Namespace object similar to the following example:

    Example Namespace manifest
    apiVersion: v1
kind: Namespace
metadata:
  name: cudn_namespace
# ...

  2. Apply the Namespace manifest by running the following command:

    oc apply -f <filename>.yaml

    where:

    <filename>

    Specifies the name of your Namespace manifest YAML file.

Attaching a virtual machine to secondary user-defined networks by using the CLI

You can connect a virtual machine (VM) to multiple secondary cluster-scoped user-defined networks (CUDNs) by configuring the interface binding.

Prerequisites

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Edit the VirtualMachine manifest to add the CUDN interface details, as in the following example:

    Example VirtualMachine manifest
    apiVersion: kubevirt.io/v1
kind: VirtualMachine
metadata:
  name: example-vm
  namespace: my-namespace (1)
spec:
  template:
    spec:
      domain:
        devices:
          interfaces:
            - name: secondary_localnet (2)
              bridge: {}
        machine:
          type: ""
        resources:
          requests:
            memory: 2048M
      networks:
      - name: secondary_localnet (3)
        multus:
          networkName: <localnet_cudn_name> (4)
# ...
    1 The namespace in which the VM is located. This value must match a namespace that is associated with the secondary CUDN.
    2 The name of the secondary user-defined network interface.
    3 The name of the network. This must match the value of the spec.template.spec.domain.devices.interfaces.name field.
    4 The name of the localnet ClusteruserDefinedNetwork object that you previously created.

  2. Apply the VirtualMachine manifest by running the following command:

    $ oc apply -f <filename>.yaml

    where:

    <filename>

    Specifies the name of your VirtualMachine manifest YAML file.

Additional resources