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.

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.

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.

_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#525was 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
providerMetadataremains 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
- Virtualization Architecture — the pillar covering hypervisor, control-plane and operating-model decisions this question sits inside.
- Virtualization Control Plane Architecture — the learning-path stage on how responsibility is split between platform and provider layers.
- Kubernetes Did Not Replace Virtual Machines — It Changed Their Role — why Kubernetes owns application placement while the infrastructure layer keeps its own job, a comparable split to the one Issue #13 draws for KubeVirt.
- Operational Parity Is Becoming The Real Virtualization Challenge — the estate-level condition where individual platforms can report healthy while nothing measures whether their operational outcomes agree.
- VM API Issue #13, maintainer reply — the project statement on scope relative to KubeVirt.
- VM API repository, commit 4d17e64 — the README, ROADMAP and API types this post reads.
- Broadcom Contributes VM API Open Source Project to the Cloud Native Computing Foundation — the November 9 announcement of the Sandbox acceptance.
- CNCF project page for VM API — the Sandbox acceptance record, dated October 28, 2026.
Originally published at rack2cloud.com

Top comments (0)