Conversion migration is a specialized migration type designed for integration with external storage vendors and custom migration workflows.

Overview

Conversion migration enables organizations to leverage external storage vendor capabilities for disk data transfer while using Forklift exclusively for guest OS conversion and VM creation. This approach separates storage provisioning from VM conversion, allowing optimized migration workflows in environments with compatible storage infrastructure.

How Conversion Migration Works

Process Overview

  • External Disk Provisioning: Storage vendors or custom processes handle disk data transfer
  • Guest Conversion Only: Forklift performs only guest OS conversion and VM creation
  • Pre-populated Storage: PVCs are created externally before migration begins
  • Metadata-Driven: Uses PVC labels and annotations to identify source disk relationships

Architecture Flow

  1. Storage Vendor Phase
    • External storage vendor transfers VMDK data to target Kubernetes storage
    • Vendor creates PVCs with required metadata (labels and annotations)
    • Data integrity and transfer optimization handled by vendor systems
  2. Forklift Conversion Phase
    • Forklift identifies pre-created PVCs using VM metadata matching
    • Performs guest OS conversion using existing disk data
    • Creates target VM with converted configuration
    • Handles VM lifecycle and power state management

Platform Requirements and Limitations

Source Platform Support

VMware vSphere Only:

  • Conversion migration is exclusively available for VMware vSphere source providers
  • Not supported for oVirt, OpenStack, OVA, or KubeVirt sources
  • Requires access to VMDK disk metadata for proper conversion

Technical Requirements:

  • Source VMs must be accessible through vSphere API
  • VMDK files must be available for metadata extraction
  • VM configuration must be compatible with KubeVirt target platform

Target Platform Requirements

Kubernetes/OpenShift:

  • KubeVirt installed and configured
  • Compatible CSI storage drivers for vendor storage systems
  • Sufficient cluster resources for guest conversion workloads

Prerequisites and Setup

Pre-Migration Requirements

1. Storage Vendor Capabilities

The external storage vendor solution must provide:

  • VMDK Data Transfer: Ability to transfer VMware VMDK data to Kubernetes PVCs
  • Data Integrity: Ensure data consistency during transfer process
  • PVC Provisioning: Automated creation of PVCs with proper metadata
  • Performance Optimization: Leverage storage-level optimizations for faster transfer

2. PVC Creation with Required Metadata

External processes must create PVCs with specific labels and annotations:

Required Labels:

  • vmID: Source VM identifier from vSphere
  • vmUUID: Source VM UUID from vSphere

Required Annotations:

  • forklift.konveyor.io/disk-source: VMDK disk filename (including .vmdk extension)

Example PVC Template:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: vm-conversion-disk-0
  labels:
    vmID: "vm-178"
    vmUUID: "50324a11-5d13-4f9b-9b46-7c8b9f8e123a"
  annotations:
    forklift.konveyor.io/disk-source: "vm-disk-001.vmdk"
spec:
  accessModes:
  - ReadWriteOnce
  resources:
    requests:
      storage: 100Gi
  storageClassName: vendor-optimized-storage

3. Network and Access Configuration

Source Environment:

  • Keep source VMs running during external disk transfer for network configuration preservation
  • Maintain vSphere provider access for Forklift to collect VM metadata
  • Ensure network connectivity between storage vendor systems and vSphere

Target Environment:

  • Configure storage classes compatible with vendor storage systems
  • Ensure network policies allow guest conversion pod operations
  • Validate CSI driver compatibility and performance

Migration Plan Configuration

Plan Creation for Conversion Migration

1
2
3
4
5
6
7
8
9
10
11
12

# Basic conversion migration plan
kubectl mtv create plan conversion-migration \
  --source vsphere-prod \
  --migration-type conversion \
  --vms "vm-with-vendor-storage"

# Conversion migration with simplified storage mapping
kubectl mtv create plan vendor-conversion \
  --source vsphere-prod \
  --migration-type conversion \
  --vms "where name ~= 'vendor-ready-.*'" \
  --target-namespace conversion-target

