Compute Engine Adds Immutable Date Versions Beside the v1 API

TL;DR

• Compute Engine API multi-versioning is a way to address the same service through several frozen, date-stamped contracts, and it is now generally available in every Google Cloud region.
• Google published the change on 4 November 2026, with 2026-09-01 as the first stable version, 2026-10-01-preview available for testing, and the old /v1 endpoint still the default when no version is named.
• Stable versions ship quarterly, carry a date such as 2026-09-01, and receive no breaking changes after publication.
• Preview versions branch from a stable parent, run on a rapid cadence and carry a one-year lifespan before they disappear.
• The request carries the version selection in the X-Goog-Api-Version header or the $apiVersion query parameter, so the base path stays /compute/v1/ and resource links stay uniform.
• AggregatedList turns on partial success by default in dated versions, and errors arrive as google.rpc.ErrorInfo payloads with a reason, a domain and metadata.
• A platform team pins what it owns: a client library release, a Terraform provider version and a stable date, and tests a preview where it wants early access.

Google Compute Engine has answered to one production endpoint, /v1, for more than a decade, and that endpoint served as the control plane for millions of virtual machines, Google Kubernetes Engine clusters and large AI builds. On 4 November 2026 the Google Cloud blog published the general availability of API multi-versioning, written by software engineer Michael Murstein, which adds immutable date-stamped versions beside the original endpoint.

The new version identifiers let Google evolve defaults and response formats within frozen contracts. A dated contract can carry its own defaults alongside /v1, allowing customers to adopt safer error formats and more resilient list calls on their chosen upgrade schedule.

A date-stamped contract sits beside the decade-old v1

The old model was channel-based versioning: three long-lived channels named /v1, /beta and /alpha, with /v1 acting as a single mutable production surface shared by every customer worldwide. Any behavioural improvement on that surface, even correcting a counter-intuitive default or modernising an error format, risked breaking an existing script or required a multi-year migration.

Interface-based versioning, aligned with Google's AIP-185, keeps those channels and adds immutable snapshots identified by date. The post states the separation precisely: each stable version is a locked, point-in-time contract of every generally available Compute Engine feature and behavioural default, and it receives no breaking changes after publication.

Two properties of that arrangement are worth noting. The date names a contract that includes the defaults, so a team that pins a version also pins behaviour it never configured. And /v1 keeps working as the default, which means an organisation can adopt the model gradually and no estate has to migrate on the day of the announcement.

Stable versions arrive quarterly and hold still

A stable version is written as a plain date, YYYY-MM-DD, and the first one is 2026-09-01. Google releases a new stable version on a predictable quarterly cadence, and the post is explicit that published stable versions do not receive breaking changes and that they have no end-of-support date today.

That combination is the real news. A stable date version with no end-of-support date is a contract an integration can live inside for as long as the customer wants.

The honest caveat sits in the post itself: the sentence says there is no end-of-support date today. Google has left the door open to introduce one later, and any team treating 2026-09-01 as permanent should treat that clause as a warning that the support policy may change.

Preview versions branch from a stable parent

A preview version carries the suffix -preview, appears on a rapid cadence, and the post gives 2026-10-01-preview as the current example. Each preview branches from a stable parent, exists to expose upcoming features and API designs, and carries a predictable one-year lifespan for testing and feedback.

The lifespan is the useful part of the design, because it converts a vague promise into a date a team can plan around. A twelve-month window gives a team time to run a real pilot against a preview surface and sets a firm end date for that pilot, and the post tells customers to use preview SDK releases to test those features.

The risk profile is also clear. A preview is a testing surface by construction, and the one-year clock means anything built on it needs a production path back to a stable date. Teams that pin a preview in production are accepting a migration date they already know.

The request carries the version selection

Version selection is deliberately unglamorous. A caller keeps the /compute/v1/ base URL path and names the version with the X-Goog-Api-Version HTTP header or the $apiVersion query parameter, which the post illustrates with a curl call that passes X-Goog-Api-Version: 2026-09-01.

The benefit is that resource selfLink URIs stay uniform across tools and services. Keeping version selection in the request preserves stable URLs for links stored in runbooks, dashboards and Terraform state files.

Two commands are worth memorising, because they are how most teams actually reach the new surface. The gcloud compute command group targets the bundled stable API version, and the new gcloud preview compute command group targets the bundled preview version.

AggregatedList stops failing when one zone is down

The first behavioural difference the post names is the partial-success default for global list requests. On legacy /v1, calling AggregatedList across all zones and regions leaves returnPartialSuccess at false, so a transient problem in a single zone can fail a global list request unless the caller opted in.

Dated versions enable partial success by default, and the consequence is practical: a fleet query keeps returning the zones that answered while reporting the ones that did not. Anyone who has written a script that tolerated one bad region by retrying the whole call will recognise the improvement.

This is also the clearest example of why the versioning model had to exist. Flipping that default on /v1 would have changed the result of an unknown number of scripts at once, and no responsible platform team does that to a surface shared by every customer.

Errors become fields you can read

The second behavioural change is in error handling. Dated versions adopt google.rpc.ErrorInfo payloads aligned with AIP-193, carrying a structured reason, a domain and contextual metadata, and the post gives the example that matters most during a migration: an invalid version identifier returns the list of supported_versions.

Anyone who has parsed cloud error strings with a regular expression knows the cost of the old approach. A structured reason survives a wording change, a metadata field can be read by a script, and a list of supported versions turns a guessed version name into a correctable mistake.

The post also lists two quieter changes: new versions let Compute Engine tighten overly broad legacy IAM permission checks and introduce safer configuration defaults, and multi-versioning gives Google a clean path to evolve decade-old resource schemas toward its own API improvement proposals.

What a platform team should pin, and where

Pinning happens at four places, and each one has its own answer in the post. A client library release binds to a specific date-based API version automatically while keeping the /v1 package namespace, so upgrading the dependency is the whole action. The google Terraform provider targets stable dated APIs while google-beta targets previews. The gcloud CLI splits into gcloud compute for stable and gcloud preview compute for preview. A direct REST caller passes the header or the query parameter.

A workable policy follows from that list. Pin the client library and Terraform provider releases that carry the stable API you need, record their target date next to the deployment, and keep preview work on a separate pipeline whose output nobody depends on. Change one version string in staging, compare the response schemas and the defaults, then move production.

The migration is also a documentation exercise. Defaults that used to be implicit, such as the partial-success behaviour of a global list call, now depend on the version a request names, and a runbook that omits the version is a runbook that describes a moving target.

Teams that run their own automation against cloud control planes should use this discipline for self-managed infrastructure: know which contract you depend on and write the date down. The versioning model is documented in the cited Google Cloud announcement.

Sources

• Introducing Compute Engine API multi-versioning: Predictable evolution without breaking production, Google Cloud Blog, cloud.google.com, 2026-11-04
• AIP-185: API Versioning, Google API Improvement Proposals, google.aip.dev, read 2026-11-04

Source: the Google Cloud blog post of 4 November 2026 as rendered on the captured page, read in full on 4 November 2026. The channel-based and interface-based versioning models, the stable and preview cadences, the first stable version, the header and query parameter, the partial success default, the ErrorInfo payload, the IAM and schema notes, and the client library, gcloud and Terraform mappings all come from that post. The pinning policy and the documentation advice are Netics analysis.