View placement policies

This document describes how to view placement policies.

Viewingplacement policies isuseful to see all the existing placement policies in a project, or verify theconfiguration details of a specific placement policy.

Before you begin

Required roles

To get the permissions that you need to view placement policies, ask your administrator to grant you theCompute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on your project. For more information about granting roles, seeManage 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 theRequired 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 withcustom roles or otherpredefined roles.

View your placement policies

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

View a list of your placement policies

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

gcloud

To view a list of placement policies, use thegcloud compute resource-policies list commandwith the--filter flag set togroupPlacementPolicy:*.

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

The output is similar to the following:

NAME: example-compact-policyDESCRIPTION:REGION: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1CREATION_TIMESTAMP: 2024-05-09T02:09:24.588-07:00NAME: example-spread-policyDESCRIPTION:REGION: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1CREATION_TIMESTAMP: 2024-05-09T02:08:13.404-07:00

For more information about using filter expressions to narrow down a list ofCompute Engine resources, see thegcloud topic filters command.

REST

To view a list of placement policies that are located in a specific region,make aGET request to theresourcePolicies.list method.In the request URL, include thefilter query parameter and set it togroupPlacementPolicy%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 wantto view a list of placement policies.

  • REGION: the region where one or more placementpolicies 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 ofresource policies usingURL-encoding, see thefilter 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 thegcloud compute resource-policies describe command.

Note: If you want to view themaxDistance field in a compact placementpolicy, use thegcloud beta compute resource-policies describe commandinstead.
gcloud compute resource-policies describePOLICY_NAME \    --region=REGION

Replace the following:

  • POLICY_NAME: the name of an existing placementpolicy.

  • REGION: the region where the placement policy islocated.

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: COLLOCATEDid: '5587673659722509355'kind: compute#resourcePolicyname: example-compact-policyregion: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1selfLink: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/example-compact-policystatus: READY

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

    creationTimestamp: '2024-05-09T02:08:13.404-07:00'groupPlacementPolicy:  availabilityDomainCount: 5id: '5970772604948130963'kind: compute#resourcePolicyname: example-spread-policyregion: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1selfLink: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/example-spread-policystatus: READY

REST

To view the details of a placement policy, make aGET request to theresourcePolicies.get method.

Note: If you want to view themaxDistance field in a compact placementpolicy, make aGET request to thebeta.resourcePolicies.get methodinstead.
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 placementpolicy you want to view the details of is located.

  • REGION: the region where the placement policy islocated.

  • POLICY_NAME: the name of an existing placementpolicy.

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?

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.