Nowa wersja hv2pve — 1.0.3

W starszych wersjach hv2pve migracja wymagała wyłączenia maszyny wirtualnej po stronie Hyper-V przed rozpoczęciem procesu. Efekt? Każda migracja wiązała się z przestojem systemu, co utrudniało pracę w środowiskach produkcyjnych. Długość przestoju była związana z wielkością dysków maszyny wirtualnej.

Największa nowość w obecnej wersji

Dzięki technologii AVHDX Migrate Chain (hd2raw) możliwa jest migracja maszyny wirtualnej bez jej wyłączania, co znacząco ogranicza przestój usług. Cały proces odbywa się w trybie online, a finalna synchronizacja ostatniego snapshotu oraz uruchomienie systemu po stronie docelowej zajmuje w testach od kilkunastu do kilkudziesięciu sekund — w zależności od aktualnego obciążenia VM. Narzędzie hd2raw umożliwia bezpośrednią synchronizację plików AVHDX do formatu raw oraz ich strumieniowanie prosto na dysk w środowisku Proxmox. Dzięki temu nie ma już potrzeby wcześniejszego scalania łańcucha AVHDX po stronie Windows, co upraszcza cały proces migracji i skraca czas operacji.

Jak to wygląda bez naszego narzędzia

W scenariuszu bez wykorzystania naszego narzędzia proces migracji z Hyper-V do Proxmox jest w całości realizowany manualnie. Administrator musi najpierw wyeksportować dyski VHDX/AVHDX oraz scalić łańcuch snapshotów po stronie Hyper-V. Następnie wymagane jest ich przekonwertowanie do formatu obsługiwanego przez Proxmox — najczęściej raw lub qcow2. Kolejnym krokiem jest ręczne utworzenie maszyny wirtualnej w środowisku Proxmox, podpięcie przekonwertowanych dysków oraz odtworzenie konfiguracji sprzętowej (CPU, RAM, sieć, kontrolery).

Każdy z tych etapów to osobna operacja wymagająca uwagi i czasu, a wraz ze wzrostem liczby migrowanych maszyn wirtualnych rośnie również ryzyko błędów konfiguracyjnych. Co istotne, przestój obejmuje cały czas potrzebny na kopiowanie oraz konwersję danych, co w praktyce może oznaczać wielogodzinny downtime przy większych wolumenach dyskowych.

Jak to działa pod spodem (w skrócie)

Proces migracji został zaprojektowany tak, aby był przewidywalny, powtarzalny i bezpieczny — szczególnie w trybie AVHDX Migrate Chain (AMC). Poniżej uproszczony opis działania z zachowaniem kluczowego założenia: pracujemy na dokładnie trzech snapshotach.

Migracja rozpoczyna się od inwentaryzacji po stronie Hyper-V. Weryfikowane jest, czy maszyna spełnia warunki migracji oraz czy jej stan odpowiada wybranemu trybowi. W trybie standardowym VM musi być wyłączona, natomiast w trybie AMC (AVHDX Migrate Chain) może pozostawać uruchomiona. Sprawdzana jest również dostępność przestrzeni na storage w Proxmox oraz to, czy maszyna o danym ID nie była wcześniej migrowana. Pozwala to uniknąć prostych błędów migracji.

Po stronie Proxmox VE tworzona jest kompletna definicja maszyny wirtualnej, dyski oraz ich poprawne podpięcie do konfiguracji. Następnie maszyna jest uruchamiana i od razu wstrzymywana, co pozwala maksymalnie skrócić późniejszy downtime podczas właściwego przełączenia. To przygotowanie jest kluczowe, ponieważ właściwy import odbywa się już na gotowej strukturze. Na tym etapie nadawany jest także tag init, który umożliwia bezpieczne wznowienie procesu w przypadku jego przerwania (np. błędy sieciowe itp.).

W trybie AMC (AVHDX Migrate Chain) właściwa migracja przebiega w trzech etapach snapshotowych:

Snapshot 1 — po jego utworzeniu rozpoczyna się migracja bazowego pliku VHDX/VHD. Snapshot przechwytuje wszystkie zmiany powstające w trakcie kopiowania dużego dysku bazowego, dzięki czemu maszyna może normalnie pracować.

Snapshot 2 — tworzony po zakończeniu transferu bazy. Obejmuje zmiany wygenerowane w czasie migracji pierwszej warstwy. Następnie migrowany jest pierwszy plik różnicowy i wykonywany jest jego merge zarówno po stronie Hyper-V (mechanizmem natywnym), jak i po stronie Proxmox przy użyciu hd2raw.