Storage Mapping Considerations

Simplified Mapping: Since disk provisioning is handled externally, storage mappings can be omitted or simplified:

1
2
3
4
5

map:
  network:
    name: conversion-network-mapping
    namespace: openshift-mtv
  storage: {}  # Empty storage mapping since PVCs are pre-created

Alternative Approach:

1
2
3
4
5
6

# Create plan without explicit storage mapping
kubectl mtv create plan conversion-simple \
  --source vsphere-prod \
  --migration-type conversion \
  --network-mapping network-only-mapping \
  --vms @conversion-vm-list.yaml

Conversion Migration Workflow

Phase 1: External Storage Preparation

  1. Storage Vendor Assessment
    • Validate storage vendor compatibility with your environment
    • Verify data transfer capabilities and performance characteristics
    • Test PVC creation automation and metadata handling
  2. Source VM Analysis
    • Identify VMs suitable for conversion migration
    • Extract VM metadata (vmID, vmUUID, disk information)
    • Plan storage requirements and target storage classes
  3. Storage Transfer Execution
    • Execute storage vendor disk transfer processes
    • Monitor transfer progress and data integrity
    • Validate PVC creation with proper labels and annotations

Phase 2: Forklift Conversion

  1. Pre-Migration Validation 
    1
2
3
4
5

    # Verify PVCs are available with proper metadata
kubectl get pvc -l vmID=vm-178 -o yaml
   
# Check VM accessibility in source provider
kubectl mtv get inventory vms vsphere-prod -q "where id = 'vm-178'"
  2. Migration Plan Execution 
    1
2
3
4
5

    # Start conversion migration
kubectl mtv start plan conversion-migration
   
# Monitor conversion progress
kubectl mtv get plan conversion-migration --watch
  3. Post-Migration Validation 
    1
2
3
4
5

    # Verify VM creation
kubectl get vm -n target-namespace
   
# Check VM functionality
kubectl mtv describe plan conversion-migration

Use Cases and Scenarios

Enterprise Storage Integration

Storage Array Optimization:

  • Organizations with high-performance storage arrays providing optimized VM data transfer
  • Custom storage replication mechanisms that can populate Kubernetes PVCs
  • Integration with storage vendor migration tools and automation platforms

Performance-Critical Migrations:

  • Large-scale migration projects where network-based transfer creates bottlenecks
  • Environments requiring storage-level optimization for massive data volumes
  • Scenarios where storage vendor tools provide superior performance to network transfers

Custom Migration Architectures

Multi-Stage Workflows:

  • Organizations with existing disk migration processes that need VM conversion
  • Integration with backup and restore systems that can populate PVCs from backups
  • Custom automation that separates storage provisioning from VM lifecycle management

Vendor Ecosystem Integration:

  • Storage vendors providing migration services with Kubernetes integration
  • Managed service providers offering optimized migration solutions
  • Enterprise environments with multiple storage vendor relationships

Best Practices

Planning and Coordination

Storage Vendor Coordination:

  • Ensure storage vendor processes complete successfully before starting Forklift migration
  • Validate PVC metadata exactly matches source VM configuration
  • Test complete integration workflow in non-production environment before production use

Source VM Management:

  • Keep source VMs running during external disk transfer to preserve network configuration
  • Maintain vSphere provider connectivity for IP address and configuration collection
  • Plan maintenance windows that account for both storage transfer and conversion phases

Validation and Testing

Pre-Migration Testing:

  • Validate storage vendor PVC creation automation with test VMs
  • Test complete conversion workflow with non-critical VMs
  • Verify post-conversion VM functionality and performance

Monitoring and Troubleshooting:

  • Implement monitoring for both storage vendor processes and Forklift conversion
  • Plan troubleshooting procedures that span multiple vendor systems
  • Establish clear escalation paths for issues in storage vendor vs. Forklift domains

Performance Optimization

Storage Configuration:

  • Use high-performance storage classes compatible with vendor systems
  • Configure appropriate PVC access modes and volume modes
  • Consider storage array features like deduplication and compression

