Compute Engine API versioning: pin 2026-09-01 or stay on /v1

Compute Engine API versioning is opt-in. Google announced general availability of date-based versions on 5 November 2026, and any request that names no version still goes to /v1, so nothing in your estate changes today. What you decide is whether to pin 2026-09-01 for its new defaults, and which scripts to test first.

We haven't run these versions against a production fleet. Everything below comes from Google's own documents, linked on each claim, and where the coverage and the source differ we say so.

What Compute Engine API versioning changes, and what it leaves alone

Until now, Compute Engine used channel-based versioning: three long-lived channels, /v1, /beta and /alpha. The new model, which Google calls interface-based versioning, follows AIP-185, where stable versions must be dates in YYYY-MM-DD format and previews must end in -preview. It adds immutable, date-stamped snapshots next to /v1 instead of replacing it.

Item	What Google says
Stable versions	Named YYYY-MM-DD, released quarterly from 2026-09-01. No breaking changes after publication, and "no end-of-support date today".
Preview versions	Named YYYY-MM-DD-preview, such as 2026-10-01-preview. They branch from a stable parent and carry a one-year lifespan.
Selecting a version	The X-Goog-Api-Version header or the $apiVersion query parameter, on the unchanged /compute/v1/ path.
Default	Requests that name no version go to the /v1 endpoint, which remains fully supported.

Pinning is one header on the request Google shows in its announcement:

curl -X GET \
  "https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instances" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "X-Goog-Api-Version: 2026-09-01"

Google's versioning guide says you don't have to migrate: existing requests keep working, but you can't reach new date-based features without moving. That is the whole trade. Stay put and keep the old defaults, or pin and take the new ones.

Three defaults that change when you pin a date-based version

AggregatedList returns partial results by default

In /v1, the returnPartialSuccess parameter defaults to false, so a transient issue in one zone could fail a global list request unless the caller opted in. In date-based versions, Google says partial success is on by default.

That suits a dashboard. It is a behaviour change for anything that treats the list as the complete truth, such as a cleanup job, an inventory reconciliation or a cost report: a call that used to fail loudly can now succeed with gaps. The /v1 response schema includes an unreachables array of strings. We haven't confirmed how date-based versions populate it, so check that your code reads it before it acts on a list. That is our reading, not Google's guidance.

Errors become structured ErrorInfo payloads

Date-based versions return standardised google.rpc.ErrorInfo payloads with a reason, a domain and metadata, which Google says removes brittle regex parsing of error strings. AIP-193 requires every error response to include an ErrorInfo, with the reason in UPPER_SNAKE_CASE and at most 63 characters. Ask for a version that doesn't exist and the metadata lists the supported ones.

The sources we read don't list the reason codes Compute Engine uses. Read them from real responses in staging before you rewrite any retry logic that matches message text.

IAM checks can tighten

Google says new API versions let Compute Engine tighten overly broad legacy IAM permission checks without disrupting legacy automation on /v1. Read the wording carefully: it describes what the model now allows, not a list of checks that tightened in 2026-09-01. Neither Google's post nor InfoQ names the affected permissions. Automation that runs on a service account with a loose role is the thing to review before any later quarterly version arrives.

Where the coverage and Google's own pages disagree

InfoQ reports that /v1 has no end-of-life date. Google's announcement attaches "no end-of-support date today" to the stable date-based versions and says /v1 "remains fully supported". It makes no end-of-life statement about /v1 either way. The versioning guide says stable versions are maintained in perpetuity under the standard Google Cloud deprecation policy, and gives no end date for the older channels.

The honest summary is that no date has been announced, which is not a promise that none will come. InfoQ also notes that Google hasn't said which quarterly versions will contain breaking changes. A pinned version is frozen, but each new quarterly version can introduce updated defaults or modified schemas, so the release notes become required reading at every upgrade.

A checklist before you pin a Compute Engine API version

1. Find out what you call today. Google's guide points to Cloud Audit Logs and to the request headers or query parameters for the version in use.
2. List every global list call. Check whether the code treats an AggregatedList result as complete, and whether it reads unreachables.
3. Search for error-string matching. Anything that greps message text needs to move to reason and domain.
4. Review the roles your automation runs as. Replace broad roles now, while nothing forces the issue.
5. Check how your tooling binds a version. Per Google, each client library release binds to a specific date-based version and keeps the compute_v1 namespace; gcloud compute targets the bundled stable version; the Terraform google provider targets stable and google-beta targets preview, with no version setting in HCL. Taken together, that suggests a routine dependency or provider bump may move you onto a date-based version without any import change. Confirm in each release's notes, and pin your provider and library versions in the lockfile.
6. Test in staging by changing one version string. Google describes exactly this upgrade path. Run it through your CI/CD pipeline so the comparison is repeatable, not a one-off manual check.

When not to pin yet

Stay on /v1 if your automation is stable and nothing you run needs a new feature. Google's guide is explicit that migration isn't required, and a quiet /v1 estate has no deadline attached today.

Wait if you can't yet test list handling and error parsing, because those are the first two items on the checklist above. And keep preview versions out of production: Google's guide says they aren't recommended for mission-critical production, and InfoQ points out that no path from preview to stable has been stated.

Getting a pinned version through staging

The work in this change is small in code and large in coverage: finding every list call, every error parser and every service account that touches the Compute Engine API. If your platform team is weighing a pin and wants a second pair of eyes on a Terraform and automation estate, our AWS, GCP and Azure consulting team can review the list handling, error parsing and role scope with you, and our DevOps and cloud engineering practice can build the staging comparison into your pipeline.