This document explains how to view placement policies. Specifically, it explains how to view the available placement policies in a specified project, or view the configuration details of one of these policies.
Before you begin
- Review the restrictions for placement policies.
-
If you haven't already, 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 as follows.
Select the tab for how you plan to use the samples on this page:
gcloud
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- 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, then initialize it by running the following command:
gcloud init
-
Required roles
To get the permissions that you need to view or delete placement policies,
ask your administrator to grant you the
Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1
) IAM role on the project.
For more information about granting roles, see Manage access.
This predefined role contains the permissions required to view or delete placement policies. To see the exact permissions that are required, expand the Required permissions section:
Required permissions
The following permissions are required to view or delete 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 specified project, select one of the following methods:
To see all your placement policies, 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
You can view a list of all the placement policies in a specified project using the gcloud CLI and REST.
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: policy-1
DESCRIPTION:
REGION: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1
CREATION_TIMESTAMP: 2023-07-15T02:10:51.958-08:00
NAME: policy-2
DESCRIPTION:
REGION: https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1
CREATION_TIMESTAMP: 2023-07-15T02:11:16.826-08: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": "637231102400797797",
"creationTimestamp": "2023-07-28T04:12:11.072-07:00",
"selfLink": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/policy-1",
"region": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1",
"name": "policy-1",
"groupPlacementPolicy": {
"collocation": "COLLOCATED"
},
"status": "READY"
},
{
"kind": "compute#resourcePolicy",
"id": "1228789480840827204",
"creationTimestamp": "2023-07-15T02:10:51.958-08:00",
"selfLink": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/policy-2",
"region": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1",
"name": "policy-2",
"groupPlacementPolicy": {
"availabilityDomainCount": 2
},
"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
You can view the details of a placement policy in a specified project using the gcloud CLI and REST.
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:
creationTimestamp: '2023-07-15T02:10:51.958-08:00'
groupPlacementPolicy:
availabilityDomainCount: 2
id: '1228789480840827204'
kind: compute#resourcePolicy
name: pp2
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-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:
{
"kind": "compute#resourcePolicy",
"id": "637231102400797797",
"creationTimestamp": "2023-07-28T04:12:11.072-07:00",
"selfLink": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/example-policy",
"region": "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1",
"name": "policy-1",
"groupPlacementPolicy": {
"availabilityDomainCount": 2
},
"status": "READY"
}
What's next?
Learn how to replace, remove, or delete placement policies.
Learn how to apply a placement policy: