View placement policies

This document describes how to view placement policies.

Viewing placement policies is useful to see all the existing placement policies in a project, or verify the configuration details of a specific placement policy.

Before you begin

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:
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  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 view placement policies, ask your administrator to grant you the Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on your project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to view placement policies. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to view placement policies:

To view a list of your placement policies: compute.resourcePolicies.list on the project
To view the details of a placement policy: compute.resourcePolicies.get on the project

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

View your placement policies

To view the placement policies that are available in a project, select one of the following methods described in this document:

To see all the existing placement policies in a project, view a list of your placement policies.
To see the configuration details of a placement policy, view the details of a placement policy.

View a list of your placement policies

To view a list of all the placement policies in your project, select one of the following options:

gcloud

To view a list of placement policies, use the gcloud compute resource-policies list command with the --filter flag set to groupPlacementPolicy:*.

gcloud compute resource-policies list \
    --filter="groupPlacementPolicy:*"

The output is similar to the following:

NAME: example-compact-policy
DESCRIPTION:
REGION: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1
CREATION_TIMESTAMP: 2024-05-09T02:09:24.588-07:00

NAME: example-spread-policy
DESCRIPTION:
REGION: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1
CREATION_TIMESTAMP: 2024-05-09T02:08:13.404-07:00

For more information about using filter expressions to narrow down a list of Compute Engine resources, see the gcloud topic filters command.

REST

To view a list of placement policies that are located in a specific region, make a GET request to the resourcePolicies.list method. In the request URL, include the filter query parameter and set it to groupPlacementPolicy%3A*.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/resourcePolicies?filter=groupPlacementPolicy%3A*

Replace the following:

PROJECT_ID: the ID of the project in which you want to view a list of placement policies.
REGION: the region where one or more placement policies are located.

The output is similar to the following:

{
  "kind": "compute#resourcePolicyList",
  "id": "projects/example-project/regions/us-central1/resourcePolicies",
  "items": [
    {
      "kind": "compute#resourcePolicy",
      "id": "5587673659722509355",
      "creationTimestamp": "2024-05-09T02:09:24.588-07:00",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/example-compact-policy",
      "region": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1",
      "name": "example-compact-policy",
      "groupPlacementPolicy": {
        "collocation": "COLLOCATED"
      },
      "status": "READY"
    },
    {
      "kind": "compute#resourcePolicy",
      "id": "5970772604948130963",
      "creationTimestamp": "2024-05-09T02:08:13.404-07:00",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/example-spread-policy",
      "region": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1",
      "name": "example-spread-policy",
      "groupPlacementPolicy": {
        "availabilityDomainCount": 5
      },
      "status": "READY"
    }
  ],
  "selfLink": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies",
  "etag": "-L7XCupTQ5V9__TOJ8G5RDcR2cY=/g_xt0udkOM_tU7jSL0z9I2Sivis="
}

For more information about using filter expressions to narrow down a list of resource policies using URL-encoding, see the filter query parameter.

View the details of a placement policy

To view the details of a placement policy, select one of the following options:

gcloud

To view the details of a placement policy, use the gcloud compute resource-policies describe command.

gcloud compute resource-policies describe POLICY_NAME \
    --region=REGION

Replace the following:

POLICY_NAME: the name of an existing placement policy.
REGION: the region where the placement policy is located.

The output is similar to the following:

If you're viewing the details of a compact placement policy:

creationTimestamp: '2024-05-09T02:09:24.588-07:00'
groupPlacementPolicy:
  collocation: COLLOCATED
id: '5587673659722509355'
kind: compute#resourcePolicy
name: example-compact-policy
region: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1
selfLink: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/example-compact-policy
status: READY

If you're viewing the details of a spread placement policy:

creationTimestamp: '2024-05-09T02:08:13.404-07:00'
groupPlacementPolicy:
  availabilityDomainCount: 5
id: '5970772604948130963'
kind: compute#resourcePolicy
name: example-spread-policy
region: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1
selfLink: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/example-spread-policy
status: READY

REST

To view the details of a placement policy, make a GET request to the resourcePolicies.get method.

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME

Replace the following:

PROJECT_ID: the ID of the project where the placement policy you want to view the details of is located.
REGION: the region where the placement policy is located.
POLICY_NAME: the name of an existing placement policy.

The output is similar to the following:

If you're viewing the details of a compact placement policy:

{
  "kind": "compute#resourcePolicy",
  "id": "5587673659722509355",
  "creationTimestamp": "2024-05-09T02:09:24.588-07:00",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/example-compact-policy",
  "region": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1",
  "name": "example-compact-policy",
  "groupPlacementPolicy": {
    "collocation": "COLLOCATED"
  },
  "status": "READY"
}

If you're viewing the details of a spread placement policy:

{
  "kind": "compute#resourcePolicy",
  "id": "5970772604948130963",
  "creationTimestamp": "2024-05-09T02:08:13.404-07:00",
  "selfLink": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/example-spread-policy",
  "region": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1",
  "name": "example-spread-policy",
  "groupPlacementPolicy": {
    "availabilityDomainCount": 5
  },
  "status": "READY"
}

What's next?

Learn how to replace, remove, or delete placement policies.
Learn how to apply a placement policy:
- Apply compact placement policies to VMs.
- Apply spread placement policies to VMs.
Learn how to verify the location of VMs that are using compact placement policies.