Dopiero po zmigrowaniu i scaleniu drugiego snapshotu rozpoczyna się proces wyłączania maszyny wirtualnej. Migrator wydaje wówczas na hoście Microsoft Hyper-V polecenie PowerShell:

Stop-VM -VMName {vmid}

Jest to moment przejścia w krótką fazę kontrolowanego downtime’u.

Snapshot 3 — tworzony tuż przed wyłączeniem VM, obejmuje ostatnie zmiany systemu. Już na wyłączonej maszynie migrowany jest trzeci plik różnicowy, po czym wykonywany jest jego merge po obu stronach — zarówno w Hyper-V, jak i w Proxmox. Następnie maszyna uruchamiana jest już w środowisku docelowym.

Takie podejście powoduje, że większość danych przenoszona jest przy działającej VM, a przestój ogranicza się wyłącznie do migracji i scalenia trzeciego snapshotu oraz restartu systemu. Jednocześnie integralność danych po stronie Hyper-V pozostaje zachowana, co umożliwia szybki powrót do środowiska źródłowego w razie potrzeby.

Na zakończenie maszyna oznaczana jest tagiem imported, co jednoznacznie potwierdza poprawne zakończenie procesu i zapobiega jej ponownemu zakwalifikowaniu przez migrator hv2pve.

Jaki zysk daje użycie AVHDX Migrate Chain?

Największą korzyścią z zastosowania AVHDX Migrate Chain (AMC) jest radykalne skrócenie odczuwalnego downtime’u oraz lepsza kontrola nad czasem migracji.

Na przykładzie maszyny wirtualnej o rozmiarze 100 GB różnica jest wyraźna.

Bez AVHDX Migrate Chain — cały proces odbywa się w trybie klasycznym, co oznacza konieczność wyłączenia VM na czas kopiowania i konwersji pełnego dysku. W efekcie przestój trwa praktycznie przez cały czas transferu danych:

Migracja zajmuje kilkanaście–kilkadziesiąt minut, a downtime obejmuje niemal cały ten okres.

Z AVHDX Migrate Chain — większość danych (bazowy dysk oraz dwa pierwsze snapshoty) przenoszona jest przy działającej maszynie. Wyłączenie VM następuje dopiero przed migracją trzeciego, finalnego snapshotu. Sama synchronizacja ostatnich zmian oraz uruchomienie systemu w środowisku Proxmox trwa zwykle kilkadziesiąt sekund (w zależności od obciążenia workloadu):

Choć całkowity czas operacji może być zbliżony lub nawet dłuższy, kluczowa różnica polega na tym, że przestój ograniczony jest wyłącznie do finalnej fazy końcowej synchronizacji.

Na wykresach w Grafana wyraźnie widać skrócony czas niedostępności usługi przy wykorzystaniu AVHDX Migrate Chain — obciążenie systemu jest rozłożone w czasie, a użytkownicy końcowi odczuwają jedynie krótki, kontrolowany restart zamiast długiej przerwy serwisowej.

Jak to testowaliśmy

Proces testowania migratora hv2pve został zaprojektowany tak, aby weryfikować nie tylko poprawność samej operacji, ale przede wszystkim integralność danych po migracji.

W kodzie narzędzia zaimplementowaliśmy dodatkowy moduł odpowiedzialny za generowanie plików kontrolnych wraz z logowaną w rejestrze sumą kontrolną (sha1sum). Po zakończeniu migracji wyliczone wartości były porównywane z sumami kontrolnymi plików znajdujących się już w docelowej lokalizacji. Takie podejście pozwalało jednoznacznie potwierdzić, że dane zostały przeniesione w sposób kompletny i nie uległy uszkodzeniu w trakcie transferu ani procesu synchronizacji snapshotów.

Całość procesu testowego została w pełni zautomatyzowana przy użyciu Jenkins. Pipeline’y uruchamiały różne scenariusze migracyjne — zarówno w trybie standardowym, jak i w trybie AVHDX Migrate Chain (AMC) — co pozwalało na wielokrotne, powtarzalne i deterministyczne sprawdzenie poprawności działania narzędzia. Dzięki temu mogliśmy w kontrolowany sposób weryfikować zarówno typowe scenariusze migracji, jak i sytuacje brzegowe, upewniając się, że hv2pve i hd2raw działają poprawnie i bezpiecznie.

Co robić, gdy migracja zostanie przerwana

Podczas migracji maszyny wirtualnej do Proxmox VE mogą wystąpić sytuacje, w których proces nie zakończy się poprawnie. Najczęściej dotyczą one statusu maszyny po stronie docelowej oraz snapshotów tworzonych w trakcie migracji.

