Replace, remove, or delete placement policies

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

Replacing, removing, or deletingplacement policies isuseful in the following cases:

  • Replace a placement policy in a virtual machine (VM) instance to move the VMto a different position relative to other VMs.

  • Remove a placement policy from a VM when you're no longer interested in itsposition relative to other VMs.

  • Delete a placement policy when you no longer need it.

Before you begin

Required roles

To get the permissions that you need to replace, remove, or delete 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 replace, remove, or delete placement policies. To see the exact permissions that are required, expand theRequired 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 withcustom roles or otherpredefined roles.

Replace a placement policy in a VM

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

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

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

gcloud

  1. Create an empty YAML file.

  2. To export the properties of a VM into the YAML file that you've justcreated, use thegcloud compute instances export command.

    gcloud compute instances exportVM_NAME \    --destination=FILE_PATH \    --zone=ZONE

    Replace the following:

    • VM_NAME: the name of an existing VM thatspecifies a placement policy.

    • FILE_PATH: the path to the YAML file that youcreated in the previous step.

    • ZONE: the zone where the VM is located.

  3. In the YAML configuration file, edit the value of theresourcePoliciesfield to specify a different 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 theplacement policy is located. You can only specify a placement policythat is located in the same project as the VM.

    • REGION: the region where the placement policy islocated.

    • POLICY_NAME: the name of the placement policy.

    Tip: To avoid getting an error such as"ERROR: (gcloud.compute.instances.update-from-file) Cannot parse YAML: [Expected type for field value, found True (type)]", add quotes (' ') around any label values ofyes orno in the exported instance configuration file. This indicates the values are strings, not Boolean values.

  4. To update the VM and restart it, use thegcloud compute instances update-from-file commandwith the--most-disruptive-allowed-action flag set toRESTART.

    gcloud compute instances update-from-fileVM_NAME \    --most-disruptive-allowed-action=RESTART \    --source=YAML_FILE \    --zone=ZONE

    Replace the following:

    • VM_NAME: the name of the VM.

    • YAML_FILE: the path to the YAML file with theconfiguration data that you modified in the previous step.

    • ZONE: the zone where the VM is located.

REST

  1. Create an empty JSON file.

  2. To view the properties of an existing VM, make aGET request to theinstances.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 islocated.

    • ZONE: the zone where the VM is located.

    • VM_NAME: the name of an existing VM thatspecifies a placement policy.

  3. In the empty JSON file that you created in the previous steps, do thefollowing:

    1. Enter the VM properties from theGET request output.

    2. Locate theresourcePolicies field, and then edit its value tospecify a different 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 theplacement policy is located. You can only specify a placementpolicy that is located in the same project as the VM.

      • REGION: the region where the placement policyis located.

      • POLICY_NAME: the name of the placementpolicy.

  4. To update the VM and restart it, make aPUT request to theinstances.update method.In the request, do the following:

    • In the request URL, include themost_disruptive_allowed_actionquery parameter set toRESTART.

    • For the request body, use the VM configuration details from the JSONfile that you created and updated in the previous steps.

    PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME?most_disruptive_allowed_action=RESTART{  ...  "resourcePolicies": [    "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME"  ],  ...}

For more information about updating the properties of a VM, seeUpdate VM properties.

Remove a placement policy from a VM

If you want to remove a spread placement policy with two or more availabilitydomains from a VM, then you can do so without stopping the VM. If you wantto remove a compact placement policy or a spread placement policy with only oneavailability domain, then you must firststop the VM beforeremoving 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 adifferent 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 thegcloud compute instances remove-resource-policies command.

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

Replace the following:

  • VM_NAME: the name of an existing VM that specifies aplacement policy.

  • POLICY_NAME: the name of the placement policy appliedto the VM. To verify the name of the placement policy,view the details of the VMand check the value of theresourcePolicies field.

  • ZONE: the zone where the VM is located.

REST

To remove a placement policy from a VM, make aPOST request to theinstances.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 islocated.

  • ZONE: the zone where the VM is located.

  • VM_NAME: the name of an existing VM that specifies aplacement policy.

  • REGION: the region where the placement policy islocated.

  • POLICY_NAME: the name of the placement policy appliedto the VM. To verify the name of the placement policy,view the details of the VMand check the value of theresourcePolicies field.

Delete a placement policy

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

  • If the policy is applied to VMs only and you want to keep the VMs, do thefollowing:

    1. Remove the placement policy from the VMs as describedin 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 keepas described in this document.

    2. Deleteevery other Compute Engine resource the placementpolicy 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 thegcloud compute resource-policies delete command.

gcloud compute resource-policies deletePOLICY_NAME \    --region=REGION

Replace the following:

  • POLICY_NAME: the name of an existing placementpolicy.

  • REGION: the region where the placement policy islocated.

REST

To delete a placement policy, make aDELETE request to theresourcePolicies.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 placementpolicy is located.

  • REGION: the region where the placement policy islocated.

  • POLICY_NAME: the name of an existing placementpolicy.

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 2025-12-09 UTC.