Edit the machine type of a VM instance


If your VM does not have a local SSD and is not part of a managed instance group (MIG), you can change the machine type of your VM after stopping it.

If your existing machine type is not a good fit for the workloads you run on your VM, change the machine type of that VM. You can change the machine type of a VM to adjust the number of vCPUs and memory as your workload changes. For example, you can start a VM with a smaller machine during setup, development, and testing and change the VM to use a larger machine type when you are ready for production workloads.

For VMs that do not have a local SSD and are not part of a MIG, you can change the machine type without affecting the following resources:

  • The VM's SSH keys
  • The VM configurations, such as VM metadata
  • The VM's persistent disk data, including installed applications and application data

If you need to change the machine type of VMs within a MIG, see Automatically apply VM configuration updates in a MIG.

Before you begin

  • Understand how to stop a VM.
  • Understand machine types.
  • 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:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    Java

    To use the Java samples on this page from a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

    1. Install the Google Cloud CLI.
    2. To initialize the gcloud CLI, run the following command:

      gcloud init
    3. Create local authentication credentials for your Google Account:

      gcloud auth application-default login

    For more information, see Set up authentication for a local development environment.

    Python

    To use the Python samples on this page from a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

    1. Install the Google Cloud CLI.
    2. To initialize the gcloud CLI, run the following command:

      gcloud init
    3. Create local authentication credentials for your Google Account:

      gcloud auth application-default login

    For more information, see Set up authentication for a local development environment.

    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

Limitations

Billing implications

Each machine type is billed at a different rate, so make sure you understand the pricing implications of changing machine types. For example, an e2-standard-2 machine type costs more than an e2-micro machine type.

Changing a machine type might also affect the sustained use discounts for that VM. Sustained use discounts are calculated separately for different categories in the same region. If you change machine types so that the new machine type is in a different category, the subsequent running time of the VM counts toward the sustained use discount of the new category.

For example, assume you have a VM with n2-standard-2 machine type running for half a month. You then decide to change the machine type to m1-ultramem-40. Once you make that change, Compute Engine starts counting the running time of the VM towards the sustained use discount of the memory-optimized vCPU and memory category.

On your bill, you would see a sustained use discount applied to the n2-standard-2 machine type from before you made the machine type change, and a separate sustained use discount for m1-ultramem-40, if your VM remains running on m1-ultramem-40 for at least a 25% of the rest of the month.

Best practices

Here are some best practices to help you successfully change the VM machine type.

  • Make regular backups of your persistent disk data using snapshots. Consider taking a snapshot of your persistent disk data before you change the machine type. If you want to make sure the new machine type is able to support the data on the existing VM, you can take a persistent disk snapshot and use it to start a second VM with the new machine type to confirm that the VM starts up successfully.

  • Add additional persistent disks to the /etc/fstab file. If you have additional persistent disks attached to your VM, make sure they are added to the /etc/fstab file so that they are automatically mounted when the VM reboots.

  • Create a reservation before changing the machine type. To avoid errors related to resource availability, create Compute Engine reservations for the new machine types when they are available to reserve them within a zone. Reservations help ensure that the resources are available when you need them.

To create a reservation, complete the following steps:

  1. Create a reservation (or identify existing reservations) with identical properties as the planned VMs. The reservation's VM count needs to be equal to or greater than the number of VMs that you want to change. Optionally, to prevent other VMs from consuming this reservation, use the specificReservationRequired option.

  2. Verify that the planned VMs will be able to consume the reservation:

    1. Verify that the desired VMs have the correct reservation affinity.
    2. Immediately before changing the VMs, ensure the reservation has enough capacity.

Change a machine type

You can only change the machine type of a stopped VM. A VM is considered stopped only when the VM is in the TERMINATED state. You cannot change the machine type of a running VM.

If you are upgrading your machine type to the latest generation, review Move your VM to a third generation machine series before proceeding.

Permissions required for this task

To perform this task, you must have the following permissions:

  • compute.instances.setMachineType on the VM

Console

  1. In the Google Cloud console, go to the VM instances page.

    Go to VM instances

  2. In the Name column, click the name of the VM for which you want to change machine type.

  3. From the VM instance details page, complete the following steps:

    1. If the VM is running, in the menu at the top of the page, select Stop to stop the VM.
    2. To edit the VM, click Edit.
    3. In the Machine configuration section, select the machine type that you want to use, or create a custom machine type.

    4. To save your changes, click Save.

    5. Restart the VM.

gcloud

  1. Stop the VM by using the gcloud compute instances stop command:

    gcloud compute instances stop VM_NAME
    

    Replace VM_NAME with the VM containing the machine type to change.

  2. Change the machine type by using the gcloud compute instances set-machine-type command:

    gcloud compute instances set-machine-type VM_NAME \
        --machine-type NEW_MACHINE_TYPE
    

    Replace NEW_MACHINE_TYPE with the new machine type for the VM. The machine type can be one of the following:

  3. Start the VM by using the gcloud compute instances start command:

    gcloud compute instances start VM_NAME
    

    Replace VM_NAME with the name of the VM that you changed.

Java

Java

Before trying this sample, follow the Java setup instructions in the Compute Engine quickstart using client libraries. For more information, see the Compute Engine Java API reference documentation.

To authenticate to Compute Engine, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.


import com.google.cloud.compute.v1.Instance;
import com.google.cloud.compute.v1.Instance.Status;
import com.google.cloud.compute.v1.InstancesClient;
import com.google.cloud.compute.v1.InstancesSetMachineTypeRequest;
import com.google.cloud.compute.v1.Operation;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class ChangeInstanceMachineType {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Cloud project you want to use.
    String projectId = "your-project-id";
    // Name of the zone your instance belongs to.
    String zone = "zone-name";
    // Name of the VM you want to modify.
    String instanceName = "instance-name";
    // The new machine type you want to use for the VM.
    // For example: "e2-standard-8", "e2-custom-4-2048" or "m1-ultramem-40"
    // More about machine types: https://cloud.google.com/compute/docs/machine-resource
    String newMachineType = "e2-standard-8";
    changeMachineType(projectId, zone, instanceName, newMachineType);
  }

  // Changes the machine type of VM.
  // The VM needs to be in the 'TERMINATED' state for this operation to be successful.
  public static void changeMachineType(String projectId, String zone, String instanceName,
      String newMachineType)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `instancesClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (InstancesClient instancesClient = InstancesClient.create()) {

      Instance instance = instancesClient.get(projectId, zone, instanceName);
      if (!instance.getStatus().equals(Status.TERMINATED.name())) {
        throw new Error(String.format(
            "Only machines in TERMINATED state can have their machine type changed. "
                + "%s is in %s state.", instance.getName(), instance.getStatus()));
      }

      InstancesSetMachineTypeRequest machineTypeRequest =
          InstancesSetMachineTypeRequest.newBuilder()
              .setMachineType(String.format("projects/%s/zones/%s/machineTypes/%s",
                  projectId, zone, newMachineType))
              .build();

      Operation response = instancesClient
          .setMachineTypeAsync(projectId, zone, instanceName, machineTypeRequest)
          .get(3, TimeUnit.MINUTES);

      if (response.hasError()) {
        System.out.println("Machine type update failed! " + response);
        return;
      }
      System.out.println("Machine type update - operation status: " + response.getStatus());
    }
  }
}

Python

Python

Before trying this sample, follow the Python setup instructions in the Compute Engine quickstart using client libraries. For more information, see the Compute Engine Python API reference documentation.

To authenticate to Compute Engine, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.

from __future__ import annotations

import sys
from typing import Any

from google.api_core.extended_operation import ExtendedOperation
from google.cloud import compute_v1


def wait_for_extended_operation(
    operation: ExtendedOperation, verbose_name: str = "operation", timeout: int = 300
) -> Any:
    """
    Waits for the extended (long-running) operation to complete.

    If the operation is successful, it will return its result.
    If the operation ends with an error, an exception will be raised.
    If there were any warnings during the execution of the operation
    they will be printed to sys.stderr.

    Args:
        operation: a long-running operation you want to wait on.
        verbose_name: (optional) a more verbose name of the operation,
            used only during error and warning reporting.
        timeout: how long (in seconds) to wait for operation to finish.
            If None, wait indefinitely.

    Returns:
        Whatever the operation.result() returns.

    Raises:
        This method will raise the exception received from `operation.exception()`
        or RuntimeError if there is no exception set, but there is an `error_code`
        set for the `operation`.

        In case of an operation taking longer than `timeout` seconds to complete,
        a `concurrent.futures.TimeoutError` will be raised.
    """
    result = operation.result(timeout=timeout)

    if operation.error_code:
        print(
            f"Error during {verbose_name}: [Code: {operation.error_code}]: {operation.error_message}",
            file=sys.stderr,
            flush=True,
        )
        print(f"Operation ID: {operation.name}", file=sys.stderr, flush=True)
        raise operation.exception() or RuntimeError(operation.error_message)

    if operation.warnings:
        print(f"Warnings during {verbose_name}:\n", file=sys.stderr, flush=True)
        for warning in operation.warnings:
            print(f" - {warning.code}: {warning.message}", file=sys.stderr, flush=True)

    return result


def change_machine_type(
    project_id: str, zone: str, instance_name: str, new_machine_type: str
) -> None:
    """
    Changes the machine type of VM. The VM needs to be in the 'TERMINATED' state for this operation to be successful.

    Args:
        project_id: project ID or project number of the Cloud project you want to use.
        zone: name of the zone your instance belongs to.
        instance_name: name of the VM you want to modify.
        new_machine_type: the new machine type you want to use for the VM.
            For example: `e2-standard-8`, `e2-custom-4-2048` or `m1-ultramem-40`
            More about machine types: https://cloud.google.com/compute/docs/machine-resource
    """
    client = compute_v1.InstancesClient()
    instance = client.get(project=project_id, zone=zone, instance=instance_name)

    if instance.status != compute_v1.Instance.Status.TERMINATED.name:
        raise RuntimeError(
            f"Only machines in TERMINATED state can have their machine type changed. "
            f"{instance.name} is in {instance.status}({instance.status_message}) state."
        )

    machine_type = compute_v1.InstancesSetMachineTypeRequest()
    machine_type.machine_type = (
        f"projects/{project_id}/zones/{zone}/machineTypes/{new_machine_type}"
    )
    operation = client.set_machine_type(
        project=project_id,
        zone=zone,
        instance=instance_name,
        instances_set_machine_type_request_resource=machine_type,
    )

    wait_for_extended_operation(operation, "changing machine type")

REST

  1. Stop the VM by using the instances.stop method:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/stop
    

    Replace the following:

    • PROJECT_ID: the project ID

    • ZONE: the zone containing the VM

    • VM_NAME: the VM containing the machine type to change

  2. Change the machine type by using the instances.setMachineType method:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMachineType
    

    In the body of the request, provide the updated machineType:

    {
        machineType: "zones/MACHINE_TYPE_ZONE/machineTypes/NEW_MACHINE_TYPE"
    }
    

    Replace the following:

    • MACHINE_TYPE_ZONE: the zone containing the machine type

    • NEW_MACHINE_TYPE: the new machine type for the VM

      The machine type can be one of the following:

  3. Start the VM by using the instances.start method:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/start
    

    Replace the following:

    • PROJECT_ID: the project ID
    • ZONE: the zone containing the VM
    • VM_NAME: the name of the VM that you changed

Move to a smaller machine type

If you move from a machine type with more resources to a machine type with fewer resources, such as moving from a e2-standard-8 machine type to a e2-standard-2, you could run into hardware resource issues or performance limitations because smaller machine types are less powerful than larger machine types. Make sure that your new machine type is able to support any applications or services that are currently running on the VM, or that you update your services and applications to run on the smaller machine types.

Review the rightsizing recommendations before changing the machine type. For information about Compute Engine sizing recommendations, see Applying machine type recommendations for VM instances.

Move your VM to a third generation machine series

When the requirements are met, you can modify your VM to use a machine type in a new generation machine series by changing the machine type—for example, from m1-ultramem-160 to m3-ultramem-128.

Third generation machine types and Arm T2A machine types might not support the same features and interfaces as your current machine type. Before starting the migration process, review the requirements and considerations in Prepare to move to a new VM.

To change the machine type for your VM instance to a third generation machine type, you can use either of the following approaches.

Create a new VM instance and move your workload

In this procedure, you create a new VM instance, then move your workload to the new VM.

For details on how to complete this procedure, see Move your workload from an existing VM to a new VM.

Change the machine type to a new machine type

In this procedure, you verify that your current VM instance can be updated to use the new machine type, and then change the machine type.

  1. Verify your current VM instance uses an operating system version supported by the new machine type. If the version is not supported, then follow the instructions in Move your workload from an existing VM to a new VM.

  2. If you want to change the machine type for your VM to a T2A machine type, follow the instructions in Move your workload from an existing VM to a new VM.

  3. If your current VM has attached Local SSD, follow the instructions in Move your workload from an existing VM to a new VM.

  4. Verify your applications and programs can support a different network or storage interface, such as gVNIC or NVMe.

  5. Review the best practices for changing the machine type of a VM.

  6. Follow the procedure described in Change a machine type.

What's next