Access global resources regionally for high availability

By using autoscaling scripts or runtime services on Compute Engine, you can automate continuous integration and continuous deployment (CI/CD) pipelines. However, because these resources depend heavily on global resource definitions when they query global API endpoints, this approach can introduce a single point of failure across your multi-region architecture.

To mitigate this risk, you can configure your services to access regional views of global resources. By sending GET and LIST requests to regionalized read-only endpoints within the exact region where your compute workloads run, your services isolate their API consumption from potential outages in the global control plane or in other regions. For more information about regionalized read-only endpoints and resilience best practices, see Use regional views for resilient control-plane reads.

Before you begin

• If you haven't already, set up authentication. Authentication verifies your identity 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. Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI 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.

  Install the Google Cloud CLI.

  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 access global resources regionally, ask your administrator to grant you the Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on the project or OS images. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to access global resources regionally. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to access global resources regionally:

• To get regional views for a project: compute.projects.get on the project
• To get regional views for OS images: compute.images.get and compute.images.list on the project or OS images

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

Project resource

You can get regional views of your global project resource by using the projectViews read-only endpoint. When you query the projectViews endpoint, Compute Engine returns the standard global compute.Project resource object. The resource itself remains global.

Note: When you query a compute.Project resource by using regional projectViews.get endpoints, the quota array is excluded from the response. For accurate quota configuration and real-time usage metrics across all regions and zones, query the global projects.get endpoint.

Get a regional view of a project resource

You can get a regional view of your global project by using the Google Cloud CLI or the REST API.

gcloud

To describe your global project through the control plane for a specific region, run the gcloud compute project-views describe command:

gcloud compute project-views describe \
    --region=REGION \
    --project=PROJECT_ID

Replace the following:

• REGION: the Google Cloud region for the API request—for example, us-central1.
• PROJECT_ID: your project ID.

REST

To describe your global project through the control plane for a specific region, send a GET request to the projectViews method.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/projectViews"

Replace the following:

• PROJECT_ID: your project ID.
• REGION: the Google Cloud region for the API request—for example, us-central1.

The API returns the standard compute.Project resource representation directly.

{
  "kind": "compute#project",
  "id": "1234567890123456789",
  "creationTimestamp": "2024-01-15T10:00:00.000-08:00",
  "name": "my-project12345",
  "commonInstanceMetadata": {
    "items": [
      {
        "key": "example-key",
        "value": "example-value"
      }
    ]
  },
  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project12345",
  "defaultServiceAccount": "SERVICE_ACCOUNT_EMAIL"
}

OS image resource

You can get regional views of your global OS image resource by using the imageViews read-only endpoint. When you query the imageViews endpoint, Compute Engine returns the standard global compute.Image resource object. The resource itself remains global.

Get a regional list of OS image resources

You can list all of the global OS images that are available to your project through a specific regional endpoint by using the gcloud CLI or the REST API.

gcloud

To list global OS images by using a regional endpoint, run the gcloud compute image-views list command:

gcloud compute image-views list \
    --region=REGION \
    --project=PROJECT_ID

Replace the following:

• REGION: the Google Cloud region for the API request—for example, us-central1.
• PROJECT_ID: your project ID.

REST

To list global OS images by using a regional endpoint, send a GET request to the imageViews method:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/imageViews"

Replace the following:

• PROJECT_ID: your project ID.
• REGION: the Google Cloud region for the API request—for example, us-central1.

Get a regional view of an OS image resource

You can retrieve information for a specific global OS image through a regional endpoint by using the gcloud CLI or the REST API.

gcloud

To retrieve details for a global OS image using a regional endpoint, run the gcloud compute image-views describe command:

gcloud compute image-views describe IMAGE_NAME \
    --region=REGION \
    --project=PROJECT_ID

Replace the following:

• IMAGE_NAME: the name of the global OS image resource.
• REGION: the Google Cloud region for the API request—for example, us-central1.
• PROJECT_ID: your project ID.

REST

To retrieve details for a global OS image using a regional endpoint, send a GET request to the specific imageViews method:

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/imageViews/IMAGE_NAME"

Replace the following:

• PROJECT_ID: your project ID.
• REGION: the Google Cloud region for the API request—for example, us-central1.
• IMAGE_NAME: the name of the global OS image resource.

The API returns the standard compute.Image resource representation directly.

{
  "kind": "compute#image",
  "id": "1234567890123456789",
  "creationTimestamp": "2024-01-15T10:00:00.000-08:00",
  "name": "my-image12345",
  "sourceDisk": "https://www.googleapis.com/compute/v1/projects/my-project12345/zones/us-central1-a/disks/my-disk12345",
  "sourceDiskId": "1234567890123456789",
  "sourceType": "RAW",
  "status": "READY",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project12345/global/images/my-image12345"
}

What's next

• Learn more about The project resource.
• Learn more about OS images.
• Learn how to Troubleshoot regional views of global resources.