This is a cache of https://docs.okd.io/4.16/virt/live_migration/virt-configuring-live-migration.html. It is a snapshot of the page at 2026-04-01T04:41:10.260+0000.
Configuring live migration - Live migration | Virtualization | OKD 4.16
  1. Documentation
×

Configuring live migration

You can configure live migration settings to ensure that the migration processes do not overwhelm the cluster.

You can configure live migration policies to apply different migration configurations to groups of virtual machines (VMs).

Configuring live migration limits and timeouts

Configure live migration limits and timeouts for the cluster by updating the HyperConverged custom resource (CR), which is located in the kubevirt-hyperconverged namespace.

Prerequisites

  • You have installed the OpenShift CLI (oc).

Procedure

  • Edit the HyperConverged CR and add the necessary live migration parameters:

    $ oc edit hyperconverged kubevirt-hyperconverged -n kubevirt-hyperconverged
    Example
    apiVersion: hco.kubevirt.io/v1beta1
kind: HyperConverged
metadata:
  name: kubevirt-hyperconverged
  namespace: kubevirt-hyperconverged
spec:
  liveMigrationConfig:
    bandwidthPerMigration: 64Mi
    completionTimeoutPerGiB: 800
    parallelMigrationsPerCluster: 5
    parallelOutboundMigrationsPerNode: 2
    progressTimeout: 150
    allowPostCopy: false

    where:

    bandwidthPerMigration

    Specifies the bandwidth of each migration in bytes per second. For example, a value of 2048Mi means 2048 MiB/s. Default: 0, which is unlimited.

    completionTimeoutPerGiB

    Specifies the length of time, in seconds per GiB of memory, at which the migration is canceled if it has not completed. For example, a VM with 6GiB memory times out if it has not completed migration in 4800 seconds. If the Migration Method is BlockMigration, the size of the migrating disks is included in the calculation.

    parallelMigrationsPerCluster

    Specifies the number of migrations running in parallel in the cluster. Default: 5.

    parallelOutboundMigrationsPerNode

    Specifies the maximum number of outbound migrations per node. Default: 2.

    progressTimeout

    Specifies the length of time, in seconds, at which the migration is canceled if memory copy fails to make progress. Default: 150.

    allowPostCopy

    Specifies whether the post copy mode is enabled. You can enable post copy mode to allow the migration of one node to another to converge, even if a VM is running a heavy workload and the memory dirty rate is too high. By default, allowPostCopy is set to false.

    You can restore the default value for any spec.liveMigrationConfig field by deleting that key/value pair and saving the file. For example, delete progressTimeout: <value> to restore the default progressTimeout: 150.

Live migration policies

You can create live migration policies to apply different migration configurations to groups of VMs that are defined by VM or project labels.

You can create live migration policies by using the OKD web console.

Creating a live migration policy by using the command line

You can create a live migration policy by using the command line. KubeVirt applies the live migration policy to selected virtual machines (VMs) by using any combination of labels:

  • VM labels such as size, os, or gpu

  • Project labels such as priority, bandwidth, or hpc-workload

For the policy to apply to a specific group of VMs, all labels on the group of VMs must match the labels of the policy.

If multiple live migration policies apply to a VM, the policy with the greatest number of matching labels takes precedence.

If multiple policies meet this criteria, the policies are sorted by alphabetical order of the matching label keys, and the first one in that order takes precedence.
Procedure

  1. Edit the VM object to which you want to apply a live migration policy, and add the corresponding VM labels.

    1. Open the YAML configuration of the resource:

      $ oc edit vm <vm_name>

    2. Adjust the required label values in the .spec.template.metadata.labels section of the configuration. For example, to mark the VM as a production VM for the purposes of migration policies, add the kubevirt.io/environment: production line:

      apiVersion: migrations.kubevirt.io/v1alpha1
kind: VirtualMachine
metadata:
  name: <vm_name>
  namespace: default
  labels:
    app: my-app
    environment: production
spec:
  template:
    metadata:
      labels:
        kubevirt.io/domain: <vm_name>
        kubevirt.io/size: large
        kubevirt.io/environment: production
# ...

    3. Save and exit the configuration.

  2. Configure a MigrationPolicy object with the corresponding labels. The following example configures a policy that applies to all VMs that are labeled as production:

    apiVersion: migrations.kubevirt.io/v1alpha1
kind: MigrationPolicy
metadata:
  name: <migration_policy>
spec:
  selectors:
    namespaceSelector:
      hpc-workloads: "True"
      xyz-workloads-type: ""
    virtualMachineInstanceSelector:
      kubevirt.io/environment: "production"

    where:

    namespaceSelector

    Specifies the project labels.

    virtualMachineInstanceSelector

    Specifies the VM labels.

  3. Create the migration policy by running the following command:

    $ oc create -f <migration_policy>.yaml

Additional resources