hyper2kvm

Migration Guides

Comprehensive migration workflows, playbooks, and batch migration features for VM migrations.

📖 Migration Workflows

🔄 Batch Migration

Guide Descriptions

Migration Playbooks

File: playbooks.md

10 Complete Playbooks:

  1. vSphere to KVM Single VM - Basic single VM migration
  2. vSphere to KVM Bulk Migration - Multiple VM batch migration
  3. AWS EC2 to KVM Migration - Cloud to on-premise
  4. Azure VM to KVM Migration - Azure migration workflow
  5. Disaster Recovery Migration - DR scenario handling
  6. Development Environment Migration - Dev/test environments
  7. Production Database Migration - Database-specific workflow
  8. Web Application Stack Migration - Multi-tier applications
  9. Zero-Downtime Migration - Live migration strategies
  10. Hybrid Cloud Migration - Multi-cloud scenarios

Each playbook includes:

Use when: Planning and executing specific migration scenarios

Migration Quick Reference

File: quick-reference.md

Quick command reference for:

Use when: Need quick syntax for common migration tasks

Batch Features Guide

File: batch-features.md

Complete batch migration features:

Architecture:

Use when: Migrating multiple VMs, need automation, require custom workflows

Batch Quick Reference

File: batch-quick-reference.md

Quick reference for:

Use when: Need quick syntax for batch migration features

Migration Workflow Comparison

