1. Documentation
×

Hot swapping a virtual machine secondary network

You can change the secondary network of a virtual machine (VM) without rebooting your VM. The change is transparent to the guest operating system, preserving properties like the MAC address.

By hot swapping the secondary network, you can move a running VM to a different network segment or VLAN and apply new network policies or reconfigure network topology without interrupting the workload. OKD Virtualization supports hot swapping for VMs that are connected to an OVN-Kubernetes localnet and a Linux bridge secondary network.

To hot swap a VM secondary network, you must edit the network configuration of the running VM to refer to a new NetworkAttachmentDefinition or ClusterUserDefinedNetwork manifest. This action triggers a live migration, connecting the VM to the new network without a reboot.

Hot swap limitations

OKD Virtualization supports hot swapping for VMs that are connected to an OVN-Kubernetes localnet and a Linux bridge secondary network.

Consider the following limitations before hot swapping a VM secondary network:

  • Hot swapping only works for VMs that are live migratable.

  • Network connectivity might be interrupted during the live migration process.

  • If you update network references for multiple VMs, the updates might be queued because only a limited number of live migrations can run in parallel across the cluster.

  • You cannot hot swap to a new network binding type or a Container Network Interface (CNI) plugin. For example, you cannot change from bridge binding to SR-IOV binding.

  • The target NetworkAttachmentDefinition and ClusterUserDefinedNetwork objects must be valid and all referenced resources such as bridges, VLANs, and network resources must exist. Migration completes even if the network configuration is invalid, but the VM will lose network connectivity.

  • This feature applies only to secondary networks attached by using NetworkAttachmentDefinition or ClusterUserDefinedNetwork manifests. You cannot hot swap the primary pod network, regardless of whether it uses the default cluster network or a custom primary user-defined network.

  • If the new network requires a different IP configuration, such as a different subnet or gateway, you must reconfigure the guest operating system network settings. The hot swap does not automatically update the guest network configuration.

Hot swapping a virtual machine secondary network by using the command line

You can hot swap a virtual machine (VM) secondary network by using the command line.

Prerequisites

  • The VM to which you want to hot swap the network is running and is live migratable.

  • You have installed the OpenShift CLI (oc).

  • The target NetworkAttachmentDefinition object exists in the same namespace as the VM. If you created a ClusterUserDefinedNetwork object, verify that the cluster user-defined network controller has created the corresponding NetworkAttachmentDefinition object.

    Example NetworkAttachmentDefinition manifest:

    apiVersion: k8s.cni.cncf.io/v1
kind: NetworkAttachmentDefinition
metadata:
  name: nad-with-vlan20
spec:
  config: '{
    "cniVersion": "0.3.1",
    "name": "nad-with-vlan20",
    "type": "bridge",
    "bridge": "br2",
    "vlan": 20
  }'
Procedure

  1. Use your preferred text editor to edit the VirtualMachine manifest, as shown in the following example:

    apiVersion: kubevirt.io/v1
kind: VirtualMachine
...
  template:
    spec:
      domain:
        devices:
          interfaces:
          - bridge: {}
            name: bridge-net
      networks:
      - name: bridge-net
        multus:
          networkName: nad-with-vlan20
#...

    • spec.networks.name specifies the name of the network. This must be the same as the name of the new network interface that you defined in the template.spec.domain.devices.interfaces list.

    • spec.networks.multus.networkName specifies the name of the target NetworkAttachmentDefinition object.

  2. Save your changes and exit the editor.

  3. For the new configuration to take effect, apply the changes by running the following command. If your OKD cluster has live migration enabled, applying the changes triggers automatic VM live migration and connects the new network to the running VM.

    $ oc apply -f <filename>.yaml

    where:

    <filename>

    Specifies the name of your VirtualMachine manifest YAML file.

Verification

  1. Verify that the VM live migration is progressing successfully by using the following command.

    $ oc get vmi vm-fedora -w -o jsonpath='{.status.conditions[?(@.type=="MigrationRequired")]}{"\n"}'

    Example output:

    {"type":"MigrationRequired","status":"True","lastProbeTime":null,"lastTransitionTime":"2024-05-27T10:15:30Z","reason":"AutoMigrationDueToLiveUpdate","message":""}

  2. Use the following command to connect to the VM console and to devices on the new network:

    $ virtctl console vm-fedora

Additional resources