hypersdk

hypersdk - Project Summary

Official Project Name: hypersdk Status: ✅ Production Ready Date: 2026-01-19 Version: 0.2.0 (Phase 2 Complete)

🎯 What We Built

A complete, production-ready VM migration and management system with:

Component Size Purpose
hyperexport 19 MB Interactive CLI with beautiful pterm UI
hypervisord 20 MB Background daemon with 51+ REST API endpoints
hyperctl 17 MB Daemon control CLI tool
Web Dashboard - Browser-based UI for job monitoring and VM console access

✅ Completed Features

Phase 1: Core Functionality

Phase 2: Extended Features (New!)

Daemon Architecture

User Experience

📊 Test Results

Live Test - Currently Running

VM Being Exported:

Test Environment:

What Was Tested

✅ Connection to vSphere
✅ VM discovery (201 VMs)
✅ Interactive VM selection
✅ Daemon startup and API
✅ Job submission via YAML
✅ Job query and status
✅ Parallel file downloads
✅ Progress tracking
✅ CD/DVD removal
✅ Error handling and retry

📁 Project Structure

~/projects/hypersdk/
├── build/
│   ├── hyper2kvm      (19 MB) - CLI
│   ├── hypervisord     (20 MB) - Daemon
│   └── hyperctl       (17 MB) - Control
│
├── cmd/
│   ├── hyper2kvm/main.go      - Interactive CLI
│   ├── hypervisord/main.go     - Daemon service
│   └── hyperctl/main.go       - Control CLI
│
├── daemon/
│   ├── models/job.go          - Job models
│   ├── jobs/manager.go        - Job manager
│   └── api/server.go          - REST API
│
├── providers/
│   └── vsphere/
│       ├── client.go          - vSphere connection
│       ├── export.go          - Export logic
│       ├── vm_operations.go   - VM management
│       └── types.go           - Type definitions
│
├── progress/
│   └── reporter.go            - Progress abstraction
│
├── config/
│   └── config.go              - Configuration
│
├── logger/
│   └── logger.go              - Logging
│
├── go.mod                     - Module: hypersdk
├── README.md                  - Main documentation
├── GETTING-STARTED.md         - Quick start guide
├── DAEMON-README.md           - Daemon architecture
├── TEST-RESULTS.md            - Detailed test report
└── example-*.yaml             - Example job files

🚀 Quick Commands

Start Daemon

cd ~/projects/hypersdk
export GOVC_URL='https://vcenter.example.com/sdk'
export GOVC_USERNAME='administrator@vsphere.local'
export GOVC_PASSWORD='your-password'
export GOVC_INSECURE=1

./build/hypervisord

Submit Job

# Single VM
./build/hyperctl submit -vm "/datacenter/vm/my-vm" -output "/tmp/export"

# From file
./build/hyperctl submit -file example-job.yaml

# Batch
./build/hyperctl submit -file example-batch.yaml

Monitor Progress

./build/hyperctl query -all
./build/hyperctl status

Interactive Mode

./build/hyperexport

🔧 Technical Details

Technologies Used

Concurrency Model

API Design (51+ Endpoints)

Total: 51+ production-ready endpoints

Security Features

🐍 Python Integration Example

import requests
import time

BASE_URL = "http://localhost:8080"

def export_vm(vm_path, output_path):
    """Submit VM export job"""
    response = requests.post(f"{BASE_URL}/jobs/submit", json={
        "name": "python-export",
        "vm_path": vm_path,
        "output_path": output_path,
        "options": {
            "parallel_downloads": 4,
            "remove_cdrom": True
        }
    })
    
    job_id = response.json()["job_ids"][0]
    print(f"Job submitted: {job_id}")
    return job_id

def wait_for_completion(job_id):
    """Wait for job to complete"""
    while True:
        response = requests.post(f"{BASE_URL}/jobs/query",
            json={"job_ids": [job_id]})
        
        job = response.json()["jobs"][0]
        status = job["status"]
        
        print(f"Status: {status}", end="")
        
        if job.get("progress"):
            progress = job["progress"]
            print(f" - {progress['phase']} ({progress['percent_complete']:.1f}%)")
        else:
            print()
        
        if status in ["completed", "failed", "cancelled"]:
            return job
        
        time.sleep(5)

# Usage
job_id = export_vm("/datacenter/vm/my-vm", "/tmp/export")
result = wait_for_completion(job_id)

if result["status"] == "completed":
    print(f"Export successful!")
    print(f"Output: {result['result']['output_dir']}")
else:
    print(f"Export failed: {result.get('error')}")

📈 Performance Characteristics

🎓 Key Learnings

API Evolution Fixed

Design Decisions

🔮 Future Enhancements

Completed (Phase 2)

Planned

Possible

📚 Documentation

Core Documentation

| File | Purpose | |——|———| | README.md | Main project documentation | | GETTING-STARTED.md | Quick start guide with dashboard | | project-summary.md | This document - architecture overview |

API Documentation

| File | Purpose | |——|———| | API_ENDPOINTS.md | Complete API reference (51+ endpoints) | | API_REFERENCE_NEW_FEATURES.md | Phase 2 features documentation | | api.md | General API usage guide |

Dashboard Documentation

| File | Purpose | |——|———| | Dashboard README | Dashboard usage and customization | | DASHBOARD_IMPLEMENTATION_COMPLETE.md | Implementation details | | DASHBOARD_TESTING_REPORT.md | Comprehensive testing results |

Testing

| File | Purpose | |——|———| | TEST-RESULTS.md | Test coverage report | | test-api.sh | API testing script | | test-dashboard-endpoints.sh | Dashboard endpoint testing |

Examples

| File | Purpose | |——|———| | example-job.yaml | Single job example | | example-batch.yaml | Batch job example | | config.yaml.example | Configuration example |

🎉 Success Criteria - All Met!

✅ Phase 1: Functional Requirements

✅ Phase 2: Extended Requirements

✅ User Experience

✅ Quality

✅ Integration

✅ Testing

🏆 What Makes This Special

  1. Complete Solution - Three tools + web dashboard for all use cases
  2. Production Ready - Error handling, retry, logging, security hardening
  3. Beautiful UX - Modern terminal interface + web UI
  4. Easy Integration - 51+ REST API endpoints for automation
  5. Well Architected - Clean, maintainable code with proper separation of concerns
  6. Thoroughly Tested - Live tests with real vCenter, comprehensive endpoint testing
  7. Full VM Management - VMware export + libvirt/KVM management in one system
  8. Console Access - Browser-based VNC and serial console access
  9. Secure - XML injection prevention, path validation, input sanitization

🔗 Integration with hyper2kvm

This project complements the Python hyper2kvm project:

Together they provide a complete migration solution:

  1. Discover - VMware VM discovery via hypersdk API
  2. Export - High-speed export with hypervisord (concurrent, resumable)
  3. Convert - Conversion orchestration with Python hyper2kvm
  4. Import - Libvirt VM import and management via hypersdk
  5. Monitor - Web dashboard for end-to-end monitoring
  6. Manage - Post-migration VM management (snapshots, backups, console access)

✨ Final Notes

Project Status: ✅ PRODUCTION READY (Phase 2 Complete)

Everything works as designed:

Current Capabilities:

Implementation Timeline:

Made with ❤️ by Susant Sahani

Part of the hyper2kvm project family

This site is open source. Improve this page.