Introducing Compute Engine API multi-versioning: Predictable evolution without breaking production

Google Compute Engine's API multi-versioning is now generally available, adding immutable date-based API snapshots alongside the existing /v1 endpoint, with the first stable version, 2026-09-01, due on a quarterly cadence. The model, aligned with Google AIP-185, lets direct REST callers and SDK users pin to a frozen contract via the X-Goog-Api-Version header or $apiVersion query parameter while /v1 remains fully supported and the default when no version is specified. Preview versions such as 2026-10-01-preview branch from a stable parent with a one-year lifespan, and date-based versions keep the /compute/v1/ base URL path so resource selfLink URIs stay uniform.

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. 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 https://google.aip.dev/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. 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/ base URL path. You specify the target version via the X-Goog-Api-Version HTTP header or the $apiVersion query parameter. This means that resource selfLink URIs remain uniform across tools and services. By isolating behavioral changes to new date-based versions, Compute Engine is delivering improvements that make cloud applications more resilient, more secure, and easier to automate: Resilient global queries by default : In legacy /v1 , calling AggregatedList across all zones and regions defaults returnPartialSuccess to false . This means a transient issue in a single zone could cause a global list request to fail unless callers explicitly opted in. In new date-based versions, partial success is enabled by default so global fleet queries remain resilient during localized maintenance or disruptions. Actionable, machine-readable errors AIP-193 : Date-based versions adopt standardized google.rpc.ErrorInfo https://google.aip.dev/193 payloads with structured reason , domain , and contextual metadata such as returning the list of supported versions if an invalid version identifier is requested , eliminating brittle regex parsing of error strings. Stronger security and least-privilege hygiene : New API versions allow Compute Engine to tighten overly broad legacy IAM permission checks and introduce safer configuration defaults without disrupting legacy automation running on /v1 . Cleaner, declarative-friendly API design : Multi-versioning provides a clean path to evolve complex, decade-old resource schemas toward modern Google API Improvement Proposals AIPs . gcloud , and Terraform Whether you call the REST API directly or manage infrastructure through higher-level tools, Compute Engine API Multi-Versioning is designed to work without friction: | Surface | How multi-versioning works | Your responsibility | | Client libraries Python, Go, Java, Node.js, C , Ruby, PHP | Each SDK release automatically binds to a specific date-based API version while preserving the /v1 package namespace compute v1 , apiv1 . Enums are represented as strings for seamless forward and backward compatibility. | Upgrade your client library dependency as usual– no import path rewrites required . Use -preview SDK releases to test preview features. | | Google Cloud CLI gcloud | gcloud compute targets the bundled stable API version. The new gcloud preview compute command group targets the bundled preview API version. | Keep gcloud updated. Existing gcloud compute , beta , and alpha scripts continue to work as-is. | | Terraform google & google-beta | The google provider targets stable date-based APIs, while google-beta targets preview APIs under the hood. | Upgrade your Terraform provider version to adopt new features; no manual API version configuration needed in HCL scripts. | | Direct HTTP / REST | Select any active version via -H "X-Goog-Api-Version: YYYY-MM-DD" or ?$apiVersion=YYYY-MM-DD , and fetch version-specific Discovery Documents https://www.googleapis.com/discovery/v1/apis/compute/2026-09-01/rest . | Pass the header or query parameter in your HTTP client to opt into a specific version e.g., 2026-09-01 , 2026-10-01-preview . | Compute Engine API multi-versioning is available today across all Google Cloud regions, with 2026-09-01 2026-10-01-preview Start exploring and adopting date-based versions in your workflows: Explore the documentation : Compute Engine API Versioning Guide https://docs.cloud.google.com/compute/docs/api/how-tos/api-versioning-guide Creating API Requests and Handling Responses https://docs.cloud.google.com/compute/docs/api/how-tos/api-requests-responses Compute Engine REST API Reference https://docs.cloud.google.com/compute/docs/reference/rest/v1 use the version selector to inspect 2026-09-01 and 2026-10-01-preview schemas Try gcloud preview compute gcloud components update and test upcoming preview capabilities using the new gcloud preview compute surface.