Creating a VM Instance with a custom machine type

Compute Engine offers predefined machine types that you can use when you create an instance. A predefined machine type has a preset number of vCPUs, and amount of memory, and are charged at a set price as described in All pricing page.

If predefined machine types don't meet your needs, you can create an instance with custom virtualized hardware settings. Specifically, you can create an instance with a custom number of vCPUs and amount of memory, effectively using a custom machine type. Custom machine types are available for general-purpose machine types only; that is, when you create a custom machine type, you are effectively deploying a custom machine type from the N1, N2, N2D, or E2 machine type family.

Custom machine types are ideal for the following scenarios:

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

Before you begin

If you want to use the command-line examples in this guide:
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 types documentation.

Specifications

General

The total memory for a custom machine type must be a multiple of 256 MB. For example, 6.9 GB is not supported, but 6.75 GB and 7 GB are supported.
Above 1, the instance vCPU count must be even, such as 2, 4, 6, 8, 10, and so on.
Instances with custom machine types have the same persistent disk capacity limitations as instances with predefined machine types.
Custom machine types are subject to the same persistent disk limits as general-purpose machine types. Currently, the max total persistent disk size for each machine type per instance is 257 TB and the max number of persistent disks is 128.

N1 custom machine types

The maximum number of vCPUs allowed for a custom machine type is determined by the machine type family you choose. For N1 machine types:
- If you deploy in a zone that supports the Skylake CPU platform, you can create custom machine types with up to 96 vCPUs.
- If you deploy in zones that support the Broadwell, Haswell, or Ivy Bridge CPU platforms, you can deploy custom machine types with up to 64 vCPUs.
To see which platforms are available in each zone, read the regions and zones table.
By default, the memory per vCPU that you can select for a custom machine type is determined by the machine type family. For N1 machine types, select between 0.9 GB and 6.5 GB per vCPU, inclusive. Higher amounts of memory are possible by enabling extended memory.

Examples of invalid machine types

1 vCPU, 0.2 GB of total memory. Invalid because the total memory is less than the minimum 0.9 for an N1 machine type.
1 vCPU, 0.9 GB of total memory. Invalid because the total memory must be a multiple of 256 MB. For 1 vCPU, use a minimum of 1024 MB memory.

Examples of valid machine types

32 vCPUs, 29 GB of total memory. Valid because the total number of vCPUs is even and the total memory is a multiple of 256 MB. The amount of memory per vCPU is 0.9 GB, which satisfies the minimum requirement.
1 vCPU, 1 GB of total memory. Valid because it has one vCPU, which is the minimum value, and the total memory is a multiple of 256 MB. The amount of memory per vCPU is also between the acceptable range of 0.9 GB to 6.5 GB per vCPU.

N2 custom machine types

The maximum number of vCPUs allowed for a custom machine type is determined by the machine type family you choose. For N2 machine types, which only support the Cascade Lake platform, you can deploy custom machine types with 2 to 80 vCPUs.
N2 machines are only available in select zones. To learn more, read the regions and zones page.
By default, the memory per vCPU that you can select for a custom machine type is determined by the machine type family. For N2 machine types, select between 0.5 GB and 8.0 GB per vCPU, inclusive. Higher amounts of memory are possible by enabling extended memory.
If the instance has a vCPU count that is 32 vCPUs or higher, the vCPU count must be evenly divisible by 4. So, for example, 32, 36, and 40 vCPUs are all valid, but 38 is invalid.

Examples of invalid machine types

2 vCPUs, 0.8 GB of total memory. Invalid because the total memory is less than the minimum 0.5 for an N2 machine type.
34 vCPUs, 34 GB of total memory. Invalid because the total number of vCPUs is not divisible by 4.
1 vCPU, 1024 MB of memory. Invalid because the vCPU count is too small. N2 custom machine types require a minimum of 2 vCPUs.

Examples of valid machine types

36 vCPUs, 18 GB of total memory. Valid because the total number of vCPUs is even and the total memory is a multiple of 256 MB. The amount of memory per vCPU is 0.5 GB, which satisfies the minimum requirement. Because the number of vCPUs is larger than 32 vCPUs, the number of vCPUs must be divisible by 4.
2 vCPUs, 7 GB of total memory. Valid because it has 2 vCPUs, which is the minimum value, and the total memory is a multiple of 256 MB. The amount of memory per vCPU is also between the acceptable range of 0.5 GB to 8 GB per vCPU.

N2D custom machine types

The maximum number of vCPUs allowed for a custom machine type is determined by the machine type family you choose. For N2D machine types, which support the AMD EPYC Rome platform, you can deploy custom machine types with 2 to 96 vCPUs.
You can create VMs with vCPUs in multiples of 4 with up to 8 vCPUs. For VMs with more than 16 vCPUs, you can create custom VMs with a vCPU count in multiples of 16.
N2D machines are only available in select zones. To learn more, read the regions and zones page.
By default, the memory per vCPU that you can select for a custom machine type is determined by the machine type family. For N2D machine types, select between 0.5 GB and 8.0 GB per vCPU, inclusive. Higher amounts of memory are possible by enabling extended memory.

Examples of invalid machine types

2 vCPUs, 0.4 GB of total memory. Invalid because the total memory is less than the minimum 0.5 for an N2D machine type.
34 vCPUs, 34 GB of total memory. Invalid because the total number of vCPUs is not divisible by 16.
1 vCPU, 1024 MB of memory. Invalid because the vCPU count is too small. N2D custom machine types require a minimum of 2 vCPUs.

