Edit the machine type of a compute instance

If your virtual machine (VM) instance doesn't have attached Local SSD and is not part of a managed instance group (MIG), you can change the machine type of your instance 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. For example, you can start a VM with a smaller machine type during setup, development, and testing and change the VM to use a larger machine type when you are ready for production workloads.

You can use this procedure in the following situations:

  • To change to a similar machine type but with a different number of vCPUs or memory within the same machine series, for example:
    • You can change n2-highcpu-4 to n2-standard-4.
    • You can change c3d-standard-30 to c3d-highmem-30.
  • To change the machine type to use a different machine series. This is supported for only first and second generation machine series, excluding the T2A and A2 machine series. For example:
    • You can change n2-standard-4 to c2-standard-8.
    • You can change n1-highmem-4 to n2d-standard-16.

If you want to change the machine type for a VM that uses a first or second generation machine series (N1, N2, M1, etc.) to a machine type for a third generation or later machine series (M3, C3, N4, etc.), you must use the procedure documented in Move your workload to a new compute instance.

You can change the machine type without affecting the following resources:

  • The VM's SSH keys
  • The VM configurations, such as VM metadata
  • The data on attached Persistent Disk or Hyperdisk, including installed applications and application data

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, 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:

    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 in 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. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

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

    Python

    To use the Python samples on this page in 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. If you're using a local shell, then create local authentication credentials for your user account: 

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    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

    For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to change the machine type of a VM, ask your administrator to grant you the following IAM roles on the project:

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to change the machine type of a VM. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to change the machine type of a VM:

  • compute.instances.setMachineType on VM
  • compute.instances.start on VM
  • compute.instances.stop on VM

You might also be able to get these permissions with custom roles or other predefined roles.

Limitations

  • If your compute instance has one or more Local SSD, you can't change the machine type of the instance.
  • If your compute instance uses an ephemeral external IP address, the IP address might change when you modify the instance's machine type. To preserve the IP address, promote it to a static external IP address before you change the machine type.
  • Changing the machine type of a compute instance isn't available for some configurations:
    • You can't change the machine type for bare metal instances.
    • If you want to change the machine type from a first or second generation machine series to a machine type for a third generation or later machine series, you can't use this procedure. Instead, follow the instructions in Move your workload to a new compute instance.
    • If you want to change the machine type to an Arm machine type, you can't use this procedure. Instead, follow the instructions in Move your workload to a new compute instance.
    • You can use the steps in this document to change the machine type for G2 accelerator-optimized machine types. For other accelerator-optimized machine types, review Modify accelerator-optimized VMs.

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.

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 running on your current 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.

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 disks to the /etc/fstab file. If you have additional 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 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 can't change the machine type of a running VM.

If you are upgrading your machine type to the latest generation, review Evaluate VM migration options before proceeding.

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

What's next