Replace, remove, or delete placement policies

This document describes how to replace, remove, or delete placement policies.

Replacing, removing, or deleting placement policies is useful in the following cases:

Replace a placement policy in a virtual machine (VM) instance to move the VM to a different position relative to other VMs.
Remove a placement policy from a VM when you're no longer interested in its position relative to other VMs.
Delete a placement policy when you no longer need it.

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.
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

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 replace or remove a placement policy from 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

Before you replace a spread placement policy in a VM with a compact placement policy, make sure that the VM uses a supported machine type and host maintenance policy. If you need to update the VM before replacing its placement policy, then do one or both of the following:

After you replace the placement policy in a VM, you must restart the VM to make the newly applied placement policy effective.

To replace a placement policy in a VM, select one of the following options:

gcloud

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/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 the placement 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 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.
The request returns the configuration details of the VM.
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/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 the placement 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

If you want to remove a spread placement policy with two or more availability domains from a VM, then you can do so without stopping the VM. If you want to remove a compact placement policy or a spread placement policy with only one availability domain, then you must first stop the VM before removing the placement policy attached to it.

Removing a placement policy from a VM doesn't affect its physical location. However, if the VM is live migrating, Compute Engine might move the VM to a different physical location.

To remove a placement policy from a VM, select one of the following options:

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 check the value of 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 check the value of 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 one or more Compute Engine resources, then 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 as described in this document.
2. Delete the placement policy as described in this section.
Otherwise, do the following:
1. Optional: Remove the placement policy from any VM you want to keep as described in this document.
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 as described in this section.

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

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.