Examples of valid machine types

32 vCPUs, 16 GB of total memory. Valid because the total number of vCPUs is even and the total memory is a multiple of 256 MB. The amount of memory per vCPU is 0.5 GB, which satisfies the minimum requirement. Because the number of vCPUs is larger than 8 vCPUs, the number of vCPUs must be divisible by 16.
2 vCPUs, 7 GB of total memory. Valid because it has 2 vCPUs, which is the minimum value, and the total memory is a multiple of 256 MB. The amount of memory per vCPU is also between the acceptable range of 0.5 GB to 8 GB per vCPU.

E2 custom machine types

The maximum number of vCPUs allowed for a custom machine type is determined by the machine type family you choose. E2 machine types support predefined platforms with Intel or AMD EPYC Rome processors, you can deploy custom machine types with 2 to 16 vCPUs.
By default, the memory per vCPU that you can select for a custom machine type is determined by the machine type family. For E2 machine types, select 0.5 GB to 8 GB per vCPU, inclusive.
E2 machines are only available in select zones. To learn more, read the regions and zones page.

Examples of invalid machine types

1 vCPU, 1024 MB of memory. Invalid because the vCPU count is too small. E2 custom machine types require a minimum of 2 vCPUs.
16 vCPUs, 1 GB of total memory. Invalid because the ratio of vCPUs to memory is below 0.5 GB per vCPU.

Examples of valid machine types

16 vCPUs, 4 GB of total memory. Valid because the total number of vCPUs is even and the total memory is a multiple of 256 MB.
2 vCPUs, 8 GB of total memory. Valid because it has 2 vCPUs, which is the minimum value, and the total memory is a multiple of 256 MB. The amount of memory per vCPU is also between the acceptable range of 0.5 GB to 8 GB per vCPU.

Pricing

Google charges for custom machine types based on the number of vCPUs and memory hours that the instance uses. This is different from how predefined machine types are charged, so we recommend you review the pricing page before you create a custom machine type.

Instances running a custom machine type 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, read sustained use discounts for custom machine types.

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 MB units. If you use the gcloud command-line tool, it is possible to provide the total memory for an instance in GB or MB units. 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.

Creating an instance with a custom machine type

Before you create an instance, make sure you read and understand the Specifications for creating a custom machine type.

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

In the Google Cloud Console, go to the Create an instance page.
Go to the Create an instance page
Under Zone, select the zone where you want to host this instance. This filters the list of machine types to only those types that are available in that zone.
Under Machine configuration, select General-purpose.
From the Series list, select N1 under First Generation for N1 custom machine types or E2, N2, or N2D for Second Generation custom machine types.
From the Machine type list, select Custom.
Drag the sliders to choose the number of vCPUs and the amount of memory for the instance. The console displays an estimated cost for the instance as you change the number of vCPUs and memory.
Save your changes and continue with the rest of the creation process.

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, you want.

For example:

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

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

The --custom-cpu, --custom-memory, and --custom-vm-type flags.
The --machine-type=e2-custom-number-of-cpus-number-of-mb flag.
The --machine-type=n2d-custom-number-of-cpus-number-of-mb flag.

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

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

gcloud beta 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, you want.

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 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 also create preemptible instances with a custom machine type, or create groups of instances with a custom machine type by specifying a custom machine type in the formats described above.

Adding extended memory to a machine type

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

For some workloads, this might not be enough memory. At an additional 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 allow you to create instances with a total of 1.4 TB per VM instance.

Determining if 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 analytics, high performance databases, including relational and NoSQL databases such as MS SQL Server, MongoDB and MemcacheD/Redis, fall into this category. vCPU-based licensing of operating systems and software stacks also make selecting an optimal VM memory configuration more challenging with predefined machine types. By using extended memory, you can add as much memory as you need to reach the best price and performance for your VM instances.

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. 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. Note that 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

For pricing information, see extended custom memory pricing.

Limitations

You can only add extended memory to custom machine types. Predefined machine types are not supported.
There is no limit of 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 only available in select regions and zones.
You must specify memory in 256 MB increments.
Extended memory does not qualify for committed use discounts.

Adding 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

In the Google Cloud Console, go to the Create an instance page.
Go to the Create an instance page
Under Zone, select the zone where you want to host this instance. This will also filter the list of machine types to only types available in that zone.
Under Machine configuration, select General-purpose.
From the Series drop-down, select First for N1 custom machine types or Second for N2 or N2D custom machine types.
From the Machine type drop down, select Custom.
Select the amount of memory you want. To add extended memory, check the Extend memory option. The range of selectable memory expands.
Continue with the instance creation process.

gcloud

For N1 machine types, use the gcloud command and the instances create subcommand, 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 subcommand. 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 beta command with the instances create subcommand. Set the --custom-extensions, --custom-cpu, and --custom-memory flags, followed by the --custom-vm-type flag, to specify the N2D machine type:

gcloud beta 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 amount of memory, in MB, you want.

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

Adding 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

In the Google Cloud Console, go to the VM instances page.
Go to the VM instances page
Choose the stopped instance you want to modify from the instance list.
Click Edit at the top of the page.
Under Machine configuration, select General-purpose.
From the Machine type list, select Custom.
Select the amount of vCPU you want.
Select the amount of memory you want. To add extended memory, check the Extend memory option. The range of selectable memory expands.
Save your changes.

gcloud

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

For example, to add 2 GB memory to an 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 amount of memory, in MB, you want.

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 types.
After creating a VM, read a tutorial to get started using an instance.
Learn how to connect to your instance.