Updating VM tenancy
This page describes how to update a VM's tenancy by modifying the VM's nodeaffinity labels.
By default, Compute Engine deploys VMs on multi-tenant hosts. On multi-tenanthosts, VMs typically share host resources with VMs from other projects andcustomers. When you move a VM to asole-tenant node, your project has exclusive access to and complete control of thesole-tenant node hardware. You are the only tenant on that node, so yourworkloads are isolated from the workloads of other projects and their VMs.
By modifying node affinity labels, you can move a VM in the following ways:
- From a multi-tenant host to a sole-tenant node group or node
- From a sole-tenant node group or node to a multi-tenant host
- From one sole-tenant node to another sole-tenant node or node group
- From a sole-tenant node group to another sole-tenant node group or node
Temporarily moving workloads into sole-tenancy
Due to fluctuating requirements of your workloads, such as periodic needs foradditional isolation to examine performance, or changes to your complianceregulations, you might need to temporarily move specific workloads to sole-tenant nodes. Then, when you no longer need sole-tenancy, redeploy your VMs to amulti-tenant host. When you modify the tenancy of a VM, Compute Enginepreserves the configurations of the VM.
Rebalancing sole-tenant workloads
In addition to moving VMs to and from sole-tenant nodes and node groups, you canmove VMs between nodes and node groups, which can help you consolidate nodes andrebalance workloads. Moving a VM requires a restart, so plan moving VMs based onthe availability requirements of your workloads.
Limitations
- When you move a VM that is already running on a sole-tenant node, the VM mightrestart on another node. If a VM's sole tenancy is specified by node group nameor by using the
node-group-namedefault affinitylabel, the VM can restart on anynode in the node group. If the VM's sole tenancy is specified using affinity oranti-affinitycustom affinitylabels, the VM might restart on anynode of any node group in the zone.
Before you begin
- If you haven't already, set upauthentication. Authentication verifies your identity 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. After installation,initialize the Google Cloud CLI by running the following command:
gcloudinit
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.- 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. After installation,initialize the Google Cloud CLI by running the following command:
gcloudinit
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.
Moving a VM into sole-tenancy
Update tenancy by moving the VM to a specific sole-tenant node or nodegroup from another node or node group or from a multi-tenant host.
gcloud
Stop the VM.
gcloud compute instances stopVM_NAME
Replace
VM_NAMEwith the name of the VM to stop.Update the tenancy by specifying the node group to move the VM to.
gcloud compute instances set-schedulingVM_NAME \ --node-group=NODE_GROUP_NAME
Replace the following:
VM_NAMEname of the VM to move to aspecific node groupNODE_GROUP_NAMEname of the node group tomove the VM to
Alternatively, you can move a VM to a sole-tenant node by using the nameof the node or by using a affinity label. For more information, see the
gcloud compute instances set-schedulingcommand.Start the VM.
gcloud compute instances startVM_NAME
Replace
VM_NAMEwith the name of the VM to starton the node group previously specified by the contents of an affinitylabel file.
REST
Stop the VM. For more informationabout this command, seeinstances.stop.
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/stop
Replace the following:
PROJECT_ID: ID of the project containing theVM to stopZONEzone containing the projectVM_NAMEname of the VM to stop
Update the tenancy by specifying the node group to move the VM to.
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setScheduling{ "nodeAffinities": [ { "key": "compute.googleapis.com/node-group-name", "operator": "IN", "values": [ "NODE_GROUP_NAME" ] } ]}Replace the following:
PROJECT_IDID of the project containingthe VM to moveZONEzone containing the projectVM_NAMEname of the VM to move to aspecific node groupNODE_GROUP_NAMEname of the node group tomove the VM to
Alternatively, you can move a VM to a sole-tenant node by using the nameof the node or by using a affinity label. For more information, see the
instances.setSchedulingmethod.Start the VM. For more informationabout this command, see
instances.start.POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/start
Replace the following:
PROJECT_IDID of the project containing theVM to startZONEzone containing the projectVM_NAMEname of the VM to start
Moving a VM out of sole-tenancy
If your VM no longer requires dedicated hardware, for example, after an eventthat required your VM to be isolated from other VMs, move the VM from asole-tenant node to a multi-tenant host.
gcloud
Stop the VM.
gcloud compute instances stopVM_NAME
Replace
VM_NAMEwith the name of the VM to stop.Clear the node affinities from the VM so you can move it to a multi-tenant host.
gcloud compute instances set-schedulingVM_NAME --clear-node-affinities
Replace
VM_NAMEwith the name of the VM forwhich toremove nodeaffinities.Start the VM on a multi-tenant host.
gcloud compute instances startVM_NAME
Replace
VM_NAMEwith the name of the VM fromwhich you previously cleared the node affinities.
REST
Stop the VM. For more information about this command, see
instances.stop.POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/stop
Replace the following:
PROJECT_IDID of the project containing theVM to stopZONEzone containing the projectVM_NAMEname of the VM to stop
Clear the node affinities from the VM to move it to a multi-tenant host.
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setScheduling{ "nodeAffinities": []}Replace the following:
PROJECT_IDID of the project containing theVM to moveZONEzone containing the projectVM_NAMEname of the VM from which to clearnode affinities
Start the VM on a multi-tenant host. For more information about thiscommand, seeinstances.start.
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/start
Replace the following:
PROJECT_IDID of the project containing theVM to startZONEzone containing the projectVM_NAMEname of the VM to start
What's next
- Before moving VMs onto sole-tenant nodes, read aboutsole-tenant nodepricing.
- ReadBringing your own licenses.
- Read theFAQ about Microsoft licenses.
- Learnhow to bring images with existing licenses toGoogle Cloud.
- Learn how toautoscale sole-tenant nodegroups.
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-15 UTC.