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, then 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 by selecting one of the following options:
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
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 your project.
For more information about granting roles, see Manage 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 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
Create an empty YAML file.
To export the properties of a VM into the YAML file that you've just created, 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 to the YAML file that you created in the previous step.ZONE
: the zone where the VM is located.
In the YAML configuration file, edit the value of the
resourcePolicies
field 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 the placement policy is located. You can only specify a placement policy that is located in the same project as the VM.REGION
: the region where the placement policy is located.POLICY_NAME
: the name of the placement policy.
To update the VM and restart it, use the
gcloud compute instances update-from-file
command with the--most-disruptive-allowed-action
flag set toRESTART
.gcloud compute instances update-from-file VM_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 the configuration data that you modified in the previous step.ZONE
: the zone where the VM is located.
REST
Create an empty JSON file.
To view the properties of an existing VM, make a
GET
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 is located.ZONE
: the zone where the VM is located.VM_NAME
: the name of an existing VM that specifies a placement policy.
In the empty JSON file that you created in the previous steps, do the following:
Enter the VM properties from the
GET
request output.Locate the
resourcePolicies
field, and then edit its value 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 the placement policy is located. You can only specify a placement policy that is located in the same project as the VM.REGION
: the region where the placement policy is located.POLICY_NAME
: the name of the placement policy.
To update the VM and restart it, make a
PUT
request to theinstances.update
method. In the request, do the following:In the request URL, include the
most_disruptive_allowed_action
query parameter set toRESTART
.For the request body, use the VM configuration details from the JSON file 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, see 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 theresourcePolicies
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 theresourcePolicies
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:
Remove the placement policy from the VMs as described in this document.
Delete the placement policy as described in this section.
Otherwise, do the following:
Optional: Remove the placement policy from any VM you want to keep as described in this document.
Delete every other Compute Engine resource the placement policy is applied to in the following order:
VMs
Reservations
Instance templates
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: