kubectl-mtv

A kubectl plugin for migrating virtual machines to KubeVirt using Forklift.

Overview

kubectl-mtv helps migrate VMs from vSphere, oVirt, OpenStack, EC2, and OVA to Kubernetes/OpenShift using KubeVirt. It's a command-line interface for the Forklift project.

Installation

# Using krew
kubectl krew install mtv

# Or download from releases
# https://github.com/yaacov/kubectl-mtv/releases

See Installation Guide for more options.

MCP Support

kubectl-mtv includes a built-in MCP (Model Context Protocol) server for AI agents that support MCP add‑ons, such as Cursor IDE and Claude Desktop.

See MCP Server Guide for detailed setup instructions and usage examples.

Quick Start

1. Create Provider

# vSphere
kubectl mtv create provider vsphere-01 --type vsphere \
  --url https://vcenter.example.com \
  -u admin --password secret --cacert @ca.cert

2. Create Mappings (Optional)

# Network mapping
kubectl mtv create mapping network prod-net \
  --source vsphere-01 --target openshift \
  --network-pairs "VM Network:default,Management:openshift-sdn/mgmt"

# Storage mapping with enhanced features
kubectl mtv create mapping storage prod-storage \
  --source vsphere-01 --target openshift \
  --storage-pairs "datastore1:standard;volumeMode=Block;accessMode=ReadWriteOnce,datastore2:fast;volumeMode=Filesystem" \
  --default-offload-plugin vsphere --default-offload-vendor flashsystem

3. Create Migration Plan

# Using system defaults for best network and storage mapping
kubectl mtv create plan migration-1 \
  --source vsphere-01 \
  --vms vm1,vm2,vm3

# Using existing mappings
kubectl mtv create plan migration-1 \
  --source vsphere-01 \
  --network-mapping prod-net \
  --storage-mapping prod-storage \
  --vms vm1,vm2,vm3

4. Start Migration

kubectl mtv start plan migration-1

5. Monitor Progress

# Interactive TUI with scrolling, help panel, and adjustable refresh
kubectl mtv get plan --vms --watch

For a complete walkthrough, see the Quick Start Guide.

Inventory Management

Query and explore provider resources before migration:

# List VMs
kubectl mtv get inventory vms vsphere-01

# Filter VMs by criteria
kubectl mtv get inventory vms vsphere-01 -q "where memoryMB > 4096"

# List networks and storage
kubectl mtv get inventory networks vsphere-01
kubectl mtv get inventory storage vsphere-01

See Inventory Management Guide for advanced queries and filtering.

VDDK Support

For optimal VMware disk transfer performance, build a VDDK image from VMware's VDDK SDK:

# Build VDDK image
kubectl mtv create vddk-image \
  --tar VMware-vix-disklib-8.0.1.tar.gz \
  --tag quay.io/myorg/vddk:8.0.1

# Use it when creating a provider
kubectl mtv create provider vsphere-01 --type vsphere \
  --url https://vcenter.example.com \
  --vddk-init-image quay.io/myorg/vddk:8.0.1

See VDDK Setup Guide for detailed instructions.

Help and Reference Topics

The built-in help system includes machine-readable output and reference topics for domain-specific query languages:

# Get help for any command
kubectl mtv help create plan

# Learn the TSL query language or KARL affinity syntax
kubectl mtv help tsl
kubectl mtv help karl

# Machine-readable command schema (JSON/YAML) for automation and AI agents
kubectl mtv help --machine
kubectl mtv help --machine --short get plan

See Command Reference for the full help command documentation.

Features

• Multi-Platform Support: Migrate from vSphere, oVirt, OpenStack, EC2, and OVA
• Auto-Mapping: Automatic network and storage mapping for all source providers
• Flexible Mapping: Use existing mappings, inline pairs, or automatic defaults
• Advanced Queries: Filter and search inventory with powerful query language
• VDDK Support: Optimized VMware disk transfers
• Real-time Monitoring: Track migration progress live
• Timezone-Aware Display: View timestamps in local time or UTC with --use-utc flag
• System Health Checks: Comprehensive health diagnostics for the MTV/Forklift system with actionable recommendations
• Settings Management: View and configure ForkliftController settings (feature flags, performance tuning, resource limits)
• Machine-Readable Help: Full command schema available as JSON/YAML for automation, MCP servers, and AI agents

Documentation

Complete Technical Guide - Comprehensive documentation covering all features and use cases

Quick Links

• Installation & Prerequisites
• Quick Start Tutorial
• Provider Management
• Inventory Management
• Mapping Management
• Migration Plan Creation
• Migration Hooks
• MCP Server Integration
• Command Reference

Environment Variables

• MTV_VDDK_INIT_IMAGE: Default VDDK init image for VMware providers
• MTV_INVENTORY_URL: Base URL for inventory service
• MTV_INVENTORY_INSECURE_SKIP_TLS: Skip TLS verification for inventory service connections (set to "true" to enable)

License

Apache-2.0