Skip to content

CLAUDE.md

Latest commit

 

History

History
151 lines (111 loc) · 6.11 KB

CLAUDE.md

File metadata and controls

151 lines (111 loc) · 6.11 KB
Raw

vJailbreak Development Instructions

vJailbreak is a VMware to Platform9 Private Cloud Director (PCD) VM migration tool built on Kubernetes (k3s). It converts VMDK disks to QCOW2 (or raw LUNs) and deploys VMs to OpenStack, supporting hot (live) and cold migrations with Changed Block Tracking (CBT).

Quick References

External Documentation

DIRECTIVE: When working with vJailbreak components, ALWAYS consult the official documentation of underlying open-source tools before implementing features or debugging issues.

Core Dependencies: virt-v2v, libguestfs, nbdkit, k3s, OpenStack, Platform9 PCD, govmomi, controller-runtime, virtio-win

Documentation Links:

Development Rules

Critical directives — follow these strictly:

CRD Changes

  • After editing types in k8s/migration/api/v1alpha1/, ALWAYS run make generate inside k8s/migration/ to regenerate deepcopy/client code and update CRD YAML
  • Test CRD changes with cd k8s/migration && make test before committing

Generated Files

  • NEVER hand-edit deploy/installer.yaml — it is generated by make generate-manifests
  • NEVER hand-edit zz_generated.deepcopy.go files — they are generated by controller-gen

Git Workflow

  • Run make setup-hooks once per clone before any commits to activate pre-commit validation
  • Pre-commit hooks will validate code formatting and run basic checks

Unit Test Requirements

  • ALWAYS write unit tests for any new code written by Claude
  • Place tests in _test.go files alongside the code under test (Go convention)
  • If existing code is hard to unit test (e.g., no interfaces, large functions with external deps), refactor up to 1-2 files to make it testable — refactor must not change logic or behavior, only restructure for testability (e.g., extract interfaces, dependency injection, split large functions into pure helpers)
  • Use table-driven tests for Go code where multiple input/output cases apply
  • Mock external dependencies (VMware, OpenStack, Kubernetes API) using interfaces — do not hit real external systems in unit tests

Integration/Build Testing Requirements

  • v2v-helper tests require CGO_ENABLED=1 GOOS=linux GOARCH=amd64
  • v2v-helper tests will NOT compile on macOS without Linux cross-compilation toolchain
  • Run make test-v2v-helper for v2v-helper tests (requires Linux or Docker)
  • Run cd k8s/migration && make test for controller tests
  • ALWAYS run tests before submitting PRs

Module Structure

  • Four independent Go modules — run go commands from the correct directory:
    • Controller: k8s/migration/
    • V2V Helper: v2v-helper/
    • API Server: pkg/vpwned/
    • Common: pkg/common/
  • When adding dependencies, run go mod tidy in the specific module directory
  • Cross-module imports must reference the full module path

Repository Layout

Path Purpose
k8s/migration/ Kubernetes controller manager (Go, controller-runtime)
v2v-helper/ Migration worker pod — disk copy and conversion (Go, libguestfs)
ui/ React/TypeScript frontend (MUI, Vite)
pkg/vpwned/ REST API server (Go) for Cluster Conversion
pkg/common/ Shared Go utilities
image_builder/ Builds the vJailbreak appliance QCOW2 image
appliance/ Vagrant-based k3s cluster for local testing
deploy/ Generated Kubernetes manifests
docs/ Astro documentation site
scripts/ Utility and firstboot scripts

Quick Commands

# One-time setup
make setup-hooks

# Build components
make ui v2v-helper vjail-controller build-vpwned
make generate-manifests  # Requires vjail-controller and ui built first
make build-image         # Complete appliance QCOW2

# Testing
make test-v2v-helper     # v2v-helper (requires Linux CGO)
cd k8s/migration && make test  # Controller tests

# Development
make run-local           # Run controller locally
cd ui && yarn dev        # UI dev server (requires VITE_API_HOST, VITE_API_TOKEN)

Image tags: Default <git-parent-branch>-<short-sha>. Override: BUILD_VERSION=v1.2.3 REGISTRY=myregistry.io make <target>

Common Pitfalls

  • macOS Development: v2v-helper tests require Linux CGO, use Docker/Linux VM
  • DNS Resolution: ESXi host DNS required for VM copy. Add to /etc/hosts or restart controller after /etc/resolv.conf changes
  • VDDK Libraries: Must be in /home/ubuntu/vmware-vix-disklib-distrib on vJailbreak VM
  • Build Dependencies: generate-manifests requires vjail-controller and ui built first

Debugging

# Controller logs
kubectl -n vjailbreak logs -l control-plane=controller-manager -f

# Migration status
kubectl -n migration-system get migration <name> -o yaml

# V2V helper logs
kubectl -n migration-system logs <migration-name>-v2v-helper

Check: Guest OS support at https://libguestfs.org/virt-v2v-support.1.html

Repository Structure

| Path | Purpose | |------|---------|| | k8s/migration/ | Controller (Go module) | | v2v-helper/ | Migration worker (Go module, CGO required) | | ui/ | React/TypeScript frontend | | pkg/vpwned/ | API server (Go module) | | pkg/common/ | Shared utilities (Go module) | | scripts/ | Utility and firstboot scripts | | deploy/ | Generated Kubernetes manifests |

Key CRDs: Migration, MigrationPlan, VMwareCreds, OpenstackCreds, NetworkMapping, StorageMapping, MigrationTemplate