Jeżeli migracja zostanie przerwana po zainicjalizowaniu wszystkich dysków, maszyna po stronie Proxmox otrzyma status init. Oznacza to, że struktura VM została utworzona prawidłowo i wszystkie dyski istnieją. W takiej sytuacji migrację można bezpiecznie ponowić.

Jeżeli jednak proces zakończy się przed pełną inicjalizacją dysków, migrator nie nada tagu init, a maszyna zostanie oznaczona jako corrupted. Taki status blokuje kolejną próbę migracji. W praktyce oznacza to konieczność ręcznego usunięcia tej maszyny wirtualnej po stronie Proxmox wraz z jej dyskami, a następnie rozpoczęcia migracji od nowa.

Osobnym przypadkiem jest sytuacja, w której podczas migracji tworzone są snapshoty i proces zostanie przerwany już po ich utworzeniu. W takim scenariuszu pozostają one w środowisku i blokują ponowną migrację — VM otrzymuje status snapshot. Na ten moment ich usunięcie lub „posprzątanie” pozostaje po stronie użytkownika. Dopiero po ręcznym usunięciu snapshotów możliwe jest ponowne uruchomienie migracji.

Następne kroki

Rozwój migratora koncentruje się obecnie na zwiększeniu odporności na błędy. Kluczowym celem jest ograniczenie sytuacji, w których administrator musi ręcznie sprzątać środowisko po przerwanej migracji.

Planowane jest usprawnienie obsługi wyjątków oraz wprowadzenie mechanizmów automatycznego czyszczenia snapshotów po stronie Microsoft Hyper-V — zarówno w trakcie migracji (jeśli pozwoli na to stan procesu), jak i przy jej ponownym uruchomieniu. Dzięki temu środowisko źródłowe ma pozostawać w spójnym stanie nawet po nieudanej próbie importu.

Równolegle pracujemy nad możliwością wznawiania importu po błędzie bez konieczności ręcznego usuwania maszyny po stronie Proxmox VE. Uzupełnieniem tego będzie automatyczne czyszczenie VM oraz zasobów storage po nieudanym imporcie.

W roadmapie znajdują się również:

• refaktoryzacja projektu oraz wydzielenie dedykowanej warstwy Service Layer
• dynamiczna ilość checkpointów przy migracji AMC
• automatyczny dobór odpowiedniego datastore dla VM w Proxmox
• migracja urządzeń blokowych oraz iSCSI
• migracja klastra Microsoft Hyper-V do klastra PVE z automatycznym rozmieszczeniem maszyn wirtualnych
• wsparcie migracji wielu maszyn równolegle
• transfer dysków przez NFS oraz SSH
• generyczne wsparcie EFI
• web GUI do zarządzania migracjami (monitorowanie postępu, konfiguracja, obsługa błędów)

Tutorial: Jak przeprowadzić migrację VM

Repozytorium hv2pve

Pierwszym krokiem jest przygotowanie środowiska po stronie Hyper-V oraz źródłowej maszyny wirtualnej. Należy uruchomić odpowiedni skrypt z katalogu prep_script, który przygotowuje VM do migracji. Jeśli planujesz użycie trybu AVHDX Migrate Chain (AMC), w trakcie konfiguracji środowiska ustaw zmienną HYPERV_CREATE_CHECKPOINT (szczegóły w sekcji o pliku env.json).

Następnie wybierz tryb importu maszyny wirtualnej. Domyślnie program zgłosi skip ze względu na CheckVMState — VM musi być wyłączona. Aby skorzystać z trybu AVHDX Migrate Chain, konieczne jest włączenie modułu nbd po stronie Proxmox oraz pobranie osobnej binarki hd2raw, umożliwiającej synchronizację plików AVHDX do formatu raw.

1. Utwórz wirtualne środowisko (venv): python3 -m venv ./venv
2. Aktywuj wirtualne środowisko: source ./venv/bin/activate
3. Zainstaluj zależności: pip install -r req.txt
4. Skonfiguruj połączenie z Hyper-V/Proxmox w pliku env.json. Aby użyć trybu AVHDX Migrate Chain, ustaw HYPERV_CREATE_CHECKPOINT na true: { "HYPERV_IP": "a.b.c.d", "HYPERV_USER": "administrator", "HYPERV_PASS": "changeme", "HYPERV_CREATE_CHECKPOINT": true, ... }
5. Uruchom weryfikację początkową: make dryrun
6. Rozpocznij migrację: make run
7. Uruchom migrację w trybie debug (opcjonalnie): make debug