This post was originally published on this site

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/ 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.

code_block
<ListValue: [StructValue([('code', '# Request a specific date-based stable version using the HTTP headerrncurl -X GET \rn "https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances" \rn -H "Authorization: Bearer $(gcloud auth print-access-token)" \rn -H "X-Goog-Api-Version: 2026-09-01"'), ('language', ''), ('caption', )])]>

2. Safer defaults, stronger resilience, and modern API standards

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).

3. Seamless adoption across client libraries, 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.

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).

Get started

Compute Engine API multi-versioning is available today across all Google Cloud regions, with 2026-09-01 as the initial stable version and 2026-10-01-preview available for preview testing.

Start exploring and adopting date-based versions in your workflows:

  1. Explore the documentation:

  2. Try gcloud preview compute: Run gcloud components update and test upcoming preview capabilities using the new gcloud preview compute surface.