Cluster Resource Management:

  • Ensure adequate cluster resources for guest conversion workloads
  • Consider dedicated nodes for conversion processing if performing large-scale migrations
  • Monitor cluster performance during conversion operations

Troubleshooting

Common Issues

PVC Metadata Problems

Missing or Incorrect Labels:

1
2
3
4
5

# Check PVC labels
kubectl get pvc -o yaml | grep -A10 -B10 "vmID\|vmUUID"

# Verify label values match source VM
kubectl mtv get inventory vms vsphere-prod -q "where id = 'vm-178'" -o yaml

Annotation Issues:

1
2

# Validate disk source annotations
kubectl get pvc -o yaml | grep -A5 -B5 "forklift.konveyor.io/disk-source"

Storage Vendor Integration Issues

PVC Availability:

  • Verify storage vendor processes completed successfully
  • Check PVC status and binding to persistent volumes
  • Validate storage class availability and configuration

Data Integrity:

  • Confirm storage vendor data transfer completed without errors
  • Verify disk data is accessible from Kubernetes cluster
  • Test PVC mounting and data accessibility

Forklift Conversion Problems

VM Metadata Mismatch:

  • Ensure source VM is still accessible through vSphere provider
  • Verify VM configuration hasn’t changed since PVC creation
  • Check for VM state changes that might affect conversion

Guest Conversion Failures:

  • Review guest conversion pod logs for detailed error information
  • Verify VM compatibility with KubeVirt target platform
  • Check for guest OS specific issues or driver requirements

Monitoring and Logging

Storage Vendor Monitoring:

  • Monitor storage vendor transfer processes and completion status
  • Track PVC creation and metadata accuracy
  • Validate data transfer performance and integrity

Forklift Monitoring:

1
2
3
4
5
6
7
8

# Monitor conversion plan progress
kubectl mtv get plan conversion-migration --watch

# Check conversion pod logs
kubectl logs -l migration=conversion-migration -f

# Review plan events and conditions
kubectl describe plan conversion-migration

Integration Examples

Complete Conversion Migration Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# Step 1: Verify storage vendor has completed PVC creation
kubectl get pvc -l vmID=vm-178

# Step 2: Validate PVC metadata
kubectl get pvc conversion-vm-disk-0 -o yaml

# Step 3: Create conversion migration plan
kubectl mtv create plan vendor-conversion-example \
  --source vsphere-production \
  --migration-type conversion \
  --target-namespace production-workloads \
  --network-mapping production-networks \
  --vms "vendor-migrated-vm-01,vendor-migrated-vm-02"

# Step 4: Execute migration
kubectl mtv start plan vendor-conversion-example

# Step 5: Monitor and validate
kubectl mtv get plan vendor-conversion-example --watch

Advanced Configuration Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# conversion-plan.yaml
apiVersion: forklift.konveyor.io/v1beta1
kind: Plan
metadata:
  name: advanced-conversion-plan
  namespace: openshift-mtv
spec:
  type: conversion
  description: "Conversion migration with vendor-provided storage"
  targetNamespace: migrated-workloads
  provider:
    source:
      name: vsphere-production
      namespace: openshift-mtv
    destination:
      name: openshift-target
      namespace: openshift-mtv
  map:
    network:
      name: production-network-mapping
      namespace: openshift-mtv
    storage: {}  # Empty - PVCs pre-created by vendor
  vms:
  - id: vm-178
    name: production-database
  - id: vm-179  
    name: production-webserver
  preserveStaticIPs: true
  targetPowerState: on

Next Steps

After understanding conversion migration:

  1. Evaluate Storage Vendors: Assess available storage vendor solutions for compatibility
  2. Test Integration: Implement proof-of-concept with non-critical VMs
  3. Plan Production Rollout: Design comprehensive migration strategy incorporating conversion migration
  4. Monitor and Optimize: Establish monitoring and optimization procedures for production use

Previous: Chapter 3.5: Migration Types and Strategy Selection
Next: Chapter 4: Provider Management