Starting on March 12, 2025, OpenShift docs will only be available at docs.redhat.com. From that time on, docs.openshift.com links will automatically redirect to their locations on docs.redhat.com.
  1. Documentation
    2. history bug_report picture_as_pdf
×

Connecting a virtual machine to a primary user-defined network

You can connect a virtual machine (VM) to a user-defined network (UDN) on the VM’s primary interface. The primary user-defined network replaces the default pod network in your specified namespace. Unlike the pod network, you can define the primary UDN per project, where each project can use its specific subnet and topology.

OpenShift Virtualization supports the namespace-scoped UserDefinedNetwork and the cluster-scoped ClusterUserDefinedNetwork custom resource definitions (CRD).

Tenant owners can configure a primary UserDefinedNetwork CRD to create a network that isolates their namespace from other namespaces without requiring network policies. Cluster administrators can use the ClusterUserDefinedNetwork CRD to create a shared OVN network across multiple namespaces.

You must add the k8s.ovn.org/primary-user-defined-network label when you create a namespace that is to be used with user-defined networks.

With the layer 2 topology, OVN-Kubernetes creates 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.

The layer 2 topology enables seamless migration of VMs without the need for Network Address Translation (NAT) because persistent IP addresses are preserved across cluster nodes during live migration.

You must consider the following limitations before implementing a primary UDN:

  • You cannot use the virtctl ssh command to configure SSH access to a VM.

  • You cannot use the oc port-forward command to forward ports to a VM.

  • You cannot use headless services to access a VM.

  • You cannot define readiness and liveness probes to configure VM health checks.

OpenShift Virtualization currently does not support secondary user-defined networks.

Creating a primary namespace-scoped user-defined network

You can create an isolated primary network in your project namespace. You must use the OVN-Kubernetes layer 2 topology and enable persistent IP address allocation in the user-defined network (UDN) configuration to ensure VM live migration support.

Prerequisites

  1. You have installed the OpenShift CLI (oc).

  2. You have created a namespace and applied the k8s.ovn.org/primary-user-defined-network label.

Procedure

  1. Create a UserDefinedNetwork object to specify the custom network configuration:

    Example UserDefinedNetwork manifest
    apiVersion: k8s.ovn.org/v1
kind: UserDefinedNetwork
metadata:
  name: udn-l2-net (1)
  namespace: my-namespace (2)
spec:
  topology: Layer2 (3)
  layer2:
    role: Primary (4)
    subnets:
      - "10.0.0.0/24"
      - "2001:db8::/60"
  ipam:
    lifecycle: Persistent (5)
    1 Specifies the name of the UserDefinedNetwork custom resource.
    2 Specifies the namespace in which the VM is located. The namespace must have the k8s.ovn.org/primary-user-defined-network label. The namespace must not be default, an openshift-* namespace, or match any global namespaces that are defined by the Cluster Network Operator (CNO).
    3 Specifies the topological configuration of the network. The required value is Layer2. A Layer2 topology creates a logical switch that is shared by all nodes.
    4 Specifies if the UDN is primary or secondary. OpenShift Virtualization only supports the Primary role. This means that the UDN acts as the primary network for the VM and all default traffic passes through this network.
    5 Specifies that virtual workloads have consistent IP addresses across reboots and migration. The spec.layer2.subnets field is required when ipam.lifecycle: Persistent is specified.

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

    $ oc apply -f --validate=true <filename>.yaml

Creating a primary cluster-scoped user-defined network

You can connect multiple namespaces to the same primary user-defined network (UDN) to achieve native tenant isolation.

Prerequisites

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

  2. You have installed the OpenShift CLI (oc).

  3. You have created multiple namespaces with the k8s.ovn.org/primary-user-defined-network label.

Procedure

  1. Create a ClusterUserDefinedNetwork object to specify the custom network configuration:

    Example ClusterUserDefinedNetwork manifest
    kind: ClusterUserDefinedNetwork
metadata:
  name: cudn-l2-net (1)
spec:
  namespaceSelector: (2)
    matchExpressions: (3)
    - key: kubernetes.io/metadata.name
      operator: In (4)
      values: ["red-namespace", "blue-namespace"]
  network:
    topology: Layer2 (5)
    layer2:
      role: Primary (6)
      ipam:
        lifecycle: Persistent
      subnets:
        - 203.203.0.0/16
    1 Specifies the name of the ClusterUserDefinedNetwork custom resource.
    2 Specifies the set of namespaces that the cluster UDN applies to. The namespace selector must not point to default, an openshift-* namespace, or any global namespaces that are defined by the Cluster Network Operator (CNO).
    3 Specifies the type of selector. In this example, the matchExpressions selector selects objects that have the label kubernetes.io/metadata.name with the value red-namespace or blue-namespace.
    4 Specifies the type of operator. Possible values are In, NotIn, and Exists.
    5 Specifies the topological configuration of the network. The required value is Layer2. A Layer2 topology creates a logical switch that is shared by all nodes.
    6 Specifies if the UDN is primary or secondary. OpenShift Virtualization only supports the Primary role. This means that the UDN acts as the primary network for the VM and all default traffic passes through this network.

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

    $ oc apply -f --validate=true <filename>.yaml

Attaching a virtual machine to the primary user-defined network

You can connect a virtual machine (VM) to the primary user-defined network (UDN) by requesting the pod network attachment, and configuring the interface binding.

Prerequisites

  • You have installed the OpenShift CLI (oc).

Procedure

  1. Edit the VirtualMachine manifest to add the UDN 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: udn-l2-net (2)
              binding:
                name: l2bridge (3)
# ...
      networks:
      - name: udn-l2-net (4)
        pod: {}
# ...
    1 The namespace in which the VM is located. This value must match the namespace in which the UDN is defined.
    2 The name of the user-defined network interface.
    3 The name of the binding plugin that is used to connect the interface to the VM. The required value is l2bridge.
    4 The name of the network. This must match the value of the spec.template.spec.domain.devices.interfaces.name field.

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

    $ oc apply -f <filename>.yaml

Additional resources