Compute Engine API multi-versioning is now generally available, introducing immutable date-based stable versions on a quarterly cadence starting with 2026-09-01. The existing /v1 API remains fully supported as the default, while new stable and preview versions let teams adopt safer defaults, resilient global queries, and machine-readable errors on their own schedule without touching production workloads.
From channel-based to interface-based versioning
Compute Engine historically used channel-based versioning with three long-lived channels: /v1 for general availability, /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.
The new interface-based versioning model, aligned with Google AIP-185, introduces immutable date-based API snapshots alongside /v1. Stable versions use a YYYY-MM-DD format and are released on a predictable quarterly cadence, each representing a locked point-in-time contract of all generally available Compute Engine features and behavioral defaults. Stable versions do not receive breaking changes after publication and have no end-of-support date today.
Preview versions use a YYYY-MM-DD-preview format and branch from a stable parent to give developers early access to upcoming features and API designs. Preview versions carry a predictable one-year lifespan for testing and feedback. The existing /v1 API remains fully supported and continues to serve as the default when no date-based version is specified.
Customer-controlled upgrades and safer defaults
Date-based multi-versioning puts upgrade timing entirely in customer hands. 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. When a new quarterly stable version introduces updated defaults or modified resource schemas, teams can evaluate release notes, test in staging by changing a single version string, and roll out to production at their own pace.
Resource URIs remain consistent across versions. Date-based versions continue to use the /compute/v1/ base URL path, with the target version specified via the X-Goog-Api-Version HTTP header or the $apiVersion query parameter. This means resource selfLink URIs remain uniform across tools and services, avoiding the need to rewrite integration code when switching versions.
New date-based versions deliver improvements isolated from /v1. Resilient global queries now enable partial success by default for AggregatedList calls, so a transient issue in a single zone no longer fails a global fleet request. Standardized google.rpc.ErrorInfo payloads with structured reason, domain, and metadata fields replace brittle regex parsing of error strings. Overly broad legacy IAM permission checks are tightened and safer configuration defaults are introduced without disrupting legacy automation on /v1.
Seamless adoption across client libraries, gcloud, and Terraform
Client libraries for Python, Go, Java, Node.js, C#, Ruby, and PHP automatically bind to a specific date-based API version while preserving the /v1 package namespace such as compute_v1 or apiv1. Enums are represented as strings for seamless forward and backward compatibility. Upgrading the client library dependency adopts the new version with no import path rewrites required, and preview SDK releases are available for testing preview features.
The Google Cloud CLI bundles a stable API version for gcloud compute commands, while the new gcloud preview compute command group targets the bundled preview API version. Existing gcloud compute, beta, and alpha scripts continue to work as-is. Teams simply keep gcloud updated to receive new stable versions automatically.
The Terraform google provider targets stable date-based APIs under the hood, while google-beta targets preview APIs. Upgrading the Terraform provider version adopts new features with no manual API version configuration needed in HCL scripts. Direct HTTP and REST callers select any active version via the X-Goog-Api-Version header or $apiVersion query parameter and can fetch version-specific Discovery Documents.
What to do next
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 for preview testing. Start by reviewing the API Versioning Guide, then test gcloud preview compute after updating components, or pin a REST call to 2026-09-01 using the X-Goog-Api-Version header to validate the new defaults in staging.
Source: Introducing Compute Engine API multi-versioning: Predictable evolution without breaking production (GCP).
