Building with the Operator SDK

Everything up to here was design. This page is the part somebody can execute, so it is deliberately command-heavy and I have tried to include the details that cost a day when they are missing rather than the ones that are obvious from the tutorial.

1. Toolchain

2. Scaffolding

The order matters in one place, marked below.

Now the resources. Note --namespaced=false on everything cluster-scoped, matching the scoping decisions from the API page.

Then the webhooks. Defaulting matters more than usual here, because a class with a sensible default set is the difference between a usable API and one where every field must be spelled out.

3. The resulting layout

The four packages under internal/ that the SDK does not scaffold are where I would put the actual thinking. Rendering a VirtualMachine from a class is the most intricate logic in the project and it should be a pure function that a table test can hammer, not something buried inside a reconcile loop.

4. Registering external schemes

The operator reads and writes KubeVirt and CDI objects, so their types have to be in the manager's scheme. This is a small step that produces a confusing runtime error when it is missed.

5. Controller anatomy

The machine controller is the one worth showing, because its shape follows directly from the phase machine and from the requirement that a restarted operator can recover.

Each ensure function is idempotent and answers one question: does the object exist, does it match what the class says it should be, and is it ready. That structure is what makes the whole thing safe to interrupt.

Wiring it up, with the parts that are easy to leave out:

6. RBAC

Generated from markers, which means the deployed role is always consistent with what the code actually does. This is my favourite thing about the Kubebuilder model and worth using carefully rather than pasting a wildcard.

The subresources.kubevirt.io line is easy to miss and produces a puzzling failure: the operator can create and delete VMs but cannot gracefully stop one, so graceful shutdown silently degrades into deletion. That is exactly the APFS-corrupting behaviour the design was meant to eliminate, reintroduced by a missing RBAC rule.

7. Testing, and being honest about its limits

This is where I want to set expectations carefully, because the most important behaviour in the system cannot be tested in CI.

envtest gives a real API server without a kubelet, which is perfect here: I want to assert that the operator produced the right VirtualMachine, not that QEMU ran. The trick is that envtest needs to know about KubeVirt's types, which means vendoring their CRDs:

Practical envtest notes: reconcile results are eventually consistent, so assertions want Eventually with real timeouts rather than sleeps. And every test needs its own namespace, because a leaked finalizer in one test will hang teardown for all of them in a way that is genuinely hard to diagnose.

8. Local development

Running out of cluster with webhooks disabled is the fast loop. Webhooks need a serving certificate and a reachable service, which is awkward from a laptop, so defaulting and validation get exercised in envtest and on a real cluster instead.

The cost of that shortcut is real and worth naming: since defaulting is skipped locally, an object created during local development has no defaults applied, and behaviour can differ from the cluster. When something works locally and not deployed, missing defaults is the first thing I would check.

9. Packaging

This is what the Operator SDK adds over plain Kubebuilder, and the reason I chose it.

The generated ClusterServiceVersion is worth editing by hand rather than shipping as scaffolded. Three things in it matter:

alm-examples becomes the example CR set users see first, so it should contain a realistic class, a pool, and a claim rather than empty stubs. The required API list should declare KubeVirt and CDI, which makes OLM refuse to install onto a cluster that cannot support the operator, turning my longest prerequisite list into an admission check. And the install mode should be AllNamespaces, since cluster-scoped resources are half the API.

There is also operator-sdk scorecard ./bundle, which checks basic hygiene like whether CRDs have descriptions and status subresources. It catches nothing profound, it costs nothing in CI, and it does catch the small omissions that make an API unpleasant.

10. CI

The generate-check job is the one I would add first. Generated RBAC drifting from the markers in the code produces permission failures at runtime that look nothing like their cause.

11. The order I would build it

Vertical slices, each one demonstrable, because a horizontal approach means nothing works until everything does.

12. What is still open

Honestly, so the next person is not surprised.

The domain hook needs to be written and proven against a real macOS boot before anything else has value, and step 0 exists for exactly that reason. The guest agent's protocol is unspecified beyond the status shape on the API page. Multi-tenancy is unaddressed: quota per namespace, whether classes should be restrictable to particular tenants, and how identities are accounted for. And the workload layer is a sketch, which is intentional, since it should be designed against a machine layer that exists rather than one I imagine.