The DockerIOS operator

Section 01 took Docker-OSX apart. Section 02 established which of its constraints have supported answers and which eight do not. This section specifies the DockerIOS operator.

That operator is not the commercial product. It is the KubeVirt-on-x86 control plane I built to learn the problem, and to keep Intel Macs useful through Apple's 2028 security-update window. The commercial product is MacRack, a separate repository, a separate API domain, and a hypervisor Apple wrote.

What this operator is allowed to be

DockerIOS runs macOS on non-Apple hardware. That is outside Apple's software licence, full stop. I am documenting it as academic work and as a lab control plane for machines Apple is walking away from.

I am not selling it as a VPS. I am not offering it as multi-tenant cloud. If someone takes this design and does either of those things, they are not following this page.

MacRack is where a founder who sells infrastructure should be looking.

The output I still want from these pages is concrete: somebody should be able to read them and start writing the DockerIOS operator, in its own repo, without importing anything from MacRack. Cluster prerequisites, API surface, Operator SDK commands.

The one architectural rule that shapes all of it

DockerIOS is split into two layers, and the split is the most important decision in this section.

The machine layer delivers a running, healthy, addressable macOS instance and knows nothing about what runs inside it. The workload layer configures what runs inside: a GitLab runner, an Xcode toolchain, a signing agent.

I am building the machine layer first, completely, and the workload layer is deliberately empty for now. Every time I was tempted to let the machine layer know about GitLab, I stopped, because that is the decision that turns a platform into a bespoke CI tool.

The pages

Page	What it settles
System architecture	What DockerIOS is as a system. The two layers, the component inventory, the full path from a request to a running macOS instance, exactly which parts of Docker-OSX I reuse and why, and the GPL boundary that reuse forces on the design
Cluster requirements	Everything the cluster must provide before the operator is worth installing. Firmware, kernel command line, kubelet policies, KubeVirt and CDI configuration, CSI capabilities, and the capacity arithmetic that decides how many instances a node can actually hold
The API surface	The CRD design. Five API groups, every resource with its spec and status, the ownership graph, the phase machine and conditions, scoping decisions, and where the workload layer plugs in later
Building with the Operator SDK	The actual build. Scaffolding commands for a multi-group project, the resulting layout, registering external schemes, controller anatomy, RBAC markers, finalizers and indexes, what can and cannot be tested in CI, and packaging as an OLM bundle

Why the Operator SDK rather than a plain controller

I could scaffold this with Kubebuilder alone, and the controller code would be nearly identical, since the Operator SDK is a superset of Kubebuilder for Go projects.

What the SDK adds is the part I do not want to hand-roll: bundle generation, OLM packaging, the scorecard, and a distribution story that lets an operator be installed and upgraded as a versioned artifact rather than a pile of YAML somebody applied once. For something that has to manage stateful, expensive, slow-booting machines, upgrade discipline matters more than it does for a stateless controller.

The standing caveat, now with a destination

Everything in this section is legitimate engineering for a lab and for Intel Macs Apple is leaving. None of it changes the licence. An operator makes it easy to run a hundred of something, which is exactly when a licensing question stops being theoretical.

The product that stays inside the licence is MacRack. Different repo, different API, different hypervisor. This section does not grow a "compliant mode". Compliance is a different operator.