Updating VM tenancy

This page describes how to update the tenancy of a VM by modifying its node affinity labels. By modifying node affinity labels, you can reschedule a VM onto or off of a sole-tenant node or node group, or between nodes and node groups.

Before updating the tenancy of VMs, read the overview of VM tenancy.

Before you begin

Updating the tenancy of a VM

Update tenancy by rescheduling the VM onto a specific sole-tenant node or node group from another node or node group or from a multi-tenant host.

gcloud

  1. Before updating the tenancy of a VM, stop the VM.

    gcloud compute instances stop vm-name
    

    Replace vm-name with the name of the VM to stop.

  2. Update the tenancy in one of the following ways:

    • Specify the node group onto which to reschedule the VM. This is the recommended way to update VM tenancy.

      gcloud compute instances set-scheduling vm-name  --node-group=group-name
      

      Replace the following:

      • vm-name: Name of the VM to move to a specific node group.
      • group-name: Name of the node group to reschedule the VM onto.
    • Specify the sole-tenant node onto which to reschedule the VM.

      gcloud compute instances set-scheduling vm-name  --node=node
      

      Replace the following:

      • vm-name: Name of the VM to move to a specific sole-tenant node.
      • node: Name of the sole-tenant node onto which to reschedule the VM.
    • Specify the file containing the affinity labels of the node group to reschedule the VM onto.

      gcloud compute instances set-scheduling vm-name  --node-affinity-file=file-name.json
      

      Replace the following:

      • vm-name: Name of the VM to move to a node group specified by the contents of an affinity label file.
      • file-name: Name of the file containing the affinity labels specifying which node group to reschedule the previously specified VM.
  3. After updating the tenancy of the VM, start the VM.

    gcloud compute instances start vm-name
    

    Replace vm-name with the name of the VM to start on the node group previously specified by the contents of an affinity label file.

API

  1. Before updating the tenancy of a VM, 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-id: ID of the project containing the VM to stop.
    • zone: Zone containing the project.
    • vm-name: Name of the VM to stop.
  2. Update the tenancy in one of the following ways:

    • Specify the node group onto which to reschedule the VM. This is the recommended way to update VM tenancy.

      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-id: ID of the project containing the VM to reschedule.
      • zone: Zone containing the project.
      • vm-name: Name of the VM to move to a specific node group.
      • node-group-name: Name of the node group to reschedule the VM onto.
    • Specify the sole-tenant node onto which to reschedule the VM.

      POST https://compute.googleapis.com/compute/v1/projects/project-id/zones/zone/instances/vm-name/setScheduling
      
      {
        "nodeAffinities": [
          {
            "key": "compute.googleapis.com/node-name",
            "operator": "IN",
            "values": [
              "node-name"
            ]
          }
        ]
      }
      

      Replace the following:

      • project-id: ID of the project containing the VM to reschedule.
      • zone: Zone containing the project.
      • vm-name: Name of the VM to move to a specific sole-tenant node.
      • node-name: Name of the sole-tenant node onto which to reschedule the VM.
  3. After updating the tenancy of the VM, start the VM. For more information about 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-id: ID of the project containing the VM to start.
    • zone: Zone containing the project.
    • vm-name: Name of the VM to start.

Troubleshooting tenancy updating errors

If you attempt to reschedule a VM that is already on a sole-tenant node, the VM might restart on another node in the node group. Rescheduling fails if the node group, node, or affinity label does not exist.

If the node group, node, or node affinity label does exist, rescheduling might fail due to a lack of capacity, for example:

  • If you reschedule a VM onto a node that is scheduling VMs in parallel, in rare situations there might not be capacity.
  • If you reschedule a VM onto a node in a node group on which you haven't enabled autoscaling, there might not be capacity.
  • If you reschedule a VM onto a node in a node group on which you have enabled autoscaling but have exceeded your CPU quota, there might not be capacity.

Rescheduling a VM off of a sole-tenant node

If your VM no longer requires dedicated hardware, for example, after an event that required your VM to be isolated from other VMs, reschedule the VM off of a sole-tenant node onto a multi-tenant host.

gcloud

  1. Stop the VM.

    gcloud compute instances stop vm-name
    

    Replace vm-name with the name of the VM to stop.

  2. Clear the node affinities from the VM so it can be rescheduled onto a multi-tenant host.

    gcloud compute instances set-scheduling vm-name --clear-node-affinities
    

    Replace vm-name with the name of the VM for which to remove node affinities.

  3. Start the VM on a multi-tenant host.

    gcloud compute instances start vm-name
    

    Replace vm-name with the name of the VM from which you previously cleared the node affinities.

API

  1. 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-id: ID of the project containing the VM to stop.
    • zone: Zone containing the project.
    • vm-name: Name of the VM to stop.
  2. Clear the node affinities from the VM to reschedule it onto 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-id: ID of the project containing the VM to reschedule.
    • zone: Zone containing the project.
    • vm-name: Name of the VM from which to clear any node affinities so you can reschedule it onto a multi-tenant host.
  3. Start the VM on a multi-tenant host. For more information about 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-id: ID of the project containing the VM to start.
    • zone: Zone containing the project.
    • vm-name: Name of the VM to start.

What's next