diff --git a/docs/install/requirements.md b/docs/install/requirements.md index 86818d98c2f..fde98077218 100644 --- a/docs/install/requirements.md +++ b/docs/install/requirements.md @@ -39,6 +39,14 @@ Harvester nodes have the following hardware requirements and recommendations for - During testing, you can use only one NIC for the [built-in management cluster network](../networking/clusternetwork.md#built-in-cluster-network) (`mgmt`), and for testing the [VM network](../networking/harvester-network.md#create-a-vm-network) that is also carried by `mgmt`. High availability and optimal performance are not guaranteed. ::: +### CPU Specifications + +[Live Migration](../vm/live-migration/) functions correctly only if the CPUs of all physical servers in the [Harvester cluster](../glossary#harvester-cluster) have the same specifications. This requirement applies to all operations that rely on Live Migration functionality, such as automatic VM migration when [Maintenance Mode](../host/#node-maintenance) is enabled. + +Newer CPUs (even those from the same vendor, generation, and family) can have varying capabilities that may be exposed to VM operating systems. To ensure VM stability, Live Migration checks if the CPU capabilities are consistent, and blocks migration attempts when the source and destination are incompatible. + +When creating clusters, adding more hosts to a cluster, and replacing hosts, always use CPUs with the same specifications to prevent operational constraints. + ## Network Requirements Harvester nodes have the following network requirements for installation. diff --git a/docs/vm/live-migration.md b/docs/vm/live-migration.md index 04598387370..00e9a5ddded 100644 --- a/docs/vm/live-migration.md +++ b/docs/vm/live-migration.md @@ -26,6 +26,22 @@ Live migration means moving a virtual machine to a different host without downti ::: +## How Migration Works + +Each node has multiple CPU models that are labeled with different keys. + +- Primary CPU model: `host-model-cpu.node.kubevirt.io/{cpu-model}` +- Supported CPU models: `cpu-model.node.kubevirt.io/{cpu-model}` +- Supported CPU models for migration: `cpu-model-migration.node.kubevirt.io/{cpu-model}` + +During live migration, the system checks the value of `spec.domain.cpu.model` in the VirtualMachineInstance (VMI) CR, which is derived from `spec.template.spec.domain.cpu.model` in the VirtualMachine (VM) CR. If the value of `spec.template.spec.domain.cpu.model` is not set, the system uses the default value `host-model`. + +When `host-model` is used, the process fetches the value of the primary CPU model and fills `spec.NodeSelectors` of the newly created pod with the label `cpu-model-migration.node.kubevirt.io/{cpu-model}`. + +Alternatively, you can customize the CPU model in `spec.domain.cpu.model`. For example, if the CPU model is `XYZ`, the process fills `spec.NodeSelectors` of the newly created pod with the label `cpu-model.node.kubevirt.io/XYZ`. + +However, `host-model` only allows migration of the VM to a node with same CPU model. For more information, see [Limitations](#limitation). + ## Starting a Migration 1. Go to the **Virtual Machines** page. @@ -56,3 +72,19 @@ Live migration will be aborted if it exceeds the completion timeout of 800s per ### Progress Timeout Live migration will also be aborted when copying memory doesn't make any progress in 150s. + +## Limitation + +`host-model` only allows migration of the VM to a node with same CPU model. However, specifying a CPU model is not always required. When no CPU model is specified, you must shut down the VM, assign a CPU model that is supported by all nodes, and then restart the VM. + +Example: + +- A node: `host-model-cpu.node.kubevirt.io/XYZ` `cpu-model-migration.node.kubevirt.io/XYZ` `cpu-model.node.kubevirt.io/123` +- B node: `host-model-cpu.node.kubevirt.io/ABC` `cpu-model-migration.node.kubevirt.io/ABC` `cpu-model.node.kubevirt.io/123` + +Migrating a VM with `host-model` is not possible because the values of `host-model-cpu.node.kubevirt.io` are not identical. However, both nodes support the `123` CPU model, so you can migrate any VM with the `123` CPU model using either of the following methods: + +- Cluster level: Run `kubectl edit kubevirts.kubevirt.io -n harvester-system` and add `spec.configuration.cpuModel: "123"`. This change also affects newly created VMs. +- Individual VMs: Modify the VM configuration to include `spec.template.spec.domain.cpu.model: "123"`. + +Both methods require the restarting the VMs. If you are certain that all nodes in the cluster support a specific CPU model, you can define this at the cluster level before creating any VMs. In doing so, you eliminate the need to restart the VMs (to assign the CPU model) during live migration. \ No newline at end of file diff --git a/versioned_docs/version-v1.2/install/requirements.md b/versioned_docs/version-v1.2/install/requirements.md index 822fa7096cb..c690156e2e7 100644 --- a/versioned_docs/version-v1.2/install/requirements.md +++ b/versioned_docs/version-v1.2/install/requirements.md @@ -39,6 +39,14 @@ Harvester nodes have the following hardware requirements and recommendations for - During testing, you can use only one NIC for the [built-in management cluster network](../networking/clusternetwork.md#built-in-cluster-network) (`mgmt`), and for testing the [VM network](../networking/harvester-network.md#create-a-vm-network) that is also carried by `mgmt`. High availability and optimal performance are not guaranteed. ::: +### CPU Specifications + +[Live Migration](../vm/live-migration/) functions correctly only if the CPUs of all physical servers in the [Harvester cluster](../glossary#harvester-cluster) have the same specifications. This requirement applies to all operations that rely on Live Migration functionality, such as automatic VM migration when [Maintenance Mode](../host/#node-maintenance) is enabled. + +Newer CPUs (even those from the same vendor, generation, and family) can have varying capabilities that may be exposed to VM operating systems. To ensure VM stability, Live Migration checks if the CPU capabilities are consistent, and blocks migration attempts when the source and destination are incompatible. + +When creating clusters, adding more hosts to a cluster, and replacing hosts, always use CPUs with the same specifications to prevent operational constraints. + ## Network Requirements Harvester nodes have the following network requirements for installation. diff --git a/versioned_docs/version-v1.2/vm/live-migration.md b/versioned_docs/version-v1.2/vm/live-migration.md index 51ad9f57eb6..976f839fe06 100644 --- a/versioned_docs/version-v1.2/vm/live-migration.md +++ b/versioned_docs/version-v1.2/vm/live-migration.md @@ -26,6 +26,22 @@ Live migration means moving a virtual machine to a different host without downti ::: +## How Migration Works + +Each node has multiple CPU models that are labeled with different keys. + +- Primary CPU model: `host-model-cpu.node.kubevirt.io/{cpu-model}` +- Supported CPU models: `cpu-model.node.kubevirt.io/{cpu-model}` +- Supported CPU models for migration: `cpu-model-migration.node.kubevirt.io/{cpu-model}` + +During live migration, the system checks the value of `spec.domain.cpu.model` in the VirtualMachineInstance (VMI) CR, which is derived from `spec.template.spec.domain.cpu.model` in the VirtualMachine (VM) CR. If the value of `spec.template.spec.domain.cpu.model` is not set, the system uses the default value `host-model`. + +When `host-model` is used, the process fetches the value of the primary CPU model and fills `spec.NodeSelectors` of the newly created pod with the label `cpu-model-migration.node.kubevirt.io/{cpu-model}`. + +Alternatively, you can customize the CPU model in `spec.domain.cpu.model`. For example, if the CPU model is `XYZ`, the process fills `spec.NodeSelectors` of the newly created pod with the label `cpu-model.node.kubevirt.io/XYZ`. + +However, `host-model` only allows migration of the VM to a node with same CPU model. For more information, see [Limitations](#limitation). + ## Starting a Migration 1. Go to the **Virtual Machines** page. @@ -56,3 +72,19 @@ Live migration will be aborted if it exceeds the completion timeout of 800s per ### Progress Timeout Live migration will also be aborted when copying memory doesn't make any progress in 150s. + +## Limitation + +`host-model` only allows migration of the VM to a node with same CPU model. However, specifying a CPU model is not always required. When no CPU model is specified, you must shut down the VM, assign a CPU model that is supported by all nodes, and then restart the VM. + +Example: + +- A node: `host-model-cpu.node.kubevirt.io/XYZ` `cpu-model-migration.node.kubevirt.io/XYZ` `cpu-model.node.kubevirt.io/123` +- B node: `host-model-cpu.node.kubevirt.io/ABC` `cpu-model-migration.node.kubevirt.io/ABC` `cpu-model.node.kubevirt.io/123` + +Migrating a VM with `host-model` is not possible because the values of `host-model-cpu.node.kubevirt.io` are not identical. However, both nodes support the `123` CPU model, so you can migrate any VM with the `123` CPU model using either of the following methods: + +- Cluster level: Run `kubectl edit kubevirts.kubevirt.io -n harvester-system` and add `spec.configuration.cpuModel: "123"`. This change also affects newly created VMs. +- Individual VMs: Modify the VM configuration to include `spec.template.spec.domain.cpu.model: "123"`. + +Both methods require the restarting the VMs. If you are certain that all nodes in the cluster support a specific CPU model, you can define this at the cluster level before creating any VMs. In doing so, you eliminate the need to restart the VMs (to assign the CPU model) during live migration. \ No newline at end of file diff --git a/versioned_docs/version-v1.3/install/requirements.md b/versioned_docs/version-v1.3/install/requirements.md index 4d8a298a071..ff727666eec 100644 --- a/versioned_docs/version-v1.3/install/requirements.md +++ b/versioned_docs/version-v1.3/install/requirements.md @@ -39,6 +39,14 @@ Harvester nodes have the following hardware requirements and recommendations for - During testing, you can use only one NIC for the [built-in management cluster network](../networking/clusternetwork.md#built-in-cluster-network) (`mgmt`), and for testing the [VM network](../networking/harvester-network.md#create-a-vm-network) that is also carried by `mgmt`. High availability and optimal performance are not guaranteed. ::: +### CPU Specifications + +[Live Migration](../vm/live-migration/) functions correctly only if the CPUs of all physical servers in the [Harvester cluster](../glossary#harvester-cluster) have the same specifications. This requirement applies to all operations that rely on Live Migration functionality, such as automatic VM migration when [Maintenance Mode](../host/#node-maintenance) is enabled. + +Newer CPUs (even those from the same vendor, generation, and family) can have varying capabilities that may be exposed to VM operating systems. To ensure VM stability, Live Migration checks if the CPU capabilities are consistent, and blocks migration attempts when the source and destination are incompatible. + +When creating clusters, adding more hosts to a cluster, and replacing hosts, always use CPUs with the same specifications to prevent operational constraints. + ## Network Requirements Harvester nodes have the following network requirements for installation. diff --git a/versioned_docs/version-v1.3/vm/live-migration.md b/versioned_docs/version-v1.3/vm/live-migration.md index 04598387370..00e9a5ddded 100644 --- a/versioned_docs/version-v1.3/vm/live-migration.md +++ b/versioned_docs/version-v1.3/vm/live-migration.md @@ -26,6 +26,22 @@ Live migration means moving a virtual machine to a different host without downti ::: +## How Migration Works + +Each node has multiple CPU models that are labeled with different keys. + +- Primary CPU model: `host-model-cpu.node.kubevirt.io/{cpu-model}` +- Supported CPU models: `cpu-model.node.kubevirt.io/{cpu-model}` +- Supported CPU models for migration: `cpu-model-migration.node.kubevirt.io/{cpu-model}` + +During live migration, the system checks the value of `spec.domain.cpu.model` in the VirtualMachineInstance (VMI) CR, which is derived from `spec.template.spec.domain.cpu.model` in the VirtualMachine (VM) CR. If the value of `spec.template.spec.domain.cpu.model` is not set, the system uses the default value `host-model`. + +When `host-model` is used, the process fetches the value of the primary CPU model and fills `spec.NodeSelectors` of the newly created pod with the label `cpu-model-migration.node.kubevirt.io/{cpu-model}`. + +Alternatively, you can customize the CPU model in `spec.domain.cpu.model`. For example, if the CPU model is `XYZ`, the process fills `spec.NodeSelectors` of the newly created pod with the label `cpu-model.node.kubevirt.io/XYZ`. + +However, `host-model` only allows migration of the VM to a node with same CPU model. For more information, see [Limitations](#limitation). + ## Starting a Migration 1. Go to the **Virtual Machines** page. @@ -56,3 +72,19 @@ Live migration will be aborted if it exceeds the completion timeout of 800s per ### Progress Timeout Live migration will also be aborted when copying memory doesn't make any progress in 150s. + +## Limitation + +`host-model` only allows migration of the VM to a node with same CPU model. However, specifying a CPU model is not always required. When no CPU model is specified, you must shut down the VM, assign a CPU model that is supported by all nodes, and then restart the VM. + +Example: + +- A node: `host-model-cpu.node.kubevirt.io/XYZ` `cpu-model-migration.node.kubevirt.io/XYZ` `cpu-model.node.kubevirt.io/123` +- B node: `host-model-cpu.node.kubevirt.io/ABC` `cpu-model-migration.node.kubevirt.io/ABC` `cpu-model.node.kubevirt.io/123` + +Migrating a VM with `host-model` is not possible because the values of `host-model-cpu.node.kubevirt.io` are not identical. However, both nodes support the `123` CPU model, so you can migrate any VM with the `123` CPU model using either of the following methods: + +- Cluster level: Run `kubectl edit kubevirts.kubevirt.io -n harvester-system` and add `spec.configuration.cpuModel: "123"`. This change also affects newly created VMs. +- Individual VMs: Modify the VM configuration to include `spec.template.spec.domain.cpu.model: "123"`. + +Both methods require the restarting the VMs. If you are certain that all nodes in the cluster support a specific CPU model, you can define this at the cluster level before creating any VMs. In doing so, you eliminate the need to restart the VMs (to assign the CPU model) during live migration. \ No newline at end of file