From a4b063905026895c256e5547c595de37a27f2fc2 Mon Sep 17 00:00:00 2001 From: "ohotnikov.ivan" Date: Wed, 4 Feb 2026 23:18:02 +0300 Subject: [PATCH] docs(virtualization): add Proxmox migration guide Add comprehensive guide for migrating virtual machines from Proxmox VE to Cozystack. The guide covers disk export, image upload via virtctl, and VM deployment with troubleshooting section. Signed-off-by: ohotnikov.ivan --- .../docs/virtualization/proxmox-migration.md | 212 ++++++++++++++++++ 1 file changed, 212 insertions(+) create mode 100644 content/en/docs/virtualization/proxmox-migration.md diff --git a/content/en/docs/virtualization/proxmox-migration.md b/content/en/docs/virtualization/proxmox-migration.md new file mode 100644 index 00000000..7673663a --- /dev/null +++ b/content/en/docs/virtualization/proxmox-migration.md @@ -0,0 +1,212 @@ +--- +title: "Migrating Virtual Machines from Proxmox" +linkTitle: "Proxmox Migration" +description: "Step-by-step guide to migrating virtual machines from Proxmox VE to Cozystack" +weight: 65 +--- + +This guide describes the process of migrating virtual machines from Proxmox VE to Cozystack by exporting VM disk images and uploading them to the target environment. + +{{< note >}} +Migration is performed by exporting VM disks to files and uploading them to Cozystack. +VM state and snapshots are not preserved during migration. +{{< /note >}} + +## Prerequisites + +Before starting the migration, ensure you have: + +1. **KubeVirt client `virtctl`** installed on your local machine: + - Installation guide: [KubeVirt User Guide - Virtctl Client Tool](https://kubevirt.io/user-guide/user_workloads/virtctl_client_tool/) + +2. **Upload proxy access configured** in your Cozystack cluster: + - Modify your Cozystack ConfigMap to enable `cdi-uploadproxy`: + ```bash + kubectl patch cm -n cozy-system cozystack --type merge -p='{"data":{ + "expose-services": "dashboard,cdi-uploadproxy" + }}' + ``` + - Configure the CDI upload proxy endpoint in your Cozystack values: + ```yaml + values-cdi: | + uploadProxyURL: https://cdi-uploadproxy.example.org + ``` + +3. **DNS or hosts file configuration** for upload proxy access: + - If needed, add an entry to `/etc/hosts` on your local machine: + ``` + cdi-uploadproxy.example.org + ``` + +## Step 1: Export VM Disks from Proxmox + +Before exporting, ensure the virtual machines are stopped in Proxmox. + +Export the VM disk to a file in qcow2 format (or another format supported by KubeVirt): + +```bash +# Example: Export VM disk from Proxmox storage +qm disk export /tmp/vm-disk.qcow2 +``` + +The output should be a disk image file (e.g., `vm-disk.qcow2`) ready for upload. + +{{< note >}} +Specific commands for exporting disks may vary depending on your Proxmox storage backend and configuration. +Refer to [Proxmox VE documentation](https://pve.proxmox.com/wiki/Qm_status) for details. +{{< /note >}} + +## Step 2: Create a VMDisk for Upload + +Create a `VMDisk` resource in Cozystack with `source.upload` to prepare for image upload: + +```yaml +apiVersion: apps.cozystack.io/v1alpha1 +kind: VMDisk +metadata: + name: proxmox-vm-disk + namespace: tenant-root +spec: + source: + upload: {} + storage: 10Gi + storageClass: replicated +``` + +Apply the manifest: + +```bash +kubectl apply -f vmdisk-upload.yaml +``` + +Monitor the disk creation status: + +```bash +kubectl get vmdisk -n tenant-root +kubectl describe vmdisk proxmox-vm-disk -n tenant-root +``` + +## Step 3: Upload the Disk Image + +Once the VMDisk is created and ready for upload, use `virtctl` to upload the disk image: + +```bash +virtctl image-upload dv vm-disk-proxmox-vm-disk \ + -n tenant-root \ + --image-path=./vm-disk.qcow2 \ + --uploadproxy-url https://cdi-uploadproxy.example.org \ + --insecure +``` + +{{< note >}} +The DataVolume name follows the pattern `vm-disk-`. +If your VMDisk is named `proxmox-vm-disk`, the DataVolume will be `vm-disk-proxmox-vm-disk`. +{{< /note >}} + +Wait for the upload to complete. You can monitor the progress: + +```bash +kubectl get dv -n tenant-root +kubectl describe dv vm-disk-proxmox-vm-disk -n tenant-root +``` + +The upload is complete when the status shows `Succeeded`. + +## Step 4: Create a VMInstance + +After the disk upload is complete, create a VMInstance to boot from the uploaded disk: + +```yaml +apiVersion: apps.cozystack.io/v1alpha1 +kind: VMInstance +metadata: + name: migrated-vm + namespace: tenant-root +spec: + running: true + instanceType: u1.medium + disks: + - name: proxmox-vm-disk + # Optional: configure network, cloud-init, etc. +``` + +Apply the manifest: + +```bash +kubectl apply -f vminstance.yaml +``` + +Verify the VM is running: + +```bash +kubectl get vm -n tenant-root +kubectl get vmi -n tenant-root +``` + +## Step 5: Access the Migrated VM + +Access the VM console using virtctl: + +```bash +# Serial console +virtctl console vm-instance-migrated-vm -n tenant-root + +# VNC access +virtctl vnc vm-instance-migrated-vm -n tenant-root + +# SSH (if configured) +virtctl ssh user@vm-instance-migrated-vm -n tenant-root +``` + +## Migration Checklist + +Use this checklist to track your migration progress: + +- [ ] Export VM disks from Proxmox (qcow2 or compatible format) +- [ ] Install `virtctl` on your local machine +- [ ] Configure upload proxy access in Cozystack +- [ ] Add DNS/hosts entry for upload proxy (if needed) +- [ ] Create VMDisk with `source.upload` in Cozystack +- [ ] Upload disk image using `virtctl image-upload` +- [ ] Wait for upload to complete (status: Succeeded) +- [ ] Create VMInstance with the uploaded disk +- [ ] Verify VM boots successfully +- [ ] Test VM connectivity and functionality + +## Troubleshooting + +### Upload Fails with Connection Error + +**Problem:** `virtctl image-upload` fails with connection refused or timeout. + +**Solution:** +- Verify upload proxy is accessible: `curl -k https://cdi-uploadproxy.example.org` +- Check `/etc/hosts` entry matches the upload proxy IP +- Ensure Cozystack ConfigMap has `expose-services: "dashboard,cdi-uploadproxy"` + +### Upload Stuck at 0% + +**Problem:** Upload starts but never progresses. + +**Solution:** +- Check DataVolume status: `kubectl describe dv vm-disk- -n tenant-root` +- Verify storage class has available capacity +- Check CDI pod logs: `kubectl logs -n cozy-system -l app=cdi-uploadproxy` + +### VM Fails to Boot After Migration + +**Problem:** VM boots but fails to start properly. + +**Solution:** +- Check VM disk is attached as the first disk in VMInstance spec +- Verify disk format is compatible (qcow2, raw) +- Review VM logs: `virtctl console vm-instance- -n tenant-root` +- Ensure VM drivers are compatible with KubeVirt (VirtIO recommended) + +## Next Steps + +After successful migration: + +- Configure [cloud-init]({{% ref "/docs/virtualization/virtual-machine" %}}) for automated VM setup +- Review [instance types and profiles]({{% ref "/docs/virtualization/resources" %}}) for optimal resource allocation +- Consider creating [golden images]({{% ref "/docs/virtualization/vm-image" %}}) for future VM deployments