feat(vmpool): add VirtualMachinePool for group VM management

[fl64]

Description

DVP has no primitive to manage a group of identical virtual machines whose count changes over time. Every "I need N identical VMs and the number varies" scenario — CI runner fleets, VDI desktop pools — has to be solved with orchestration outside the platform: users write their own controllers/scripts to create and delete VirtualMachines, watch their number, recreate lost ones and clean up their disks. This duplicates logic and is error-prone around races and node failures.

This PR introduces VirtualMachinePool (paid editions only, EE/SE+): a namespaced resource that declaratively keeps a requested number of identical VMs and integrates with kubectl scale, HPA and KEDA through the standard scale subresource. Its template is an ordinary VirtualMachineSpec, so a replica is no different from a manually created VM.

The feature is complete and covers:

• Replica management — keeps the requested number of identical VMs, replaces lost ones, and reports state in status (replicas, readyReplicas, selector, conditions). It is cache-lag-safe (ReplicaSet-style expectations), so a lagging informer cache cannot double-create replicas.
• Scale-down policy — NewestFirst / OldestFirst choose which replica leaves on anonymous scale-down via scale; Explicit forbids anonymous shrink through a webhook, so for "busy" workloads (CI runners, VDI) replicas can only be removed by address.
• Addressed removal — the scaleDownWith subresource deletes named replicas and shrinks the pool by that count, instead of letting the controller pick victims.
• In-place template propagation — editing the template rolls the change out to existing replicas; disruptive changes wait for a restart and are surfaced via status.restartPendingReplicas.
• Reusable disks — per-replica disks are described in virtualDiskTemplates with a reclaim policy: Delete disks belong to the VM and are removed with it; Retain disks belong to the pool, outlive the replica and are reused on the next scale-up, with an optional warm buffer (keep) and TTL garbage-collection.

The resource is available only in paid editions, gated behind the VirtualMachinePool module feature gate (default off, locked off in CE). The API/CRD installs in every edition, but the controller self-gates on the feature gate, so the resource does nothing in CE.

Why do we need it, and what problem does it solve?

Two mass scenarios suffer most: CI/CD runners (GitLab Runner autoscaling expects a backend that can "give me N more" and reclaim idle ones) and VDI pools (warm desktops that self-heal on node failure). Without a group primitive, DVP cannot serve these natively and each team reinvents the orchestration, usually with bugs in race and failure handling. VirtualMachinePool gives users a native, declarative backend for autoscaling fleets of VMs without writing their own replica controller, and lets heavy per-replica disks be reused across scale cycles instead of rebuilt every time.

What is the expected result?

With the VirtualMachinePool feature gate enabled (EE/SE+):

1. Create a pool with spec.replicas: N, a spec.virtualMachineTemplate and spec.virtualDiskTemplates — the controller converges the number of VirtualMachines to N, each with its own disks (the first disk template is the boot device).
2. kubectl scale virtualmachinepool/<name> --replicas=M (or HPA/KEDA) scales the pool; scaleDownPolicy decides which replicas leave, or forbids anonymous shrink for Explicit.
3. scaleDownWith removes specific replicas and shrinks the pool by that count; a plain kubectl delete vm is treated as a lost replica and replaced.
4. A member in Stopped is kept, not duplicated.
5. Editing the template propagates to replicas; disruptive edits wait for a restart (status.restartPendingReplicas).
6. Retain disks freed on scale-down are reused on the next scale-up instead of being recreated; deleting the pool cascades its replicas and pool-owned disks.
7. .status reports replicas / readyReplicas / updatedReplicas / restartPendingReplicas, the selector, and the Available / Progressing conditions.

Checklist

• The code is covered by unit tests.
• e2e tests passed.
• Documentation updated according to the changes.
• Changes were tested in the Kubernetes cluster manually.

Changelog entries

section: vmpool
type: feature
summary: "Add VirtualMachinePool (EE/SE+) for declarative group management of virtual machines, scalable via the standard scale subresource, HPA and KEDA."
impact_level: low

[yaroslavborbat]

This function doesn't add any clarity. I'd prefer to remove it. It's not clear why this controller becomes EE or CE because of it, so you have to dig deeper into the code to understand what's happening.

[fl64]

Done — removed the wrapper; the pool controller and scale webhook are now set up inline in main.go like every other controller.

[yaroslavborbat]

We use the Connecter interface in the VM because we are proxying requests and streams to another API server. There is no need for you to do this. Please consider the Creater interface instead

[fl64]

Done in 558b4b2 — switched to rest.NamedCreater. No proxying here, so no need for Connecter.

[yaroslavborbat]

Should we install the resources here only if the featureGate is enabled?

[fl64]

Done — served only in paid editions. The runtime VirtualMachinePool gate isn't wired into the apiserver process, so I gate by the compiled-in edition; the CRD and controller still enforce the runtime gate.

[fl64]

Correction after cluster testing: gating this by edition was wrong. The virtualization-api binary is built without -tags MODULE_EDITION and doesn't wire in the feature gate, so inside the apiserver version.GetEdition() is always CE and the gate reads compile defaults — the edition check silently dropped the subresource in every build (endpoint 404'd in the cluster). Fixed in a3129e4: register unconditionally; availability is enforced upstream by the CRD install and the self-gating controller. Verified in-cluster (endpoint back, verb create) + e2e green.

[yaroslavborbat]

It doesn't look quite right. We created vmStorage and passed it in, but for vmPoolStorage we only passed the dependencies needed to create it

[fl64]

Done — pool storage is now constructed in Install and injected, the same way vmStorage is.

[yaroslavborbat]

Let's not return NotFound. Instead, let's return it for the resource, similar to how we do it for vm.

[fl64]

Done — returns NewNotFound scoped to the resource, same as vm.

[yaroslavborbat]

I would prefer using a typed generated client over the controller-runtime client. Also, for VMs we create a separate cache. Is it needed for the pool as well?

[fl64]

Done — now uses the generated typed clientset. No separate cache for the pool: reads go straight to the API, since scaleDownWith is a rare validate-before-delete mutation where a cache would only risk stale membership.

[yaroslavborbat]

We prefer to describe Create, Update, and Delete operations separately. Take a look at how the webhooks are implemented in other packages

[fl64]

Operations are now dispatched explicitly and the update path is split out. It stays a raw admission handler (not a CustomValidator) because it guards the scale subresource, whose request object is an autoscalingv1.Scale — the builder's typed validator decodes the parent VirtualMachinePool and can't target a subresource path.