Replace, remove, or delete placement policies

This document explains how to manage placement policies. Specifically:

Update the properties of a virtual machine (VM) instance that specifies a placement policy to do one of the following:
- Replace the placement policy with another existing placement policy.
- Remove the placement policy.
Delete a placement policy that you don't need anymore.

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

Required roles

To get the permissions that you need to replace, remove, 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 replace, remove, 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 replace, remove, or delete placement policies:

To update the properties of a VM: compute.instances.update on the project
To delete a placement policy: compute.resourcePolicies.delete on the project

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

Replace a placement policy in a VM

You can replace the placement policy specified in a VM with another placement policy using the gcloud CLI and REST.

gcloud

To replace a placement policy in a VM with another placement policy, follow these steps:

To export the properties of an existing VM, use the gcloud compute instances export command.
```
gcloud compute instances export VM_NAME \
    --destination=FILE_PATH \
    --zone=ZONE
```
Replace the following:
- VM_NAME: the name of an existing VM that specifies a placement policy.
- FILE_PATH: the path where you want to save the VM configuration file.
- ZONE: the zone where the VM is located.
In a text editor of your choice, open the VM configuration file.
To replace the placement policy with another existing policy, replace the value in the resourcePolicies field with another placement policy.
```
...
resourcePolicies:
- https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/another-example-policy
...
```
You can also modify other properties of the VM. For more information, see Properties that you can update.
Follow the remaining steps in Update VM properties.

REST

To replace a placement policy in a VM with another placement policy, follow these steps:

To export the properties of an existing VM, make a GET request to the instances.get method.
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
```
Replace the following:
- PROJECT_ID: the ID of the project where the VM is located.
- ZONE: the zone where the VM is located.
- VM_NAME: the name of an existing VM that specifies a placement policy.
To replace the placement policy with another existing policy, replace the value in the resourcePolicies field with another placement policy.
```
{
...
"resourcePolicies": [
  "https://www.googleapis.com/compute/v1/projects/example-project/regions/us-central1/resourcePolicies/another-example-policy"
],
...
}
```
You can also modify other properties of the VM. For more information, see Properties that you can update.
Follow the remaining steps in Update VM properties.

Remove a placement policy from a VM

You can remove the placement policy applied to a VM using the gcloud CLI and REST.

gcloud

To remove a placement policy from a VM, use the gcloud compute instances remove-resource-policies command.

gcloud compute instances remove-resource-policies VM_NAME \
    --resource-policies=POLICY_NAME \
    --zone=ZONE

Replace the following:

VM_NAME: the name of an existing VM that specifies a placement policy.
POLICY_NAME: the name of the placement policy applied to the VM. To verify the name of the placement policy, view the details of the VM and see the resourcePolicies field.
ZONE: the zone where the VM is located.

REST

To remove a placement policy from a VM, make a POST request to the instances.removeResourcePolicies method.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/removeResourcePolicies

{
  "resourcePolicies": [
    "projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME"
  ]
}

Replace the following:

PROJECT_ID: the ID of the project where the VM is located.
ZONE: the zone where the VM is located.
VM_NAME: the name of an existing VM that specifies a placement policy.
REGION: the region where the placement policy is located.
POLICY_NAME: the name of the placement policy applied to the VM. To verify the name of the placement policy, view the details of the VM and see the resourcePolicies field.

Delete a placement policy

You can only delete a placement policy if it's not applied to any Compute Engine resource. Otherwise, deleting the placement policy fails. If you want to delete a placement policy that is applied to a Compute Engine resource, do one of the following:

If the policy is applied to VMs only and you want to keep the VMs, do the following:
1. Remove the placement policy from the VMs.
2. Delete the placement policy.
Otherwise, do the following:
1. Optional: Remove the placement policy from any VM you want to keep.
2. Delete every other Compute Engine resource the placement policy is applied to in the following order:
  1. VMs
  2. Reservations
  3. Instance templates
3. Delete the placement policy.

You can delete a placement policy using the gcloud CLI and REST.

gcloud

To delete a placement policy, use the gcloud compute resource-policies delete command.

gcloud compute resource-policies delete 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.

REST

To delete a placement policy, make a DELETE request to the resourcePolicies.delete method.

DELETE 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 is located.
REGION: the region where the placement policy is located.
POLICY_NAME: the name of an existing placement policy.

What's next?

Learn how to view placement policies.
Learn how to do the following with a VM that specifies a placement policy:
- View the status of the VM.
- Connect to the VM.