kubevirt-vm-migration-platform

ADR 005: Custom migration controller vs scripts

• Status: Accepted (direction); implementation deferred to a later stage

Context

A migration is long-running, multi-step, touches external systems (ESXi, staging storage, CDI, KubeVirt) and can fail halfway. Scripts are the fastest way to learn each step, but they keep state in a terminal, are hard to resume safely, and do not integrate with Kubernetes RBAC, status or GitOps. MTV solves this with controllers and CRs, but we are building a learning platform, not copying MTV.

Decision

The migration workflow will be owned by a custom Kubernetes controller reconciling a namespaced VirtualMachineMigration CR (migration.platform.example/v1alpha1) through an explicit state machine. Scripts are allowed as learning tools and as the building blocks the controller calls (for example a conversion Job), not as the orchestrator.

Clarification (Stage 0 refinement)

• The controller owns a declarative migration workflow. The state machine represents reconciliation checkpoints, not a procedural script: each phase names a desired state; every reconcile re-observes actual state and takes the idempotent action that closes the gap.
• status.phase is the controller’s current reconciliation state, not a log of what ran.
• Required properties: idempotency, resumability, retry safety, with desired and observed state kept distinct (migration-state-machine.md).
• Implementation remains deferred.

Comparison (conceptual)

	Scripts	Controller
State	Terminal/logs	CR status in etcd
Resume after crash	Manual	Reconcile re-observes the system from the current checkpoint
Retries	Hand-written	Work queue with backoff + retry budget
Concurrency	Unprotected	One worker per object key
Access control	SSH/shell	Kubernetes RBAC
Cleanup	Manual	Finalizers + owner references

Consequences

• Every step must be idempotent (deterministic names, create-if-absent, evidence recorded before advancing).
• More upfront design: CRD schema, state machine, conditions. Stage 0 covers this conceptually.
• Language/framework (for example Go + controller-runtime/kubebuilder, or Python + kopf) is deferred.
• Nothing is implemented or applied in Stage 0.

Status check (added 2026-10-15). Implementation is still deferred. The first migration (Stage 1I, 2026-10-01) was run step by step under explicit approval gates, and its Gate I4 approval explicitly excluded a migration controller and Forklift. The repository contains no controller code and no VirtualMachineMigration CRD manifest. Everything in this ADR remains design.

Evidence

Design in crd-controller-fundamentals.md, migration-state-machine.md, migration-architecture.md. References: Kubernetes controllers, Custom resources, Operator pattern.