Introducing Compute Engine API multi-versioning: Predictable evolution without breaking production
Google Cloud Blog · 软件开发
Ready to modernize your infrastructure without risking production stability? API multi-versioning for Compute Engine, now in general availability, helps you do just that. With date-based API versions, Compute Engine can now regularly deliver modern API semantics, stronger resilience defaults, and improved developer experience while preserving the rock-solid stability of the
/v1
API.
For more than a decade, the Google Compute Engine
/v1
API has served as the foundational control plane for millions of virtual machines, Google Kubernetes Engine (GKE) clusters, and large-scale AI infrastructure. For platform teams and developers who build on Google Cloud, that single
/v1
endpoint delivered an extraordinary promise: write your integration once, and trust that it will keep running year after year.
Yet as cloud architectures have grown in scale and sophistication, infrastructure teams have faced a growing tension. On one hand, mission-critical production workloads require absolute API stability and strict backward compatibility. On the other hand, customers want faster access to safer security defaults, stronger regional resilience, machine-readable error models, and modern, declarative-friendly APIs, but introducing these improvements in place risks disrupting existing automation. The new versioning model helps avoid that disruption by giving you the flexibility to adopt modern semantics on your own schedule without touching your production workloads.
Date-based API versions for Compute Engine
Historically, Compute Engine relied on
channel-based versioning (CBV)
with three long-lived channels:
/v1
(generally available),
/beta
, and
/alpha
. Because
/v1
was a single, mutable production surface shared by every customer worldwide, any behavioral improvement–even changing a counter-intuitive default or modernizing an error format–carried the risk of breaking existing scripts or required multi-year migrations.
With
interface-based versioning (IBV)
, aligned with Google
AIP-185
, Compute Engine introduces immutable, date-based API snapshots alongside
/v1
:
Stable versions (
YYYY-MM-DD
)
: Released on a predictable
quarterly cadence
(starting with
2026-09-01
), each stable version represents a locked, point-in-time contract of all generally available Compute Engine features and behavioral defaults. Stable versions don't receive breaking changes after they're published. They have no end-of-support date today.
Preview versions (
YYYY-MM-DD-preview
)
: Released on a rapid cadence (such as
2026-10-01-preview
), preview versions branch from a stable parent to give developers early access to upcoming features and API designs, carrying a predictable one-year lifespan for testing and feedback.
Uninterrupted
/v1
support
: The existing
/v1
API remains fully supported and it continues to serve as the default if no date-based version is specified. Your existing applications, scripts, and integrations continue to work without modification.
Primary benefits for builders
1. Stability and customer-controlled upgrades
In a traditional single-version API, changing a default behavior forces a trade-off between platform progress and customer stability. But date-based multi-versioning puts upgrade timing entirely in your hands:
Pin to a known contract
: Direct REST callers and SDK users can lock onto a specific version identifier (such as
2026-09-01
) knowing its request and response schemas are frozen.
Upgrade on your schedule
: When a new quarterly stable version introduces updated defaults or modified resource schemas, your team can evaluate the release notes, test in staging by changing a single version string, and roll out to production at your own pace.
Consistent resource URIs
: Date-based versions continue to use the
/compute/v1/