DEV Community

NTCTech
NTCTech

Posted on Originally published at rack2cloud.com

VM API Makes VM Configuration More Portable. It Doesn't Make Operations Portable

Field Notes — Engineering Notes from the Complexity Gap | Rack2Cloud

VM API portability is a claim about the shape of a VM definition, not about what a provider does once it accepts one. VM API, a CNCF Sandbox project accepted on October 28, 2026 (Broadcom announced it on November 9), defines a common Kubernetes-style resource for describing a virtual machine across platforms. A portable manifest shape means two platforms can interpret the same fields. It does not mean the values in those fields—an image reference, a network name or a failure-domain string—resolve to equivalent resources on both.

VM API portability: shared manifest contract above, provider-defined scheduling, availability, migration and recovery below
The contract is common. The behavior underneath is provider-defined.

That distinction matters more after November 16, when a maintainer answered a question in Issue #13 that a KubeVirt contributor opened on November 4. The reply is a project statement, not a specification amendment, and the thread remains open. It is still the clearest public account of what the project does and does not intend to define. Comments on November 18 and 19 show the boundary is still being contested: a KubeVirt contributor asks that it not be documented as settled while an early-stage KubeVirt proposal (kubevirt/enhancements#525, which I have not read) is examined.

This is an architecture decision, not a project announcement: what a common VM API makes portable, what it leaves provider-dependent, and what you must prove yourself before treating two platforms as interchangeable.

VM API Portability Starts at the Manifest

The contract is vm-api.io/v1alpha1. The README describes it as the current served and storage version, and says additional versions would need an explicit compatibility design. Maturity indicators, as the repository states them: an alpha version, with the README calling API evolution and provider compatibility active development areas, and capability discovery, a shared conformance suite and documented provider support levels all listed as roadmap items rather than shipped features. I found no compatibility guarantee for the alpha API in the README, roadmap or docs.

What the spec does define is a consistent set of fields. Table 1 splits the VM API portability surface by what is common and what each provider still defines.

Table 1: Where the contract is common and where it stops

Layer Fields Common across providers Provider-defined
Configuration shape instanceType.name, instanceType.resources{cpus,memory}, bootDisk, disks[], sshPublicKeys, bootstrap.cloudInit The field names and structure What an instance type name maps to; whether inline CPU and memory sizing is supported at all
References bootDisk.source{image,snapshot,blank}, network.interfaces[].network, storageClassName That a reference exists in the spec What the reference resolves to; the README says image and network references need provider-specific resolution and defines no companion catalog resources
Admission powerState, infrastructureRef, boot-disk source, storage class and disk size Declared enum, immutability and grow-only constraints Provider capability gaps are not necessarily admission failures; some are reported through conditions after admission
Execution scheduling.spot, failureDomain, network.interfaces[].publicIP, tags The fields exist failureDomain is an opaque string each provider interprets; scheduling.spot is a spot-capacity request (the source calls it placement economics), not scheduling control, and may be unsupported; external addresses and tag values may be unsupported or rejected provider-side
Lifecycle status ready, powerState, providerID, addresses, conditions, providerMetadata The declared status fields and condition vocabulary, excluding providerMetadata; not proof of uniform condition semantics What each condition means in practice; providerMetadata contents are entirely provider-defined

The Admission row reflects rules declared in the API source comments and validation markers at 4d17e64, not verified controller enforcement.

The shape is shared. The values and the behavior behind them are not. A manifest that applies cleanly on two providers has told you the two providers parse the same document. It has told you nothing about whether the resulting VMs behave alike.

Providers Keep Control of Scheduling, HA and Live Migration

Issue #13 is the central evidence for where that line sits. As the maintainer's reply puts it, VM API targets platforms whose VM runtime sits outside KubeVirt's pod-and-node model. Providers keep scheduling, high availability and live migration. KubeVirt can itself be a provider. The API deliberately exposes less than KubeVirt does. The reply also proposes a documentation statement that KubeVirt is the API for VMs running as workloads on Kubernetes nodes.

That is a scoping statement about VM API portability, not a defect, and it is consistent with the repository's roadmap, which says the project does not implement a hypervisor or transfer running VM state and disks between providers. If you already run KubeVirt, the role Kubernetes plays relative to the virtualization layer is a separate question from what VM API defines.

The reporting model behind VM API portability has three stages, and treating them as one is the usual mistake.

Manifest validity. Per the comments and validation markers in the API source at commit 4d17e64, admission rejects only what can never be valid: an out-of-range powerState, or a change that violates an immutability or grow-only rule. I did not inspect the generic controller, so this describes what the API types declare, not what any controller enforces.

Provider acceptance. Some capability gaps are admitted and reported through conditions rather than rejected at admission. Per the source comments, Suspended, inline CPU and memory sizing, spot and external addresses are examples reported through the UpToDate condition with reason UnsupportedByProvider. Tag values are the careful case: the API says a provider rejects values it cannot represent. I am not claiming every unsupported creation is accepted and later rejected, and the condition reasons in the source are not presented as exhaustive.