Scenario Recommended Guide Features Used Complexity
Single VM migration Quick Reference Basic conversion Low
5-10 VMs Playbooks → Batch Quick Reference Batch orchestration Medium
10+ VMs Batch Features Guide Full batch features Medium-High
Production migration Playbooks (#7-9) → Batch Features Hooks, profiles, mapping High
Cloud migration Playbooks (#3-4, #10) Platform-specific Medium-High
Zero downtime Playbooks (#9) Live migration High

Quick Start Paths

Path 1: First Single VM Migration (30 minutes)

Goal: Migrate your first VM from VMware to KVM

# 1. Use Quick Reference for basic syntax
docs/guides/migration/quick-reference.md

# 2. Run simple migration
hyper2kvm local \
  --vmdk /vms/source.vmdk \
  --output-dir /vms/migrated \
  --to-output vm.qcow2

# 3. Verify and boot
virsh define /vms/migrated/vm.xml
virsh start vm

Recommended: Quick Reference

Path 2: vSphere Bulk Migration (2-4 hours)

Goal: Migrate 10+ VMs from vSphere to KVM

# 1. Follow Playbook 2 for planning
docs/guides/migration/playbooks.md - Playbook 2

# 2. Use Batch Features for automation
docs/guides/migration/batch-features.md

# 3. Create batch manifest
cat > migrations.json <<EOF
{
  "migrations": [
    {"vmdk": "/vms/vm1.vmdk", "to_output": "vm1.qcow2"},
    {"vmdk": "/vms/vm2.vmdk", "to_output": "vm2.qcow2"}
  ]
}
EOF

# 4. Execute batch
hyper2kvm local \
  --batch-manifest migrations.json \
  --batch-parallel 4 \
  --batch-continue-on-error

Recommended: Playbooks + Batch Features Guide

Path 3: Production Database Migration (4-8 hours)

Goal: Zero-downtime production database migration

# 1. Follow Playbook 7 for database-specific steps
docs/guides/migration/playbooks.md - Playbook 7

# 2. Configure hooks for backup/restore
docs/guides/migration/batch-features.md - Pre/Post Hooks

# 3. Use migration profile
cat > db-profile.yaml <<EOF
profile:
  name: "production-db"
  regen_initramfs: true
  fstab_mode: stabilize-all
  libvirt_test: true
  hooks:
    pre_conversion: "./scripts/backup-db.sh"
    post_conversion: "./scripts/verify-db.sh"
EOF

# 4. Execute with profile
hyper2kvm local \
  --vmdk /vms/db-server.vmdk \
  --profile db-profile.yaml

Recommended: Playbooks + Batch Features Guide

Migration Type Guide

Local VMDK Conversion

Scenario: VMDK files already accessible locally

Recommended:

Command:

hyper2kvm local --vmdk /path/to/vm.vmdk --output-dir /output

Remote vSphere Migration

Scenario: Fetch VMs directly from ESXi/vCenter

Recommended:

Command:

hyper2kvm fetch-and-fix \
  --host esxi.example.com \
  --user root \
  --identity ~/.ssh/id_rsa \
  --remote /vmfs/volumes/datastore1/vm/vm.vmdk

OVA/OVF Import

Scenario: Import VMs from OVA/OVF packages

Recommended:

Command:

hyper2kvm ova \
  --ova /path/to/vm.ova \
  --output-dir /output

Cloud Migration (AWS/Azure)

Scenario: Migrate from cloud providers

Recommended:

AWS Command:

hyper2kvm ami \
  --ami ami-12345678 \
  --region us-east-1 \
  --output-dir /output

Azure Command:

hyper2kvm azure \
  --vhd https://storage.blob.core.windows.net/vhds/vm.vhd \
  --output-dir /output

Live Migration (Zero Downtime)

Scenario: Migrate without stopping source VM

Recommended:

Command:

hyper2kvm live-fix \
  --host source-vm.example.com \
  --user root \
  --identity ~/.ssh/id_rsa

Batch Migration Features

Feature 1: Batch Orchestration

Execute multiple migrations in parallel:

hyper2kvm local \
  --batch-manifest migrations.json \
  --batch-parallel 4 \
  --batch-continue-on-error

Documentation: Batch Features Guide - Feature 1

Feature 2: Network & Storage Mapping

Transform network/storage during migration:

mappings:
  network:
    "VM Network": "br0"
    "Storage Network": "br1"
  storage:
    "datastore1": "/vms/pool1"
    "datastore2": "/vms/pool2"

Documentation: Batch Features Guide - Feature 2

Feature 3: Migration Profiles

Reusable configuration templates:

profile:
  name: "linux-server"
  regen_initramfs: true
  fstab_mode: stabilize-all
  compress: true
  libvirt_test: true

Documentation: Batch Features Guide - Feature 3

Feature 4: Pre/Post Hooks

Automation at pipeline stages:

hooks:
  pre_conversion: "./backup.sh"
  post_conversion: "./verify.sh"
  pre_fix: "./prepare.sh"
  post_fix: "./cleanup.sh"

Documentation: Batch Features Guide - Feature 4

Feature 5: Libvirt XML Input

Import from existing libvirt domains:

hyper2kvm libvirt-import \
  --domain-xml /etc/libvirt/qemu/vm.xml \
  --output-dir /output

Documentation: Batch Features Guide - Feature 5

Common Migration Patterns

Pattern 1: Simple Single VM

Files: Quick Reference Features: Basic conversion Time: 30 minutes

Pattern 2: Bulk Migration

Files: Playbooks (#2) + Batch Features Features: Batch orchestration, parallel execution Time: 2-4 hours

Pattern 3: Production Migration

Files: Playbooks (#7-9) + Batch Features Features: Profiles, hooks, mapping, validation Time: 4-8 hours

Pattern 4: Cloud Migration

Files: Playbooks (#3, #4, #10) Features: Platform-specific converters Time: 2-4 hours

Pattern 5: Zero Downtime

Files: Playbooks (#9) + Batch Features Features: Live migration, hooks, verification Time: 8+ hours

Integration with Other Documentation

Pre-Migration Planning

During Migration

Post-Migration

Tool Selection Matrix

Your Need Recommended Guide
First migration Quick Reference
Specific scenario Playbooks (choose scenario)
Multiple VMs Batch Quick Reference
Complex automation Batch Features Guide
Production migration Playbooks (#7-9) + Batch Features
Quick command lookup Quick Reference or Batch Quick Reference

Getting Started

Operational Guides

Reference

Summary

4 comprehensive migration guides covering:

Total Documentation: ~15,000+ lines covering all migration scenarios

Last Updated: February 2026 Documentation Version: 2.1.0 Guides: 4 comprehensive migration guides

Quick Navigation: Guides Hub Documentation Hub Operational Guides
This site is open source. Improve this page.