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.
  
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
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.
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:

To enable an organization policy: Organization Policy Administrator (roles/orgpolicy.policyAdmin) on the organization
To view, enable, or disable alpha features: Compute Admin (roles/compute.admin) on the project

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

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

Go to Organization policies
If you haven't already, from the project picker, select the organization, folder, or project where you want to edit the policy.
In the Name column, click Block Compute Engine preview features. The Policy details page appears.
Click Manage policy. The Edit policy page appears.
In the Policy source section, select Override parent's policy.
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.
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

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:
- ORGANIZATION_ID: the ID of your organization
- FOLDER_ID: the ID of your folder
- PROJECT_ID: the ID of your project
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
```
Save the policy.yaml file, and then close the text editor.
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
```
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:

View available alpha features
Enable an alpha feature
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 as follows.

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:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/previewFeatures"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/previewFeatures" | Select-Object -Expand Content

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 as follows.

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:

curl (Linux, macOS, or Cloud Shell)

Save the request body in a file named request.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/previewFeatures/FEATURE_NAME"

PowerShell (Windows)

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/previewFeatures/FEATURE_NAME" | Select-Object -Expand Content

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 as follows. 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:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/previewFeatures?filter=activationStatus=ENABLED"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/previewFeatures?filter=activationStatus=ENABLED" | Select-Object -Expand Content

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 as follows.

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:

curl (Linux, macOS, or Cloud Shell)

Save the request body in a file named request.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/previewFeatures/FEATURE_NAME"

PowerShell (Windows)

Save the request body in a file named request.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/global/previewFeatures/FEATURE_NAME" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

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

What's next

Best practices for the Compute Engine API

Use the Compute Engine alpha API Stay organized with collections Save and categorize content based on your preferences.

Before you begin

Console

gcloud

REST

Required roles

Required permissions

Allow access to alpha features

Console

gcloud

Use alpha features in your project

View available alpha features

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Enable an alpha feature

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

View enabled alpha features

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

Disable an alpha feature

gcloud

Linux, macOS, or Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

What's next

Use the Compute Engine alpha API