Use the Compute Engine alpha API


This document explains how to enable your project to send HTTP requests to alpha Compute Engine API URIs using REST. If you're new to the Compute Engine API, then see Prerequisites.

By default, your project can't send HTTP requests to the following alpha Compute Engine API URI:

https://compute.googleapis.com/compute/alpha/...

Google Cloud manages access to alpha URIs for specific Compute Engine features. You must first allow your organization, folder, or project to access and use alpha features. After this step, you can view which features are available, and then enable a project to send HTTP requests to their alpha URIs. Using Compute Engine alpha features with REST lets you test and develop with early-stage features before they're available in Preview.

Before you begin

  • You can only enable a project to send HTTP requests to an alpha URI if the project is part of an organization. If not, then migrate the project to an organization.
  • If you haven't already, then set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud 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 Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    1. After installing the Google Cloud CLI, initialize it by running the following command:

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    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.

      After installing the Google Cloud CLI, initialize it by running the following command:

      gcloud init

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

Required roles

To get the permissions that you need to enable or disable projects to send HTTP requests to alpha Compute Engine API URIs, ask your administrator to grant you the following IAM roles:

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to enable or disable projects to send HTTP requests to alpha Compute Engine API URIs. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to enable or disable projects to send HTTP requests to alpha Compute Engine API URIs:

  • To edit organization policies: orgpolicy.policy.set on the organization, folder, or project
  • To enable or disable access to an alpha Compute Engine API URI for a project: compute.previewFeatures.update on the project
  • To view available alpha features: compute.previewFeatures.get on the project

You might also be able to get these permissions with custom roles or other predefined roles.

Allow access to alpha features

Before you can use Compute Engine alpha features with REST, you must enable the Block Compute Engine preview features (compute.managed.blockPreviewFeatures) policy in your organization, folder, or project. This policy change allows your project, or the projects within your organization or folder, to access and use alpha features.

To allow your organization, folder, or project to access alpha features with REST, select one of the following options:

Console

  1. In the Google Cloud console, go to the Organization policies page.

    Go to Organization policies

  2. If you haven't already, from the project picker, select the organization, folder, or project where you want to edit the policy.

  3. In the Name column, click Block Compute Engine preview features. The Policy details page appears.

  4. Click Manage policy. The Edit policy page appears.

  5. In the Policy source section, select Override parent's policy.

  6. In the Rules section, click Add rule, and then do the following:

    1. In the Enforcement section, select On.

    2. In the row containing the allowedPreviewFeatures parameter, click Edit. The Edit parameter values pane appears.

    3. In the Value type section, select User-defined.

    4. In the User-defined values section, enter alpha-api-access.

    5. Click Save.

  7. Click Set policy. Then, in the dialog that appears, click Set policy again.

The policy change can take up to 15 minutes to propagate.

gcloud

  1. To download the compute.managed.blockPreviewFeatures policy as a file named policy.yaml, use the gcloud org-policies describe command with one of the following flags:

    • To enable the policy in your organization, include the --organization flag:

      gcloud org-policies describe compute.managed.blockPreviewFeatures --organization=ORGANIZATION_ID > policy.yaml
      
    • To enable the policy in your folder, include the --folder flag:

      gcloud org-policies describe compute.managed.blockPreviewFeatures --folder=FOLDER_ID > policy.yaml
      
    • To enable the policy in your project, include the --project flag:

      gcloud org-policies describe compute.managed.blockPreviewFeatures --project=PROJECT_ID > policy.yaml
      

    Replace the following:

  2. Open the policy.yaml file using a text editor. In the file, after the rules field, add the enforce field set to true. For example, if you're enabling the policy in your organization, your policy.yaml entry is as follows:

    name: organizations/ORGANIZATION_ID/policies/compute.managed.blockPreviewFeatures
    spec:
      rules:
      - enforce: true
    
  3. Save the policy.yaml file, and then close the text editor.

  4. To update the policy for your organization, folder, or project, use the gcloud org-policies set-policy command:

    gcloud org-policies set-policy policy.yaml
    
  5. Optional: To delete the policy.yaml file, do one of the following:

    • If you're using the Linux or macOS terminal, then use the following command:

      rm policy.yaml
      
    • If you're using the Windows terminal, then use the following command:

      del policy.yaml
      

The policy change can take up to 15 minutes to propagate.

For more information about managing organization policies, see Using constraints in the Resource Manager documentation.

Use alpha features in your project

After you allow your organization, folder, or project access to Compute Engine alpha features, you can enable a project to use those features by completing the following steps:

  1. View available alpha features

  2. Enable an alpha feature

  3. Optional: View enabled alpha features

View available alpha features

To view which Compute Engine features are available in alpha, select one of the following options:

gcloud

To view the Compute Engine features available in alpha, use the gcloud beta compute preview-features list command.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud beta compute preview-features list 

Windows (PowerShell)

gcloud beta compute preview-features list 

Windows (cmd.exe)

gcloud beta compute preview-features list 

You should receive a response similar to the following:

NAME              STATUS
alpha-feature-1   DISABLED
alpha-feature-2   DISABLED

REST

To view the Compute Engine features available in alpha, make a GET request to the beta previewFeatures.list method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the ID of your project

HTTP method and URL:

GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/previewFeatures

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{ 
  "previewFeatures": [
    {
      "activationStatus": "DISABLED",
      "creationTimestamp": "2025-03-01T00:00:00Z",
      "description": "Please see status.description for details.",
      "id": "560966157",
      "name": "alphaFeature1",
      "status": {
        "description": "Enables access to alpha APIs.",
        "helpLink": "some-link",
        "releaseStatus": {
          "stage": "PREVIEW",
          "updateDate": {
            "day": 1,
            "month": 3,
            "year": 2025
          }
        }
      }
    },
    ...
  ]
}

Enable an alpha feature

To enable your project to send HTTP requests to the alpha URI of a Compute Engine feature, select one of the following options:

gcloud

To enable your project to send HTTP requests to the alpha URI of a Compute Engine feature, use the gcloud beta compute preview-features update command with the --activation-status flag set to ENABLED.

Before using any of the command data below, make the following replacements:

  • FEATURE_NAME: the name of the feature that you want to start using.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud beta compute preview-features update FEATURE_NAME \
    --activation-status=ENABLED \
    --rollout-plan=fast-rollout

Windows (PowerShell)

gcloud beta compute preview-features update FEATURE_NAME `
    --activation-status=ENABLED `
    --rollout-plan=fast-rollout

Windows (cmd.exe)

gcloud beta compute preview-features update FEATURE_NAME ^
    --activation-status=ENABLED ^
    --rollout-plan=fast-rollout

You should receive a response similar to the following:

status: DONE

REST

To enable your project to send HTTP requests to the alpha URI of a Compute Engine feature, make a PATCH request to the beta previewFeatures.update method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the ID of your project.
  • FEATURE_NAME: the name of the feature that you want to start using.

HTTP method and URL:

PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/previewFeatures/FEATURE_NAME

Request JSON body:

{
  "activationStatus": "ENABLED",
  "rolloutOperation": {
    "rolloutInput": {
      "predefinedRolloutPlan": "ROLLOUT_PLAN_FAST_ROLLOUT"
    }
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": "compute#operation",
  "status": "DONE"
}

View enabled alpha features

To view a list of enabled Compute Engine alpha features in your project, select one of the following options:

gcloud

To view a list of enabled alpha features, use the gcloud beta compute preview-features list command with the --filter flag set to activationStatus=ENABLED.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud beta compute preview-features list --filter=activationStatus=ENABLED

Windows (PowerShell)

gcloud beta compute preview-features list --filter=activationStatus=ENABLED

Windows (cmd.exe)

gcloud beta compute preview-features list --filter=activationStatus=ENABLED

You should receive a response similar to the following:

NAME              STATUS
alpha-feature-1   ENABLED
alpha-feature-2   ENABLED

REST

To view a list of enabled alpha features, make a GET request to the beta previewFeatures.list method. In the request URL, set the filter query parameter to items.activationStatus=ENABLED.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the ID of your project

HTTP method and URL:

GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/previewFeatures?filter=activationStatus=ENABLED

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{ 
  "etag": "Ehx4OkkYX3CUXGRWAE8lvEn0ZDE=/rEhZfPEilwjblfZuwOYpO1nHC2c=",
  "id": "projects/example-project",
  "previewFeatures": [
    {
      "activationStatus": "ENABLED",
      "creationTimestamp": "2025-03-01T00:00:00Z",
      "description": "Please see status.description for details.",
      "id": "560966157",
      "name": "alphaFeature1",
      "status": {
        "description": "Enables access to alpha APIs.",
        "helpLink": "some-link",
        "releaseStatus": {
          "stage": "PREVIEW",
          "updateDate": {
            "day": 1,
            "month": 3,
            "year": 2025
          }
        }
      }
    },
    ...
  ],
  "selfLink": "https://www.googleapis.com/compute/beta/projects/example-project"
}

Disable an alpha feature

If you no longer need to use a Compute Engine alpha feature, then you can disable your project access to it.

To disable your project from sending HTTP requests to the alpha URI of a Compute Engine feature, select one of the following options:

gcloud

To disable your project from sending HTTP requests to the alpha URI of a Compute Engine feature, use the gcloud beta compute preview-features update command with the --activation-status flag set to DISABLED.

Before using any of the command data below, make the following replacements:

  • FEATURE_NAME: the name of the feature that you want to stop using.

Execute the following command:

Linux, macOS, or Cloud Shell

gcloud beta compute preview-features update FEATURE_NAME \
    --activation-status=DISABLED \
    --rollout-plan=fast-rollout

Windows (PowerShell)

gcloud beta compute preview-features update FEATURE_NAME `
    --activation-status=DISABLED `
    --rollout-plan=fast-rollout

Windows (cmd.exe)

gcloud beta compute preview-features update FEATURE_NAME ^
    --activation-status=DISABLED ^
    --rollout-plan=fast-rollout

You should receive a response similar to the following:

status: DONE

REST

To disable your project from sending HTTP requests to the alpha URI of a Compute Engine feature, make a PATCH request to the beta previewFeatures.update method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: the ID of your project.
  • FEATURE_NAME: the name of the feature that you want to stop using.

HTTP method and URL:

PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/previewFeatures/FEATURE_NAME

Request JSON body:

{
  "activationStatus": "DISABLED",
  "rolloutOperation": {
    "rolloutInput": {
      "predefinedRolloutPlan": "ROLLOUT_PLAN_FAST_ROLLOUT"
    }
  }
}

To send your request, expand one of these options:

You should receive a JSON response similar to the following:

{
  "kind": "compute#operation",
  "status": "DONE"
}

What's next