Google Cloud Moves the Compute Engine API to Immutable Date-Based Versions: An FAQ
Compute Engine has been one of the last major cloud APIs where "the API" meant a single, living /v1 surface. Google Cloud has now made date-based versioning of that API generally available: quarterly, immutable snapshots such as 2026-09-01, selected per request with a header or query parameter. New snapshots can change defaults, error formats, and IAM checks without altering what existing pinned callers see. Here's what that actually means for the people who have to operate it.

Figure: Editorial context image from the source page (preview only; rights remain with the publisher) · Credit / further reading: www.infoq.com
Q1. What changed, in one sentence?
Google Cloud's Compute Engine API is now versioned by immutable date snapshots instead of one mutable /v1 surface.
The single endpoint still exists as a compatibility path, but the real contract is now a dated snapshot. Pick a date, get a frozen set of semantics for that date. The model is not novel — Azure Resource Manager and Stripe have shipped this way for years — but applying it to compute infrastructure, where a changed default can rebuild a disk, is a meaningful shift.
Q2. Is /v1 going away?
No. /v1 remains, but it is now a pointer rather than the definition of the contract.
The interesting design question is what /v1 points at. Two possibilities exist and they behave very differently in practice:
/v1tracks the newest snapshot. Unpinned callers get change by default, and pinning is strictly opt-in protection./v1is frozen to a legacy snapshot. Unpinned callers get stability by default, and pinning is opt-in progress.
The summary of the change implies the second: new versions can change behavior "without touching /v1 callers." That is the safer default, and it means the burden shifts onto you to move forward deliberately. Read the docs and confirm which model you're on before assuming anything about when your unpinned traffic starts behaving differently.
Q3. How do you select a version?
Per request, via a header or a query parameter.
That's the important part. Version selection is not a base-URL change (/v1 → /v2), so it is not a code change in the shape of a new SDK import. It can be configuration — an environment variable, a client option, a proxy header. Two services in the same cluster can run against two different snapshots, and a single service can hold a canary percentage on a new snapshot while the rest of its traffic stays pinned. Path-based versioning makes that nearly impossible; header-based versioning makes it routine.
Q4. Why dates instead of v2, v3, or semver?
Because a date is unambiguous, monotonically increasing, and removes the need for a vendor to argue about what counts as "breaking."
Semver works for libraries where the consumer compiles against a frozen artifact. It works badly for hosted APIs, where every caller shares one live implementation and "minor" changes still surprise someone. With dates, the rule is trivial: any behavior change means a new date. And the date tells you how old your pin is at a glance — 2026-09-01 in 2029 is self-evidently stale in a way that v3 is not.
Q5. How does this differ from Azure Resource Manager and Stripe?
Mostly in the default, and the default is where the risk lives.
| Selection | Default if unspecified | |
|---|---|---|
| Azure ARM | api-version query parameter, required on every call |
None — the request fails |
| Stripe | Account-level pin, overridable per request | Account's pinned version |
| Compute Engine (new) | Header or query parameter per request | /v1 behavior |
Azure's mandatory parameter is hostile to newcomers but maximally explicit — you cannot accidentally run unpinned. Stripe's account-level pin is the friendliest: one setting, uniform behavior, per-request escape hatch for special cases. Compute Engine's per-request model with a /v1 fallback is the most flexible and the easiest to leave half-configured.
Q6. What can actually change between snapshots?
According to the announcement: defaults, error formats, and IAM checks.
- Defaults. A field you omitted got value X, and now gets value Y. This is the classic silent breakage: your request JSON is byte-identical, the resource that comes back is not.
- Error formats. Status codes and error body shapes. Retry logic and alerting are usually written against the first error you ever saw from an endpoint and never revisited.
- IAM checks. Permissions that were implicitly tolerated become explicitly denied.
Q7. Isn't changing IAM checks between versions a security problem?
It's the opposite, provided you read release notes before bumping.
Authorization is almost never covered by an API contract test suite. Nobody writes a test asserting "this service account can still do this thing it was never supposed to do." That means tightening IAM is exactly the kind of change that cannot be rolled out safely on a shared mutable surface — it either breaks everyone at once or gets postponed indefinitely. Dated snapshots let Google tighten a check in 2026-09-01 while 2025-06-01 callers keep their old behavior until they choose to move.

Figure: HEXOPS original illustration inspired by the topic (not a copy of the source article imagery) · Credit / further reading: www.infoq.com
Q8. What happens to Terraform, gcloud, and the client libraries?
They choose a version for you, and that choice becomes your migration event.
If a provider release bumps the snapshot it targets, terraform plan after an upgrade is the moment you discover what changed — which is a bad moment, because it lands in the same diff as unrelated infrastructure changes. Two habits help: pin the provider version explicitly, and read the provider changelog specifically for API-snapshot bumps rather than treating it as a routine patch.
Q9. Do pinned versions still get bug fixes and security patches?
They should — "immutable" describes the contract, not the implementation.
A snapshot promises that observable behavior won't change underneath you. It cannot promise that a server-side bug stays broken forever or that a CVE goes unpatched. The distinction to verify in the docs is between contract changes (never in an old snapshot) and correctness/security changes (must land everywhere). The follow-up question worth asking: what is the minimum support lifetime of a snapshot, and is there a published deprecation window?
Q10. How should I migrate?
Pin first, then test, then move one service at a time.
- Inventory implicit callers. Anything using
/v1without thinking about it is your unpinned population. That list is usually longer than expected — cron jobs, one-off scripts, vendor integrations. - Pin explicitly, even if you're not upgrading. Pinning is not a migration; it's making your current behavior legible and owned.
- Capture golden request/response pairs, including error responses. Diff the same suite against the current snapshot and the next one.
- Roll forward per service, not per organization. The per-request model makes this cheap; use it.
- Put the next review date in a calendar, with a named owner.
Q11. Doesn't this create a permanent version-tracking burden?
Yes, and that's the honest trade.
Date-based versioning converts a rare, violent upgrade into frequent, small decisions. That's a good trade for a platform team with dozens of services and bad for a two-person team that will pin once and forget. The failure mode is predictable: an estate of snowflakes each holding different API semantics, and nobody able to say which service is on which date. If you adopt this model, treat the snapshot ID as configuration you own — in code, in review, in a manifest — not as a default you inherited.
Q12. What's the verdict?
Right shape, real overhead, and better than the alternative.
Infrastructure APIs are exactly where silent default changes hurt most, and immutable dated snapshots are the most proven mechanism for making those changes safe and voluntary. The cost is governance: you now have a version number to manage on every surface. Teams that already treat configuration as code will barely notice. Teams that don't will discover the gap the first time a snapshot bump lands in an unrelated pull request.
Sources
- InfoQ — Google Cloud Moves the Compute Engine API to Immutable Date-Based Versions (Steef-Jan Wiggers): https://www.infoq.com/news/2026/11/compute-engine-api-versioning/
- Microsoft Learn — Azure Resource Manager API versioning: https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/versioning
- Stripe — API versioning: https://docs.stripe.com/api/versioning
- Google — AIP-185: Versioning: https://google.aip.dev/185
Disclosure: this article reflects analysis of the published announcement; verify header names, snapshot aliasing behavior, and support windows against current Google Cloud documentation before changing production configuration.



