https://github.com/yaacov/kubectl-mtv
A kubectl plugin that helps users of Forklift migrate virtualization workloads from oVirt, VMware, OpenStack, and OVA files to KubeVirt on Kubernetes.
https://github.com/yaacov/kubectl-mtv
forklift kubectl-plugin kubevirt migration-tool
Last synced: 2 months ago
JSON representation
A kubectl plugin that helps users of Forklift migrate virtualization workloads from oVirt, VMware, OpenStack, and OVA files to KubeVirt on Kubernetes.
- Host: GitHub
- URL: https://github.com/yaacov/kubectl-mtv
- Owner: yaacov
- License: apache-2.0
- Created: 2025-04-07T04:57:16.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-10T11:19:00.000Z (3 months ago)
- Last Synced: 2026-03-10T18:48:30.711Z (3 months ago)
- Topics: forklift, kubectl-plugin, kubevirt, migration-tool
- Language: Go
- Homepage: https://yaacov.github.io/kubectl-mtv/
- Size: 3.34 MB
- Stars: 11
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://github.com/kubev2v/forklift) project.
## Installation
Install the latest release (Linux / macOS):
```bash
curl -sSL https://raw.githubusercontent.com/yaacov/kubectl-mtv/main/install.sh | bash
```
This downloads the binary, verifies its checksum, and sets up shell completion. Installs to `~/.local/bin` by default.
Or build from source:
```bash
make build
mkdir -p ~/.local/bin
cp kubectl-mtv ~/.local/bin/kubectl-mtv
```
Once installed, kubectl discovers it as a plugin:
```bash
kubectl mtv --help
```
For more options (krew, manual download, shell completion, uninstall), see the [Installation Guide](guide/02-installation-and-prerequisites.md).
[](https://asciinema.org/a/uQWEl16tfen7TJAi)
## 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](guide/22-model-context-protocol-mcp-server-integration.md) for detailed setup instructions and usage examples.
## Quick Start
### 1. Create Provider
```bash
# vSphere
kubectl mtv create provider --name vsphere-01 --type vsphere \
--url https://vcenter.example.com \
--username admin --password secret --cacert @ca.cert
```
### 2. Create Migration Plan
Network and storage mappings are created automatically with sensible defaults.
Use `--network-pairs` / `--storage-pairs` to override inline if needed.
```bash
# Using system defaults for best network and storage mapping
kubectl mtv create plan --name migration-1 \
--source vsphere-01 \
--vms vm1,vm2,vm3
# Overriding mappings inline
kubectl mtv create plan --name migration-1 \
--source vsphere-01 \
--vms vm1,vm2,vm3 \
--network-pairs "VM Network:default" \
--storage-pairs "datastore1:standard"
```
### 3. Start Migration
```bash
kubectl mtv start plan --name migration-1
```
### 4. Monitor Progress
```bash
# Interactive TUI with scrolling, help panel, and adjustable refresh
kubectl mtv get plans --vms --watch
```
### Advanced: Reusable Mappings
If you need to reuse the same network/storage configuration across multiple plans,
create named mappings and reference them:
```bash
# Network mapping
kubectl mtv create mapping network --name 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 --name 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
# Reference them in a plan
kubectl mtv create plan --name migration-1 \
--source vsphere-01 \
--network-mapping prod-net \
--storage-mapping prod-storage \
--vms vm1,vm2,vm3
```
For a complete walkthrough, see the [Quick Start Guide](guide/03-quick-start-first-migration-workflow.md).
## Inventory Management
Query and explore provider resources before migration:
```bash
# List VMs
kubectl mtv get inventory vms --provider vsphere-01
# Filter VMs by criteria
kubectl mtv get inventory vms --provider vsphere-01 --query "where memoryMB > 4096"
# List networks and storage
kubectl mtv get inventory networks --provider vsphere-01
kubectl mtv get inventory storages --provider vsphere-01
```
See [Inventory Management Guide](guide/09-inventory-management.md) for advanced queries and filtering.
## VDDK Support
For optimal VMware disk transfer performance, build a VDDK image from VMware's VDDK SDK:
```bash
# 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 --name vsphere-01 --type vsphere \
--url https://vcenter.example.com \
--vddk-init-image quay.io/myorg/vddk:8.0.1
```
See [VDDK Setup Guide](guide/08-vddk-image-creation-and-configuration.md) for detailed instructions.
## Help and Reference Topics
The built-in help system includes machine-readable output and reference topics for domain-specific query languages:
```bash
# 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](guide/26-command-reference.md) 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
## 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)
## Documentation
**[Complete Technical Guide](guide/)** - Comprehensive documentation covering all features and use cases
### Quick Links
- [Installation & Prerequisites](guide/02-installation-and-prerequisites.md)
- [Quick Start Tutorial](guide/03-quick-start-first-migration-workflow.md)
- [Provider Management](guide/06-provider-management.md)
- [Inventory Management](guide/09-inventory-management.md)
- [Mapping Management](guide/11-mapping-management.md)
- [Migration Plan Creation](guide/13-migration-plan-creation.md)
- [Migration Hooks](guide/17-migration-hooks.md)
- [MCP Server Integration](guide/22-model-context-protocol-mcp-server-integration.md)
- [Command Reference](guide/26-command-reference.md)
## Running from a Container Image
Start the MCP server using docker or podman:
```bash
# Run the MCP server on port 8080
docker run --rm -p 8080:8080 \
-e MCP_KUBE_SERVER=https://api.cluster.example.com:6443 \
-e MCP_KUBE_TOKEN=sha256~xxxx \
quay.io/yaacov/kubectl-mtv-mcp-server:latest
# Run in read-only mode (disables write operations)
docker run --rm -p 8080:8080 \
-e MCP_KUBE_SERVER=https://api.cluster.example.com:6443 \
-e MCP_KUBE_TOKEN=sha256~xxxx \
-e MCP_READ_ONLY=true \
quay.io/yaacov/kubectl-mtv-mcp-server:latest
```
The server accepts the following environment variables:
| Variable | Default | Description |
|---|---|---|
| `MCP_HOST` | `0.0.0.0` | Listen address |
| `MCP_PORT` | `8080` | Listen port |
| `MCP_KUBE_SERVER` | | Kubernetes API server URL |
| `MCP_KUBE_TOKEN` | | Bearer token for Kubernetes auth |
| `MCP_KUBE_INSECURE` | | Set to `true` to skip TLS verification |
| `MCP_CERT_FILE` | | Path to TLS certificate (enables HTTPS) |
| `MCP_KEY_FILE` | | Path to TLS private key |
| `MCP_OUTPUT_FORMAT` | `markdown` | Default output format |
| `MCP_MAX_RESPONSE_CHARS` | `0` | Max response size (0 = unlimited) |
| `MCP_READ_ONLY` | `false` | Set to `true` to disable write operations |
## Building & Testing
Build and test the container image with the MCP end-to-end test suite:
```bash
# Build the image (linux/amd64)
make image-build-amd64
# Run e2e tests against the container image
make test-e2e-mcp-image MCP_IMAGE=quay.io/yaacov/kubectl-mtv-mcp-server
# Run e2e tests against the local binary build
make test-e2e-mcp
# Run e2e tests against an already running server
MCP_SSE_URL=http://localhost:8080/sse make test-e2e-mcp-external
```
You can also set `MCP_IMAGE` in `e2e/mcp/.env` (see `e2e/mcp/env.example`) and
use `CONTAINER_ENGINE` to choose between docker and podman.
## Deploying MCP Server to OpenShift
Deploy the MCP server directly to OpenShift:
```bash
# Deploy the MCP server (pod and service)
oc apply -f https://raw.githubusercontent.com/yaacov/kubectl-mtv/main/deploy/mcp-server.yaml
# Register the MCP server with OpenShift Lightspeed
oc patch olsconfig cluster --type merge \
-p "$(curl -s https://raw.githubusercontent.com/yaacov/kubectl-mtv/main/deploy/olsconfig-patch.yaml)"
```
To remove the MCP server:
```bash
# Unregister from Lightspeed
oc patch olsconfig cluster --type json \
-p '[{"op":"remove","path":"/spec/mcpServers"},{"op":"remove","path":"/spec/featureGates"}]'
# Delete the MCP server resources
oc delete -f https://raw.githubusercontent.com/yaacov/kubectl-mtv/main/deploy/mcp-server.yaml
```
See [MCP Server Guide](guide/22-model-context-protocol-mcp-server-integration.md) for more details on OpenShift integration.
## License
Apache-2.0