Google Cloud adopts immutable date-based versions for the Compute Engine API

What changes in the Compute Engine API

As of November 14, 2026, Google Cloud offers multi-versioning for the Compute Engine API in all regions, according to InfoQ. Alongside the historic /v1, there are now stable versions identified by date, in the YYYY-MM-DD format, released every quarter. The first one is 2026-09-01; the most recent preview version, 2026-10-01-preview, is also already available.

Preview versions carry the -preview suffix and have a one-year lifespan. The API path stays the same, /compute/v1/: whoever wants a specific version sets the X-Goog-Api-Version header or the $apiVersion query parameter. A call that specifies no version at all still falls back to /v1, which Google has not announced a deactivation date for.

Why /v1 became a problem

Software engineer Michael Murstein, author of the announcement on the Google Cloud blog, explains that /v1 was a single, mutable surface, shared by every API client in the world.

a single, mutable production surface shared by every customer worldwide

Michael Murstein, software engineer, Google Cloud

Any behavior improvement on that surface, even swapping a counterintuitive default or modernizing an error format, risked breaking existing scripts or required years-long migrations. The replacement is what Google calls interface-based versioning, aligned with its own AIP-185, which requires stable versions to be dates and previews to have an expiration date. Each stable version is a locked snapshot of every resource and default available on that date: once published, it receives no change that breaks behavior.

The three differences already visible

The announcement lists three concrete changes that whoever switches versions will notice:

• Partial result default: in /v1, AggregatedList only returns partial results if the call sets returnPartialSuccess; in dated versions, this behavior now comes enabled by default, so a failing zone no longer brings down the entire fleet query.
• Structured error: the error body now becomes google.rpc.ErrorInfo, with reason, domain, and metadata; requesting a version that doesn't exist returns, in metadata, the list of versions that do exist.
• Stricter permissions: according to Murstein, the new versions allow tightening legacy, overly broad IAM checks, adopting safer configuration defaults, and starting to move ten-year-old resource schemas toward Google API Improvement Proposals. Automation locked to /v1 gets none of this.

What changes in the tools the team already uses

Those who call the API directly are a minority: most people will feel the change through the libraries and tools they already use, without touching any header.

Each client library release for Python, Go, Java, Node.js, C#, Ruby, and PHP now targets a specific dated version, keeping the same compute_v1 and apiv1 namespaces: no import path changes. -preview SDK releases target the preview versions. gcloud compute points to the bundled stable version, and a new gcloud preview compute group points to the preview; existing scripts with compute, beta, and alpha keep working unchanged. In Terraform, the google provider targets stable versions and google-beta targets preview, with no need to declare a version in HCL. Discovery documents are published per version.

Google arrives last among the three big clouds

With this release, Google is the last of the three largest cloud providers to let API callers choose the version per request.

Google's quarterly cadence sits between Azure's per-service pace and Stripe's monthly pace. Unlike Stripe, however, Google hasn't said which quarterly versions will bring behavior changes relative to the previous one.

What remains open

The announcement doesn't give an end-of-life date for /v1, nor a formal path for a preview version to become stable. There's also no complete list of behavior differences between /v1 and 2026-09-01 beyond the three examples cited, nor a stance on whether other Google Cloud APIs will adopt the same scheme. The /beta and /alpha channels aren't mentioned in the material.

For those running GCP infrastructure in Brazil

Those who provision Compute Engine via Terraform, gcloud, or one of the official client libraries don't need to do anything right away: the tool already decides the version behind the scenes. In short: the risk is concentrated among those who call the REST API directly, with curl or a custom HTTP client, without a fixed version, because those calls remain stuck on /v1 and don't get the new defaults or the stricter IAM protection.

It's worth testing the new returnPartialSuccess default before migrating: teams that rely on an AggregatedList query failing completely when a zone is down (to trigger an alert, for example) may have that behavior silently changed when switching versions. Likewise, reviewing the IAM permissions the team granted for Compute Engine automation before adopting 2026-09-01 avoids surprises when Google tightens legacy checks. For those already testing the 2026-10-01-preview preview version, it's worth remembering the one-year validity period and following Google Cloud's official channel to know when it stops existing.

Source

InfoQ: Google Cloud Moves the Compute Engine API to Immutable Date-Based Versions, by Steef-Jan Wiggers, November 14, 2026.