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

• Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1)
• To connect to a VM that can run as a service account: Service Account User (v1) (roles/iam.serviceAccountUser)

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:

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

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

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());
    }
  }
}

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")

What's next

• Learn about machine type recommendations.
• Learn about managed instance groups.
• Learn about patterns for scalable and resilient apps.
• To update a first or second generation VM to use a third generation or later machine series, see Move your workload to a new compute instance.