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, 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 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 newgcloud preview compute command group targets the bundled preview API version. | Keep gcloud updated. Existinggcloud compute ,beta , andalpha scripts continue to work as-is. |
| Terraform (google & google-beta) | The google provider targets stable date-based APIs, whilegoogle-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-specificDiscovery Documents . | 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 computegcloud components update and test upcoming preview capabilities using the new gcloud preview compute surface.