Stage 0 — Architecture Before Implementation

Start with one Linux VM running nginx on ESXi. The question is how to move it to Kubernetes. The migration path moves the whole VM onto KubeVirt, where it is still a VM, now managed by Kubernetes. The modernization path repackages only the application as containers, so the VM disappears.

Why this matters: Most later decisions depend on which of the two paths you are on.

Remember this: MIGRATION = the VM remains a VM. MODERNIZATION = the VM dependency is removed.

World A is a traditional VM on ESXi. World B is the same VM run by KubeVirt. World C is the application as a container, with no guest OS. Migration moves A to B; modernization moves A or B to C.

Why this matters: Without this split, "moving to Kubernetes" can mean two different projects at once.

Remember this: Migration = A → B. Modernization = A/B → C.

KubeVirt is a Kubernetes add-on. It adds new object types such as VirtualMachine, controllers that act on them, and a node agent. A VM becomes something you kubectl apply, protect with RBAC and schedule like a Pod. It does not replace KVM; it drives QEMU and KVM from inside Pods.

Why this matters: Everything else in Stage 0 builds on this one idea.

Remember this: KubeVirt makes VMs manageable through Kubernetes.

virt-operator installs and upgrades KubeVirt. virt-api provides admission webhooks and subresources such as start, stop and console. virt-controller turns VMs into VMIs and virt-launcher Pods. virt-handler runs on every VM node and tells virt-launcher to define and start the libvirt domain.

Why this matters: When a VM will not start, the failing component tells you where to look.

Remember this: Cluster brain: virt-controller. Node hands: virt-handler.

The VirtualMachine is the persistent definition: it exists while the VM is stopped and holds runStrategy. The VirtualMachineInstance is one running instance. virt-controller creates it when the VM should run and deletes it when it stops.

Why this matters: Lifecycle questions, such as what survives a stop or what restarts a crash, depend on this split.

Remember this: VM = specification. VMI = running instance.

A controller does not run a script once. It observes, compares, takes one idempotent step, then observes again. Example: with runStrategy: Always, if the VM crashes, virt-controller creates a new VMI. That is documented KubeVirt behavior; Stage 0 did not test it.

Why this matters: Idempotent, restart-safe steps are what make a long migration survivable.

Remember this: Controller = state convergence.

spec is what you want; only you write it. status is what actually happened; only the controller writes it. The designed migration CR reports independent conditions such as SourceDiscovered, DiskImported and Ready, each with a reason, a message and observedGeneration.

Why this matters: You debug a controller by reading status, so status must be honest and specific.

Remember this: The controller reports what it knows.

CDI takes a disk image (qcow2, VMDK or raw), imports or receives it, converts it to raw and writes it into a PVC, reporting progress on a DataVolume. CDI ends when the DataVolume is Succeeded. KubeVirt begins when a VM references the PVC.

Why this matters: A clear boundary tells you which system to debug when a migrated VM has a disk problem.

Remember this: CDI imports / prepares disk into Kubernetes storage. CDI does not run VMs.

The designed cold-migration road has three rows. On the source side the VM is discovered, assessed and powered off, and its disk is copied. The disk is then converted and staged. On the Kubernetes target, CDI imports it and a KubeVirt VM is created and validated. A future controller sits on top.

Why this matters: This is the whole project on one page. Each box later becomes a controller phase.

Remember this: Stage 0 designed the whole road; nothing on it was built in Stage 0.

Migration moves the whole machine and ends as a KubeVirt VirtualMachine; the guest OS is kept and still patched like a VM. Modernization moves only the application into a container image run by a Deployment, and the guest OS goes away.

Why this matters: Treating a migrated VM as modernized hides the guest OS you still have to operate.

Remember this: Migration keeps the VM; modernization removes it.

Stage 0 sorted every finding into five categories. Validated means we saw it work. Documented means official docs say so, but we did not run it. Unvalidated means unknown. Blocked means impossible in the current lab mode. Deferred means intentionally not decided yet.

Why this matters: It stops paper decisions from being mistaken for proven facts.

Remember this: Architecture decisions are different from proven runtime facts.

Five accepted decisions answer the big questions. 001: the source is a local nested ESXi. 002: the target is AWS, Terraform-only and disposable. 003: cold before warm. 004: upstream KubeVirt + CDI. 005: a custom controller owns the workflow, with scripts only as building blocks.

Why this matters: ADRs record why, so later stages do not quietly re-decide.

Remember this: Where from, where to, how, onto what, who orchestrates.

Stage 0 produced concepts, designs, a feasibility table and five ADRs, and built nothing. Stage 1 then built selected parts in the lab: a stable ESXi host, a source VM, a cold disk copy, a conversion host, and a converted guest booting on QEMU/KVM. 1H designed the KubeVirt target. 1I built it temporarily on AWS (a single-node kubeadm cluster on EC2), migrated the VM, validated it and destroyed the target on 2026-10-01. The diagram was drawn before 1I.

Why this matters: It shows where design ends and evidence begins.

Remember this: Stage 0 asks: What should we build? Stage 1 asks: Can we actually make the important parts work?