Operational completion. Pending changes surface through reasons such as RequiresPowerOff, RateLimited and WaitingForCapacity. Two examples carry the point. An EBS volume resize is RateLimited by a cooldown the source comments measure in hours. A spot VM can be reported as Preempted. On platforms where termination also removes attached disks, the consequences extend beyond interruption: recovery may require rebuilding the VM and restoring its data. UpToDate, Ready and InfrastructureReady are separate conditions and are not interchangeable. Operators should inspect the condition and its reason rather than treating a single healthy-looking status as proof that the requested operation completed successfully.

A VM that is valid, accepted and complete on one provider has passed three different tests. Another provider can pass the first and fail the other two with no change to the manifest.

Three stages for a VM API request: manifest validity, provider acceptance, operational completion, each reported separately
Valid, accepted and complete are three separate tests.

Proving Operational Interchangeability Requires More Than a Matching Manifest

Table 2 lists the operational responsibilities whose behavior remains provider-dependent and the proof an operator owes for each.

Table 2: Responsibilities outside the contract

Responsibility Where it lives What the operator must prove
Placement Provider; failureDomain is opaque Each provider's failure-domain semantics, and the actual isolation boundary behind them
Availability Provider HA Behavior on host loss, measured per provider
Migration Provider live migration; VM API does not move running state between providers Supported migration paths, downtime, application impact and failure behavior, per provider
Change execution Provider, surfaced through conditions Time and disruption of a resize, a power-state change, a spot reclaim
Performance Provider implementation and workload behavior The same workload, under a comparable load profile, meets defined latency, throughput and resource requirements on each provider
Recovery Not addressed by the contract That a lost VM is restored on each platform within the workload's recovery time and data-loss objectives

The table implies a test program for VM API portability, not a single manifest replay. Start by applying the same configuration intent to each provider, recording admission results and UpToDate conditions, and resolving every image and network reference to its provider-specific resource. Then map each provider's failure-domain semantics and verify the actual isolation boundary. Induce a host failure and measure availability behavior. Exercise each provider's supported migration and maintenance paths within that platform, recording downtime, application impact and failure behavior. Execute a resize and a power-state change, then test capacity shortfall and, where spot is used, reclaim. Record completion time, disruption and workload performance, including latency, throughput and resource consumption against the requirements you defined. Finally, restore a lost VM and measure recovery against the workload's RTO and RPO.

This research did not identify a published cross-provider conformance suite for the API. The README lists a shared conformance suite as a roadmap item. Such a suite could test conformance to the API contract; it would not, by itself, establish equivalent availability, migration, performance or recovery outcomes.

The operator rule: do not treat two platforms as operationally interchangeable until the same workload, under comparable operating conditions—and equivalent failure conditions where relevant—meets the same defined availability, recovery and performance requirements on both. Different mechanisms can deliver equivalent guarantees: live migration on one platform, restart on another, application-level failover on a third. Matching manifests establish a common configuration interface, which is what VM API portability covers. They do not establish equivalent operational guarantees. The same gap appears in estate-wide operational parity: individual platforms can report healthy while nothing measures whether their operational outcomes agree.

Three recovery mechanisms, live migration, restart and application failover, each measured against the same workload requirement
_Equivalent guarantees can come from different mechanisms.
_

Evidence Gaps and Known Project Limitations

Claims about VM API portability need two separate lists: what this research could not establish, and what the project itself states.

EVIDENCE GAPS — WHAT THIS RESEARCH DID NOT ESTABLISH

  • Generic controller behavior was not inspected.
  • kubevirt/enhancements#525 was not read; it is known only from comments in Issue #13.
  • This research did not establish a current provider support matrix or provider-specific support levels.
  • Practical use of providerMetadata remains unverified.
  • No complete provider inventory was established.

KNOWN PROJECT LIMITATIONS — AS THE REPOSITORY STATES THEM

  • The API remains at v1alpha1; the README calls API evolution and provider compatibility active development areas, and no compatibility guarantee is stated.
  • Image and network references require provider-specific resolution.
  • Capability discovery, documented provider support levels and a shared conformance suite are roadmap items.
  • A portable accelerator field is planned, per the README, and is not currently available.

Architect's Verdict

VM API gives operators a common place to express VM configuration intent. That makes VM API portability a narrower claim than "portable VMs."

What the contract defines is the shape of the request and the vocabulary for reporting what happened. What it leaves with providers is the part that decides whether your workload survives: placement, availability, migration, change execution and recovery. The project maintainer describes this boundary directly, and the API design is consistent with that explanation.

Treat the manifest as the cheap half of VM API portability. The expensive half is evidence: the same workload, under equivalent failure conditions, meeting the same defined requirements on each platform you intend to substitute for another. Even when capability discovery and conformance tooling ship, operators will still need to validate workload-specific requirements. A shared manifest tells you two platforms speak the same configuration language. It does not tell you whether each meets your availability, recovery and performance requirements.

Portability of configuration is a design property. Portability of operations is something you observe.

Additional Resources


Originally published at rack2cloud.com

Top comments (0)