> ## Documentation Index > Fetch the complete documentation index at: https://docs.celum.io/llms.txt > Use this file to discover all available pages before exploring further. # Migrate VMs from vSphere > Move VMs from VMware vCenter into a supervisor with Forklift: turn migration on, register the vCenter, add a source, build a plan, run it cold or warm, and keep each VM's address. By the end of this page, VMs that ran in your vCenter run as KubeVirt VMs in a project on a supervisor, and you have checked that they arrived. Celum drives [Forklift](https://github.com/kubev2v/forklift) for the move: Forklift copies each VM's disks, and virt-v2v converts the guest to run on KVM unless you ask for the disks as they are. Only vSphere is a source in this release, and only through a vCenter. Celum declares every source to Forklift as a vCenter (`sdkEndpoint: vcenter`), so a standalone ESXi host cannot be a source, and Celum refuses an ESXi host's address (see [Step 3](#step-3--add-a-source)). oVirt, OpenStack, Hyper-V and OVA appear in the form as "Not in this release". ## What this changes **On the supervisor.** Turning migration on installs Forklift (`konveyor-forklift/virt-forklift`), the NetworkAttachmentDefinition CRD if it is missing, four admission policies, and one Cilium policy (`celum-forklift-v2v`) that lets Forklift reach its conversion pods inside isolated projects. The admission policies act only in namespaces labelled `k8s-gate/migration-target`; creating a plan sets that label on the plan's project namespace. Talos nodes need no change: the conversion does not need user namespaces. **In the project.** The migrated VMs and their disks, as ordinary Celum VMs of that project. **In vCenter.** Celum reads the inventory. When a plan runs, each source VM is shut down — a cold plan at its start, a warm plan at cutover — and **stays off in vCenter**. A warm plan also takes snapshots of the source VM while it copies. ## Before you start * **An onboarded supervisor** with KubeVirt, CDI, cert-manager and Flux, and a Kubernetes version that serves `admissionregistration.k8s.io/v1` MutatingAdmissionPolicy (GA in 1.36). If any of these is missing, turning migration on is refused with `409`, and the card links to the onboarding step that installs it. * **The Secret Store onboarding step**, if you register the vCenter for the platform (step 2). The credential lives in the secret store and reaches the supervisor through External Secrets. * **The cluster agent chart 1.30.462 or later** on the supervisor. The plan wizard reads the vCenter inventory through it; with an older agent it cannot list VMs. * **A registry.** Forklift's images (about 5.6 GB) are copied into the supervisor's registry when migration is turned on. * **A VDDK image**, `vddk:`, in the supervisor's registry, for warm migration, for copying disks as they are, and for the fastest copy. VDDK is VMware's Virtual Disk Development Kit, licensed by Broadcom, which you load into the registry yourself. A Celum appliance installed from a 1.314 OVA or later carries [OpenVDDK](https://github.com/openvddk/openvddk), an independent Apache-2.0 drop-in for it, as `vddk:0.7.4`, and new sources take it by default. Updating an older appliance in place does not add it. Without a VDDK, a source can still use virt-v2v over HTTPS (step 3). * **vCenter reachable over HTTPS** (`/sdk`) from the supervisor. For a warm migration, **Changed Block Tracking (CBT)** enabled on the VMs. To keep a VM's address, **VMware Tools** running in the guest, so vCenter reports the address. * **Permissions**, listed under [Permissions](#permissions). > [!NOTE] > > This page does not list the privileges the vCenter account needs. Forklift's own documentation for the vSphere provider is the reference for them. ## The shape of it **Turn migration on → register the vCenter → add a source → build a plan → run it → verify.** The first three are done once per supervisor; a plan is one wave of VMs. ## Step 1 — Turn VM migration on for the supervisor > [tab] Dashboard > > **Migrations**. While migration is off, the page shows **VM migration is off on this supervisor**, with what it installs, its prerequisites, and **VMs transferred at once** (1–200, default 20). **Enable VM migration** starts at once, without a confirmation; it reads "Copying images…" while Forklift's images are copied into the supervisor's registry. > [tab] API > > `POST /api/supervisors/{name}/migration/enable` with `{"maxVMInflight": 20}`. `GET /api/supervisors/{name}/migration/status` reports the components. > [tab] MCP > > `enable_vm_migration`, and `get_component_status` with `component=migration`. **Result:** the **Forklift** tile reads 6/6, "components up · destination ready", and the **VM migration on this supervisor** card lists every component ready. ![The Migrations page with tiles for plans, VMs migrated, sources and Forklift 6/6, the Sources tab listing two vSphere sources with verified TLS, a VDDK image and state ready, and the VM migration on this supervisor card with Re-apply and Disable buttons and every Forklift component ready](https://mintcdn.com/celum-e0119be0/6q56BAvBU9lKvSVc/images/migrations/migrations-sources.png?fit=max\&auto=format\&n=6q56BAvBU9lKvSVc\&q=85\&s=ee66b8ad2c75282cbf62d9c0c6984a8e) Migrations with Forklift running and two sources ready ## Step 2 — Register the vCenter for the platform Register a vCenter once, and every supervisor's sources (and Cluster API) can use it. Celum pins its certificate, tests the login, and keeps the user and password only in the secret store. > [tab] Dashboard > > **Settings → vCenters → Add vCenter**: Name, Address, **Load from vCenter** (reads its certificate), User, Password, CA certificate, an optional description, then **Verify and add**. A row's menu offers **Edit or rotate password**, **Load the certificate again** and **Remove**. > [tab] API > > `POST /api/vcenters` with `name`, `server`, `username`, `password`, `caPem` and `description`. `GET /api/vcenters` lists them; `PUT` and `DELETE /api/vcenters/{name}` change and remove one. > [tab] MCP > > `create_vcenter`, `register_vcenter_from_cluster_api`, `update_vcenter`, `probe_vsphere_certificate`, `list_vcenters` and `get_vcenter`. No tool removes a vCenter. ![The vCenters tab of Settings with one registered vCenter, its address, user, a pinned certificate with days left and its SHA-1 fingerprint, and the credential shown as in secret store with when the login was last tested](https://mintcdn.com/celum-e0119be0/6q56BAvBU9lKvSVc/images/migrations/settings-vcenters.png?fit=max\&auto=format\&n=6q56BAvBU9lKvSVc\&q=85\&s=93fa746f9b949158ce3cbecb7c8a68af) Settings → vCenters: the certificate is pinned and the credential is in the secret store Registering a vCenter, or rotating its password, refuses an ESXi host's address with the same message as a source does (see [Step 3](#step-3--add-a-source)). You can skip this step and type a vCenter's address and credentials straight into a source. Registering it keeps one copy of the credential, which every source then reads. ## Step 3 — Add a source A source is the vCenter that VMs are migrated from, as Forklift sees it. > [tab] Dashboard > > **Migrations → Sources → Add source**. Source type **vSphere**. For the vCenter, choose **A registered vCenter**, **This supervisor's vCenter** (the one Cluster API uses), or **Another vCenter** with its address, user, password and CA certificate. Name the source (a DNS label; plans refer to it by name) and pick the **VDDK image**, or **None — virt-v2v copies over HTTPS**. **Add source** saves it. > [tab] API > > `POST /api/supervisors/{name}/migration/providers` with `name`, `type: "vsphere"`, and one of `vcenter` (a registered one), `useSupervisorVCenter`, or `url`, `user`, `password` and `caCert`. Optional: `insecureSkipVerify`, and `vddkImage` (`"none"` for no VDDK). `GET` lists the sources, `DELETE .../providers/{provider}` removes one, `PUT .../providers/{provider}/vcenter` switches it to a registered vCenter, and `POST .../providers/{provider}/register-vcenter` registers its vCenter for the platform. > [tab] MCP > > `create_migration_source`, `list_migration_sources`, `use_vcenter_for_migration_source`, `register_vcenter_from_migration_source`, and `get_migration_source_inventory` to read its VMs, networks and datastores. No tool removes a source. ![The Add source drawer with vSphere selected, the choice between a registered vCenter, this supervisor's vCenter and another vCenter, the source name, the registered vCenter with its pinned certificate, and the VDDK image](https://mintcdn.com/celum-e0119be0/6q56BAvBU9lKvSVc/images/migrations/add-source.png?fit=max\&auto=format\&n=6q56BAvBU9lKvSVc\&q=85\&s=9fa916d4ce59401240bec9511893e9a5) Add source, taking the vCenter registered in Settings Celum tests the login before it saves the source, and it refuses three sources that would only fail later, during a run: * **An ESXi host.** Celum asks the address what it is before it sends the password, and refuses an ESXi host with "`` is an ESXi host, not a vCenter — give the address of the vCenter that manages it". It makes this check also when **Skip TLS verification** is on. * **No CA and no `insecureSkipVerify`.** TLS is verified, so the source needs the CA the vCenter's certificate chains to. * **No VDDK and TLS still verified.** Without VDDK, virt-v2v copies the disks with curl, which ignores the CA, and the run would fail at conversion with `curl error 60`. Use a VDDK image, or accept `insecureSkipVerify`. **Result:** the source's row shows TLS **verified** and state **ready**. **New plan** stays disabled until at least one source is ready. > [!WARNING] > > **Changing a source makes Forklift read its whole vCenter inventory again.** A run copying from that source at that moment can fail. Change a source between runs, not during one. ## Step 4 — Build a plan A plan names the VMs to move, the source, the project they land in, and how their networks, addresses and disks map. It holds at most 500 VMs. > [tab] Dashboard > > **Migrations → Plans → New plan**, or **Workloads → New workload → Import from another platform**. The wizard has seven steps: **Source & target**, **VMs**, **Networks**, **Addresses**, **Storage**, **Migration type**, **Review**. > [tab] API > > `POST /api/supervisors/{name}/migration/plans` with `name`, `source`, `targetNamespace`, `vms`, `networks` and `storage`. Optional: `description`, `type` (`cold`, the default, or `warm`), `conversion` (`full`, the default, `raw-virtio` or `raw-compatibility`), `convertorNode`, `targetPowerState` (`on`, `off`, or empty for the source VM's state), `preserveStaticIPs`, `identityNetwork`, `addresses`, and `start` to start it as soon as it is ready. `GET /api/supervisors/{name}/migration/landing?namespace=` reads what the project offers. > [tab] MCP > > `create_migration_plan`, with `get_migration_source_inventory` and `get_migration_landing` to fill it in. **Source & target.** The source, the **Target project**, a **Plan name** (a DNS label of at most 55 characters, such as `erp-wave-3`), and an optional description. The project's namespace is where the VMs land; they become that project's VMs. **VMs.** The source's VMs, with their power state, OS, size and **Concerns**. vSphere Cluster Services (vCLS) agent VMs are not listed. The wizard will not go on with a VM whose name or MAC address is already in use on the supervisor, a VM with a critical concern, or a VM with more than one NIC on the pod network; in a warm plan, also a VM without CBT or with shared disks. vSAN needs VDDK. ![The VMs step of New migration plan, searching the source's 212 VMs, with one Ubuntu VM chosen, its power state, size and number of concerns](https://mintcdn.com/celum-e0119be0/6q56BAvBU9lKvSVc/images/migrations/plan-vms.png?fit=max\&auto=format\&n=6q56BAvBU9lKvSVc\&q=85\&s=ab31e97441dd1f08cbc8eeeaf60ad4a7) VMs: pick the ones this wave moves **Networks.** Each vCenter network the chosen VMs use goes to the **Pod network** or is ignored; a NIC on an ignored network is dropped. The pod network is masquerade, as for every Celum VM: the guest takes its address by DHCP. Mapping a network to a VLAN of its own is not offered yet. **Addresses.** A VM can keep the address VMware Tools reports for it, inside a subnet declared adoptable: it becomes the VM's identity address, a routed /32 that follows it through live migration. The address is claimed only once that VM's migration has succeeded. The other VMs get the pod address only, or an address from the project's pool. Keeping addresses needs `cilium:Apply`, a NIC on the pod network, and cannot be combined with **Preserve static IPs**. Hosts still on the source subnet reach a kept address only once that subnet is extended (see [Reach moved VMs from the source network](#reach-moved-vms-from-the-source-network)), or once its gateway answers ARP for it. ![The Addresses step with a VM, the address VMware Tools reports, Keep that address chosen as its address here, and the other VMs getting the pod address only](https://mintcdn.com/celum-e0119be0/6q56BAvBU9lKvSVc/images/migrations/plan-addresses.png?fit=max\&auto=format\&n=6q56BAvBU9lKvSVc\&q=85\&s=ed623a74f6e2bfeb8cc1d2272afee42e) Addresses: keep the address the guest had **Storage.** Each datastore maps to a StorageClass. A VM keeps live migration between the supervisor's nodes only on a class whose volumes are ReadWriteMany. **Migration type.** | Choice | What it does | | - | - | | **Cold** | Each VM is shut down, copied, converted and started here. It is down for the whole copy. | | **Warm** | Copied while it runs, then the changed blocks again until cutover. It is down only for the last delta and the conversion. Needs VDDK and CBT. | | **Convert** (default) | virt-v2v installs virtio drivers and the guest agent and removes VMware Tools. Most of a warm cutover's downtime. | | **Copy as is · virtio** | Disks copied unchanged, with a virtio disk and NIC. Boots only a guest that already has virtio drivers; no guest agent. Needs VDDK. | | **Copy as is · compatibility** | Disks copied unchanged, with a SATA disk and an e1000e NIC, which most guests have drivers for. Slow disk and network; no guest agent. Needs VDDK. | | **Conversion runs on** | The node that copies and converts each disk: the one with the faster path to the ESXi hosts, if one has it. It must run KubeVirt VMs, not be cordoned, and have no NoSchedule or NoExecute taint. | | **Power state after migration** | As before, On, or Off. | ![The Migration type step with Cold and Warm, the guest conversion choices Convert, Copy as is virtio and Copy as is compatibility, the node conversion runs on, and the power state after migration](https://mintcdn.com/celum-e0119be0/6q56BAvBU9lKvSVc/images/migrations/plan-migration-type.png?fit=max\&auto=format\&n=6q56BAvBU9lKvSVc\&q=85\&s=8d269bd8c62c2c028f62434cef505762) Migration type: cold or warm, and whether the guest is converted **Review.** The plan as it will be created, and what it does to the source: each VM is shut down in vCenter before its disks are copied and stays off there. **Create plan** creates it; **Create and start** also starts it as soon as Forklift has validated it (with VDDK that includes a check job, which can take a minute). Neither asks again. ![The Review step listing the plan's name, source, project, type, guest conversion, VMs, networks, addresses and datastores, a warning that the source VMs will be shut down, and the buttons Create plan and Create and start](https://mintcdn.com/celum-e0119be0/6q56BAvBU9lKvSVc/images/migrations/plan-review.png?fit=max\&auto=format\&n=6q56BAvBU9lKvSVc\&q=85\&s=6fb326b31b59492fd0da406bb6d094e2) Review, with the warning about the source VMs ## Step 5 — Run it > [tab] Dashboard > > The plan's page, from **Migrations → Plans**. **Start** (or **Retry**) runs it. A warm plan adds **Cut over now**, and **Schedule cutover…** in the overflow menu. **Cancel the run** stops it. Each of these asks for confirmation, except scheduling a cutover. > [tab] API > > `POST /api/supervisors/{name}/migration/plans/{plan}/start`, `.../cutover` with an optional `{"at": ""}`, `.../cancel` with an optional `{"vms": [...]}`. Cancelling single VMs is API only; the dashboard cancels the whole run. `GET .../plans/{plan}` reads the plan, its runs and each VM's progress. > [tab] MCP > > `start_migration_plan`, `cutover_migration_plan`, `get_migration_plan` and `list_migration_plans`. No tool cancels a run. The plan's page follows each VM through Forklift's steps — Initialize, DiskTransfer, Cutover, ImageConversion, VirtualMachineCreation — with when each started and how long it took. A warm VM lists its precopies; a converted VM lists virt-v2v's own phases. The page refreshes every 5 seconds while a run is going. ![A plan's page for a succeeded warm migration: VMs migrated 1 of 1, none failed, disks copied 100%, and the VM's steps Initialize, DiskTransfer, Cutover, ImageConversion with virt-v2v and virt-customize phases, VirtualMachineCreation and the final snapshot consolidation, each marked done with its duration, then two precopies and the cutover-to-done and whole-run times](https://mintcdn.com/celum-e0119be0/6q56BAvBU9lKvSVc/images/migrations/plan-run.png?fit=max\&auto=format\&n=6q56BAvBU9lKvSVc\&q=85\&s=1d42f84101f8cfaf3f8b03b7bc19a901) A finished warm migration: every step with its duration, the precopies, and the whole run > [!NOTE] > > **Progress counts each disk's full size.** VDDK reads only the blocks a disk has allocated, so the bytes actually moved, and the copy's rate, are not shown, and the time left on a sparse disk can be well off. For orientation, on Celum's own test bed: a copy with VDDK ran at about 150 MiB/s, and a warm cutover that kept the VM's address took the VM away for about 2 minutes for Ubuntu and 6–7 minutes for Windows. A plan is **validating**, **needs attention**, **ready**, **running**, **succeeded**, **failed**, **canceled** or **archived**. **Mappings** shows where each network and datastore went, and each VM's identity address with its state. ![The Mappings tab of a plan: a vCenter network mapped to the pod network, a datastore mapped to a StorageClass, and the VM with keeps its source address, its address and state done](https://mintcdn.com/celum-e0119be0/6q56BAvBU9lKvSVc/images/migrations/plan-mappings.png?fit=max\&auto=format\&n=6q56BAvBU9lKvSVc\&q=85\&s=d22f0f49be582d816c2b2004492ffae1) Mappings: networks, datastores, and the address each VM kept ## Reach moved VMs from the source network A VM that kept its address has left its source subnet. Hosts that stay behind in that subnet reach it again only when the subnet is **extended**: an ARP-proxy appliance, a small VM on the source VLAN, answers for exactly the addresses that moved and hands their traffic to the subnet's own gateway, which routes each one to the supervisor. Nothing on the fabric changes. It bridges a migration in progress: move the whole subnet as soon as you can, retire the source environment, then remove the hybrid subnet. > [tab] Dashboard > > **Migrations → Network extension**. **Mapping** lists the vCenter networks, the subnets their guests report, and how many hosts are still at the source. **ARP-proxy appliances** has **Declare hybrid subnet** and **Deploy ARP-proxy appliance**. > [tab] API > > `GET`, `POST /api/supervisors/{name}/networking/hybrid-subnets`, and `PUT`, `DELETE .../hybrid-subnets/{subnet}`. `PUT .../networking/vm-identity-adoptable` declares which subnets' addresses may be kept. > [tab] MCP > > `list_hybrid_subnets`, `create_hybrid_subnet`, `update_hybrid_subnet`, `remove_hybrid_subnet`, `deploy_hybrid_subnet_appliance`, `get_hybrid_subnet_appliance_deployment`, `list_hybrid_subnet_appliances`, `rotate_hybrid_subnet_appliance_token`, `set_vm_identity_adoptable`. ![The Mapping view of Network extension with counts of vCenter networks with VMs, networks whose addresses are kept, addresses adopted by migrated VMs, and kept networks that are extended](https://mintcdn.com/celum-e0119be0/6q56BAvBU9lKvSVc/images/migrations/network-extension.png?fit=max\&auto=format\&n=6q56BAvBU9lKvSVc\&q=85\&s=3753a6035f6115dfc48c573a20102bbf) Network extension → Mapping: how many networks keep their addresses, and how many are extended ![The ARP-proxy appliances view with one hybrid subnet, its gateway and port group, one of one appliances answering, and three of three migrated addresses answered](https://mintcdn.com/celum-e0119be0/6q56BAvBU9lKvSVc/images/migrations/arp-proxy.png?fit=max\&auto=format\&n=6q56BAvBU9lKvSVc\&q=85\&s=db4d0464344f2807c41f866d5d7f068d) ARP-proxy appliances: a hybrid subnet answering for every migrated address ## Verify * The plan reads **succeeded**, and **VMs migrated** counts every VM of the latest run. * Each VM is in **Workloads**, in the plan's project, running (unless you chose Off). * A converted VM shows its guest agent connected. A copied-as-is VM has no guest agent, by design. * A VM that kept its address shows it on **Mappings** as **done**, and answers on it. From a host left in the source subnet, it answers only once that subnet is extended. ## If you need to undo it There is no reverse migration. The source VM is still in vCenter, powered off: power it back on there to return to it. * **Cancel the run** powers back on the VMs Forklift shut down, removes a warm plan's snapshot, and removes what the run had built on the supervisor. * **Retry** runs again only the VMs that did not get across. A plan that succeeded cannot be run again. * **Archive** cleans up what failed and canceled VMs left behind. * **Delete** removes the plan. It never touches the VMs that migrated. * **Disable** on the **VM migration on this supervisor** card removes Forklift's sources, their credentials and the plans, and leaves the CRDs. It is refused with `409` while a run is going; **Disable anyway…** overrides that. It never touches migrated VMs. Removing a source, cancelling, archiving or deleting a plan, disabling migration and removing a vCenter have no MCP tool: they are left to a person on purpose. Use the dashboard or the API. ## What commonly goes wrong | Symptom | Cause | | - | - | | **Enable VM migration** answers `409` | A prerequisite is missing on the supervisor; the message names it, and the card links to its onboarding step. | | **New plan** is greyed out | No source is ready yet. | | A source is refused with "no CA for …" | Paste the CA the vCenter's certificate chains to, use a registered vCenter, or accept `insecureSkipVerify`. | | A source without VDDK is refused with `curl error 60` | Without VDDK the copy ignores the CA. Use a VDDK image, or accept `insecureSkipVerify`. | | The wizard lists no VMs | The cluster agent on the supervisor is older than chart 1.30.462. | | The wizard will not let a VM through | Its name or MAC is already used on the supervisor, it has a critical concern, it has more than one NIC on the pod network, or (warm) it has no CBT or has shared disks. | | A run stops at ImageConversion with 0% | The conversion pod in an isolated project is unreachable: the `celum-forklift-v2v` policy is missing. **Re-apply** on the migration card restores it, and every **Start** applies it again. | | A run failed while a source was being changed | Changing a source re-reads its inventory. Change sources between runs, then **Retry**. | | A Windows guest does not boot after **Copy as is** | A stock Windows guest has no virtio drivers, and one installed on PVSCSI may not boot from SATA either. Use **Convert**. | | A converted Windows VM takes minutes longer to come up | Services set to Automatic (Delayed Start) add about two minutes to its first boot. | | **Disable** answers `409` | A run is going. Let it finish or cancel it, or use **Disable anyway…**. | ## Permissions | Task | Action | KRN | | - | - | - | | Read migration's state | `migration:GetStatus` | `krn:celum:supervisor::migration:*` | | Turn migration on / off | `migration:Enable`, `migration:Disable` | same | | List, add, change, remove sources | `migration:ListProviders`, `migration:CreateProvider`, `migration:UpdateProvider`, `migration:DeleteProvider` | same | | Read a source's inventory | `migration:ReadInventory` | same | | List and create plans | `migration:ListPlans`, `migration:CreatePlan` | same | | Read, start, cut over, cancel, archive, delete a plan | `migration:GetPlan`, `migration:StartPlan`, `migration:CutoverPlan`, `migration:CancelPlan`, `migration:ArchivePlan`, `migration:DeletePlan` | `krn:celum:supervisor::migration:` | | Use a registered vCenter in a source | `vcenter:Use` | `krn:celum:vcenter:` | | Register and manage vCenters | `vcenter:List`, `vcenter:Create`, `vcenter:Get`, `vcenter:Update`, `vcenter:Delete` | `krn:celum:vcenter:*` or `krn:celum:vcenter:` | Three checks happen inside a request rather than on its route: **Create and start** also needs `migration:StartPlan`; keeping addresses needs `cilium:Apply`; and **Load from vCenter** needs `capi:Install`. ## Next > [card] [VM lifecycle](https://docs.celum.io/vms/lifecycle.md) > > Start, stop, resize and live-migrate the VMs you just moved. > [card] [VM identity pools](https://docs.celum.io/networking/vm-identity-pools.md) > > The addresses migrated VMs keep, and how they follow a VM. > [card] [VM networking](https://docs.celum.io/vms/networking.md) > > Publish a migrated VM's ports through a LoadBalancer or a Gateway. > [card] [Create a project](https://docs.celum.io/get-started/create-a-project.md) > > The project a plan's VMs land in. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.