Compute Engine versioning guide: APIs, client libraries, and tools

This guide explains how Compute Engine manages versions across REST APIs, client libraries, and the gcloud command-line tool. It describes the difference between channel-based versioning (CBV) and interface-based versioning (IBV), while focusing primarily on the latter.

Before you begin

  • If you haven't already, set up authentication. Authentication verifies your identity for access to Cloud de Confiance by S3NS services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:

    Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Cloud de Confiance console to access Cloud de Confiance by S3NS services and APIs, you don't need to set up authentication.

    gcloud

    1. Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity. After signing in, initialize the Google Cloud CLI by running the following command: 

      gcloud init
    2. Set a default region and zone.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, and then sign in to the gcloud CLI with your federated identity.

    For more information, see Authenticate for using REST in the Cloud de Confiance authentication documentation.

Channel-based versioning and interface-based versioning

The Compute Engine API supports two versioning schemes: channel-based versioning (CBV) and interface-based versioning (IBV).

  • In channel-based versioning, releases are long-lived and receive in-place updates. Compute Engine supports v1, beta, and alpha channels.

  • In interface-based versioning, individual interfaces, methods, and resources are versioned, and can evolve incrementally and independently.

IBV supersedes CBV. However, existing implementations of CBV are unaffected by the introduction of IBV and by new versions. You can continue to use CBV if you prefer to stay on the existing API release.

IBV helps you trust that the behavior of the API, and its request and response payload, conform to an intended API version. You use IBV by specifying an API version in your request, using either a query parameter or a header. For more information, see Create an API request.

Using IBV provides the following benefits:

  • Increased stability: IBV protects running applications from change by allowing you to indicate the API version with which the service must respond.
  • Control over change adoption: with IBV, you choose which version serves your request. This lets you upgrade to new service features on your own schedule.

For more information about versioning strategies, see API improvement proposal 185.

Interface-based versioning policy

Every release of the Compute Engine IBV API is a collection of interface changes that share the same service version, even though interfaces might change version independently.

Compute Engine IBV API supports stable and preview versions.

Stable versions

Most API releases are stable versions. Stable versions maintain strict compatibility, as defined in AIP-180, meaning newer stable releases of the same version don't break existing functionality or require code rewrites.

Compute Engine identifies stable API versions using standard dates in the YYYY-MM-DD format (such as 2026-09-01). Later dates indicate newer releases.

Compute Engine supports stable versions over long timeframes so your production systems remain reliable and uninterrupted. For most applications, you only need to use a single stable version to perform your daily tasks.

Preview versions

Compute Engine can release preview versions to gather early user feedback on new features. Preview releases append a -preview tag to the date (such as 2026-10-01-preview).

Preview versions include all capabilities from the latest stable release, plus newly added experimental features. Keep the following in mind when using preview versions:

  • Preview features don't guarantee compatibility with earlier or future releases.
  • We don't recommend using preview versions for mission-critical production environments.
  • We may change, refine, or remove preview features while promoting them to a stable release.

Use preview versions when you want to experiment with new capabilities, and plan to update your code when a stable version launches.

Specify an API version in the request

To make API calls using IBV, your requests specify a target version by using either a query parameter or a header. For examples on how to make API requests, see Create an API request.

Cloud Client Libraries

Cloud Client Libraries remove the burden of building and parsing raw REST calls. Each library release connects directly to a specific date-based API version.

To access new features, update your Cloud Client Libraries package to the latest release. We publish updated Cloud Client Libraries alongside new stable and preview API releases.

We recommend running production applications on stable Cloud Client Libraries, while isolating preview libraries to testing environments.

Google Cloud CLI (gcloud)

The gcloud CLI lets you manage Compute Engine resources without having to track individual REST endpoints manually.

The gcloud CLI divides commands into two categories:

  • Stable commands: standard commands (such as gcloud compute instances create) target stable API versions. These commands are fully supported, predictable, and recommended for production scripts.
  • Preview commands: early-access features use the gcloud preview group (such as gcloud preview compute ...). These commands show a brief warning because contracts can change before final release.

Terraform

The Cloud de Confiance by S3NS Terraform Provider abstracts API versioning and manages underlying API interactions. Terraform configurations don't expose or require manual version header settings.

To access new features, update your Cloud de Confiance by S3NS Terraform Provider to the latest release. For preview features, use the google-beta provider.

Frequently asked questions

This section answers frequently asked questions about Compute Engine API versioning.

  • Do I have to migrate from v1 (CBV) to IBV?

    No, existing CBV v1 API requests continue to work as before. However, you won't be able to access new features available in IBV API.

  • How long will an IBV API version be supported?

    Stable versions are maintained in perpetuity under the standard Cloud de Confiance by S3NS deprecation policy.

  • How frequently are new IBV API versions released?

    New IBV API versions are planned with quarterly releases. Preview versions can be released at any time.

  • Do I need to enable anything in Cloud de Confiance console?

    No, IBV API is enabled by default with Compute Engine API.

  • What happens if I don't specify a version in my request?

    Your request defaults to the CBV v1 endpoint.

  • Where can I can find the API version in Cloud Audit Logs entries?

    The API version is logged in the protoPayload.requestMetadata.callerSuppliedUserAgent and in the request headers or query parameters.

What's next

To learn more about the Compute Engine API, read the following documents: