Creating a custom VM instance

Compute Engine offers predefined machine types that you can use when you create a VM instance. A predefined machine type has a preset number of vCPUs and amount of memory, and is charged at a set price.

If predefined VMs don't meet your needs, you can create a VM instance with custom virtualized hardware settings. Specifically, you can create a VM instance with a custom number of vCPUs and amount of memory, effectively using a custom machine type. Custom machine types are available in the general-purpose machine family. When you create a custom VM, you're deploying a custom VM from the E2, N2, N2D, or N1 machine family.

Custom VMs are ideal in the following scenarios:

• Workloads that aren't a good fit for the predefined virtual machine types.
• Workloads that require more processing power or more memory but don't need all upgrades that are provided by the next level machine type.

Before you begin

• If you want to use the command-line examples in this guide, do the following:
  1. Install or update to the latest version of the gcloud command-line tool.
  2. Set a default region and zone.
• If you want to use the API examples in this guide, set up API access.
• Read the machine families documentation.

Pricing

Google charges for custom VMs based on the number of vCPUs and memory hours that the VM uses. This is different from how predefined machine types are charged. See VM pricing for details.

Custom VMs are subject to the same 1-minute minimum charge as any other instance, but sustained use discounts for custom machine types are calculated differently. For more information, see sustained use discounts for custom VMs.

Expressing memory in GB or MB

For Google Cloud tools and documentation, machine type memory is calculated in gigabytes (GB), where 1 GB is 2³⁰ bytes. This unit of measurement is also known as a gibibyte (GiB) . When converting memory from GB to MB, 1 GB = 1024 MB.

In the API, you must always provide memory in megabytes. If you use the gcloud command-line tool, you can provide the total memory for a VM in gigabytes or megabytes. However, the gcloud tool expects the memory value to be an integer, so you cannot provide a float value. For example, to express 5.75 GB, convert 5.75 GB into MB instead. In this case, 5.75 GB is 5888 MB.

Create a VM instance with a custom machine type

Before you create a VM instance, make sure you read and understand the custom specifications for creating this machine type.

Note: You can only create E2 shared-core custom VMs by using the gcloud command-line tool or the Compute Engine API.

Permissions required for this task

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

• compute.instances.create on the project
• compute.instances.updateShieldedVmConfig if you plan to create a Shielded VM instance and you want to be able to change any of the Shielded VM settings
• compute.networks.use on the project if using a legacy network
• compute.subnetworks.use either on the whole project or on the chosen subnet (VPC networks)
• compute.networks.useExternalIp on the project if you need to assign an external IP address (either ephemeral or static) to the instance using a legacy network
• compute.subnetworks.useExternalIp either on the whole project or on the chosen subnet if you need to assign an external IP address (either ephemeral or static) to the instance using a VPC network
• compute.addresses.use on the project if specifying a static address in the project
• compute.instances.setMetadata if setting metadata
• compute.instances.setTags on the instance if setting tags
• compute.instances.setLabels on the instance if setting labels
• compute.images.useReadOnly on the image if creating a new root persistent disk
• compute.disks.create on the project if creating a new root persistent disk with this instance
• compute.disks.useReadOnly on the disk if attaching an existing persistent disk in read-only mode
• compute.disks.use on the disk if attaching an existing disk in read/write mode
• compute.disks.setLabels on the disk if setting labels
• compute.snapshots.create on the project to create a new snapshot if creating an instance from a snapshot
• compute.snapshots.useReadOnly on the snapshot if creating an instance from a snapshot

Console

1. In the Google Cloud Console, go to the Create an instance page.

   Go to Create an instance

2. In the Zone list, select the zone where you want to host this VM. The Series list is filtered to include only the machine type families available in the selected zone.

3. In the Machine configuration section, select General-purpose.

   1. In the Series list, click N1 in First Generation for N1 custom machine types or E2, N2, or N2D for Second Generation custom machine types.
   2. From the Machine type list, select Custom.
   3. To specify the number of vCPUs and the amount of memory for the VM instance, drag the sliders or enter the values in the text boxes. The console displays an estimated cost for the VM as you change the number of vCPUs and memory.

4. Continue to create the VM.

gcloud

The gcloud command for custom machine types differs slightly depending on the machine type family.

For N1 machine types, use the gcloud compute instances create command and include one of the following options:

• The --custom-cpu and --custom-memory flags.
• The --machine-type=custom-[NUMBER_OF_CPUS]-[NUMBER_OF_MB] flag.

For example, the following command would create an instance running an N1 machine type with 4 vCPUs and 5 GB of total memory:

gcloud compute instances create example-instance \
    --custom-cpu=4 --custom-memory=5

For N2 machine types, use the gcloud compute instances create command and include one of the following options:

• The --custom-cpu, --custom-memory, and --custom-vm-type flags.
• The --machine-type=n2-custom-NUMBER_OF_CPUS-NUMBER_OF_MB flag.

When using the --custom-memory flag, specify the total amount of memory in GB or in MB. The property must be an integer, so if you want to specify increments of 0.25 GB for memory, convert that value to MB instead.

To specify an incremental value, such as 2.5 GB of memory, convert the value to MB and supply the value followed by the MB suffix. The following example creates an instance running an N2 machine type:

gcloud compute instances create example-instance \
    --custom-cpu=6 --custom-memory=3072MB --custom-vm-type=n2

Alternatively, you can specify a custom machine type using the following format:

gcloud compute instances create example-instance \
    --machine-type n2-custom-NUMBER_OF_CPUS-NUMBER_OF_MB

Replace the following:

• NUMBER_OF_CPUS: The number of CPUs you want.
• NUMBER_OF_MB: The amount of memory, in MB.

For example:

gcloud compute instances create example-instance --machine-type=n2-custom-6-3072

For N2D or E2 machine types, use the gcloud compute instances create command and include one of the following options:

• The --custom-cpu, --custom-memory, and --custom-vm-type flags.
• The --machine-type=n2d-custom-NUMBER_OF_CPUS-NUMBER_OF_MB flag.
• The --machine-type=e2-custom-NUMBER_OF_CPUS-NUMBER_OF_MB flag.

For E2 shared-core custom machine types, use the same gcloud compute instances create command and include the shared-core machine size: micro, small, or medium.

• The --machine-type=e2-custom SHARED_CORE_MACHINE_SIZE-NUMBER_OF_MB flag.

For example:

gcloud compute instances create example-instance \
    --machine-type=e2-custom-medium-NUMBER_OF_MB

When using the --custom-memory flag, specify the total amount of memory in GB or in MB. The property must be an integer. So, if you want to specify increments of 0.25 GB for memory, convert the value to MB instead.

To specify an incremental value, such as 2.5 GB of memory, convert the value to MB and supply the value followed by the MB suffix. The following example creates an instance running an E2 machine type:

gcloud compute instances create example-instance \
    --custom-cpu=6 --custom-memory=3072MB --custom-vm-type=e2

Alternatively, you can specify a custom machine type by using the following format:

gcloud compute instances create example-instance \
    --machine-type=e2-custom-NUMBER_OF_CPUS-NUMBER_OF_MB

Replace the following:

• NUMBER_OF_CPUS: The number of CPUs you want.
• NUMBER_OF_MB: The amount of memory, in MB.

For example:

gcloud compute instances create example-instance --machine-type=e2-custom-6-3072

API

In the API, create your instance creation request as you would normally, but when specifying a machineType value, use one of the following formats. Replace NUMBER_OF_CPUS with the number of CPUs and AMOUNT_OF_MEMORY_MB with the amount of memory you want. Provide memory in MB units.

• For N1 machine types, use:

  zones/ZONE/machineTypes/custom-NUMBER_OF_CPUS-AMOUNT_OF_MEMORY_MB
  

• For N2 machine types, use:

  zones/ZONE/machineTypes/n2-custom-NUMBER_OF_CPUS-AMOUNT_OF_MEMORY_MB
  

• For N2D machine types, use:

  zones/ZONE/machineTypes/n2d-custom-NUMBER_OF_CPUS-AMOUNT_OF_MEMORY_MB
  

• For E2 machine types, use:

  zones/ZONE/machineTypes/e2-custom-NUMBER_OF_CPUS-AMOUNT_OF_MEMORY_MB
  

• For E2 shared-core custom machine types, use:

  zones/ZONE/machineTypes/e2-custom-SHARED_CORE_MACHINE_SIZE-AMOUNT_OF_MEMORY_MB
  

For example, the following URL would create an instance with 4 vCPUs and 5 GB (5120 MB) of memory:

zones/us-central1-f/machineTypes/custom-4-5120

You can similarly create preemptible instances and groups of instances with custom machine types.

Add extended memory to a machine type

Depending on the machine, each machine type has a specific amount of memory by default. For example, if you create a custom N1 VM, it can have up to 6.5 GB of memory per vCPU. For custom N2 VMs, this number increases up to 8 GB of memory per vCPU.

For some workloads, this might not be enough memory. At an extra cost, you can get more memory per vCPU beyond the default limit. This is referred to as extended memory.

With extended memory, you can add memory to a machine type with no limitations per vCPU. You can add extended memory up to certain limits based on the machine type:

• For N1 machine types, you can add up to a total of 624 GB of memory per VM.
• For N2 machine types, you can add up to a total of 640 GB of memory per VM.
• For N2D machine types, you can add up to a total of 768 GB of memory per VM.
• Extended memory is not available for E2 machine types.

If you require more memory, you must use one of the mega-memory machine types, which lets you create instances with a total of 1.4 TB per VM instance.

Determining whether you need extended memory

Certain workloads need more than the default amount of memory per vCPU to deliver optimum results. Workloads that are based on in-memory high- performance analytics databases, including relational and NoSQL databases such as MS SQL Server, MongoDB, and MemcacheD/Redis, are in this category. The vCPU-based licensing of operating systems and software stacks also makes selecting an optimal VM memory configuration more challenging with predefined machine types. By using extended memory, you can add as much memory as your VMs need for the best price- performance ratio.

Pricing

When using a custom machine type, any memory up to and including the default amount per vCPU is charged at the N1 custom machine type pricing, or the N2 custom machine type pricing. E2 custom machine and E2 shared-core custom machine types share the same pricing scheme.

For memory above the default, Compute Engine charges for extended memory based on the N1 extended custom memory pricing or the N2 extended custom memory pricing. The price for extended memory is different from the price for memory below the default threshold.

Extended memory prices differ depending on the region. Instances running with extended memory are subject to the same 1-minute minimum charge as any other instance. Extended memory also qualifies for sustained use discounts.

For more information, see sustained use discounts for custom machine types and extended custom memory pricing.

Limitations

• You can add extended memory only to custom machine types. Predefined machine types are not supported.
• There is no limit to the memory per vCPU that you can add, but there is a maximum amount of memory you can add to each VM instance. For N1 machine types, you can add up to 624 GB of memory. For N2 machine types, you can add up to 640 GB of memory. For N2D machines types, you can add up to 768 GB of memory.
• N2 and N2D machine types are available only in select regions and zones.
• You must specify memory in 256-MB increments.
• Extended memory does not qualify for committed use discounts.

Add extended memory during instance creation

To create a VM instance with extended memory, follow the instructions below.

Permissions required for this task

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

• compute.instances.create on the project
• compute.instances.updateShieldedVmConfig if you plan to create a Shielded VM instance and you want to be able to change any of the Shielded VM settings
• compute.networks.use on the project if using a legacy network
• compute.subnetworks.use either on the whole project or on the chosen subnet (VPC networks)
• compute.networks.useExternalIp on the project if you need to assign an external IP address (either ephemeral or static) to the instance using a legacy network
• compute.subnetworks.useExternalIp either on the whole project or on the chosen subnet if you need to assign an external IP address (either ephemeral or static) to the instance using a VPC network
• compute.addresses.use on the project if specifying a static address in the project
• compute.instances.setMetadata if setting metadata
• compute.instances.setTags on the instance if setting tags
• compute.instances.setLabels on the instance if setting labels
• compute.images.useReadOnly on the image if creating a new root persistent disk
• compute.disks.create on the project if creating a new root persistent disk with this instance
• compute.disks.useReadOnly on the disk if attaching an existing persistent disk in read-only mode
• compute.disks.use on the disk if attaching an existing disk in read/write mode
• compute.disks.setLabels on the disk if setting labels
• compute.snapshots.create on the project to create a new snapshot if creating an instance from a snapshot
• compute.snapshots.useReadOnly on the snapshot if creating an instance from a snapshot

Console

1. In the Google Cloud Console, go to the Create an instance page.

   Go to Create an instance

2. In the Zone list, select the zone where you want to host this VM. The Series list is filtered to include only the machine type families available in the selected zone.

3. In the Machine configuration section, select General-purpose.

   1. In the Series list, click N1 in First Generation for N1 custom machine types or N2 or N2D for Second Generation custom machine types.
   2. In the Machine type list, select Custom.
   3. To specify the number of vCPUs drag the Cores slider or enter the value in the text box.

   4. To add extended memory, select Extend memory, and do the following:

      1. To specify the amount of memory for the VM instance, drag the Memory slider or enter the value in the text box.

      The console displays an estimated cost for the VM as you change the number of vCPUs and memory.

4. Continue to create the VM.

gcloud

For N1 machine types, use the gcloud command and the instances create sub-command, followed by the --custom-extensions flag to enable extended memory. Then, specify the total memory that you want with the --custom- memory parameter.

gcloud compute instances create example-instance  \
    --custom-extensions --custom-cpu=2 --custom-memory=15

For N2 machine types, use the gcloud command with the instances create sub-command. Set the --custom-extensions, --custom-cpu, and --custom-memory flags, followed by the --custom-vm-type flag, to specify the N2 machine type:

gcloud compute instances create example-instance \
    --custom-extensions --custom-cpu=2 --custom-memory=16 \
    --custom-vm-type=n2

For N2D machine types, use the gcloud command with the instances create sub-command. Set the --custom-extensions, --custom-cpu, and --custom-memory flags, followed by the --custom-vm-type flag, to specify the N2D machine type:

gcloud compute instances create example-instance \
    --custom-extensions --custom-cpu=2 --custom-memory=16 \
    --custom-vm-type=n2d

API

In the API, construct your instance creation request as you would normally, but when specifying a machineType value, use one of the following formats:

• For N1 machine types, use:

  zones/ZONE/machineTypes/custom-NUMBER_OF_CPUS-AMOUNT_OF_MEMORY-ext
  

• For N2 machine types, use:

  zones/ZONE/machineTypes/n2-custom-NUMBER_OF_CPUS-AMOUNT_OF_MEMORY-ext
  

• For N2D machine types, use:

  zones/ZONE/machineTypes/n2d-custom-NUMBER_OF_CPUS-AMOUNT_OF_MEMORY-ext
  

Replace the following:

• NUMBER_OF_CPUS: The number of vCPUs.
• AMOUNT_OF_MEMORY: The memory, in MB.

For example, the following specifies an N2 machine type with 2 vCPUs and 20 GB of memory:

zones/ZONE/machineTypes/n2-custom-2-20480-ext

Add extended memory to an existing VM instance

To add more memory to an existing instance, you must first stop the instance. After the instance stops, follow the instructions below to add more memory to the VM.

Permissions required for this task

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

• compute.instances.setMachineType on the instance

Console

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

   Go to VM instances

2. Choose the stopped VM you want to modify from the VM list.

3. Click Edit at the top of the page.

4. In Machine configuration, select General-purpose.

5. From the Machine type list, select Custom.

6. Select the number of vCPUs you want.

7. To add extended memory, select Extend memory and then specify the amount of memory you want.

8. Save your changes.

gcloud

Using the gcloud command-line tool, use the instances set-machine-type sub-command, followed by the --custom-extensions flag paired with the existing --custom-memory parameter.

For example, to add 2 GB memory to a VM instance named example-instance, which currently has an N1 machine type with 2 vCPU, 13 GB, in the us-central1-b zone, use the following command:

gcloud compute instances set-machine-type example-instance \
   --zone=us-central1-b --custom-cpu=2 \
   --custom-memory=15 --custom-extensions

API

In the API, make a POST request to the setMachineType method with the desired machine type in the request body. Use one of the following formats:

• For N1 machine types, use:

  zones/ZONE/machineTypes/custom-NUMBER_OF_CPUS-AMOUNT_OF_MEMORY-ext
  

• For N2 machine types, use:

  zones/ZONE/machineTypes/n2-custom-NUMBER_OF_CPUS-AMOUNT_OF_MEMORY-ext
  

• For N2D machine types, use:

  zones/ZONE/machineTypes/n2d-custom-NUMBER_OF_CPUS-AMOUNT_OF_MEMORY-ext
  

Replace the following:

• NUMBER_OF_CPUS: The number of vCPUs.
• AMOUNT_OF_MEMORY: The memory, in MB.

For example, the following request uses a machine type with 2 vCPUs and 15 GB of memory:

zones/ZONE/machineTypes/custom-2-15360-ext

For example:

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

{
    machineType: "zones/us-central1-f/machineTypes/custom-2-15360-ext"
}

What's next

• Learn more about machine families.
• After creating a VM, step through a tutorial to start using a VM instance.
• Learn how to connect to your VM instance.