This document describes the prerequisites required for creating managed instance groups (MIGs) that use A4 or A3 Ultra accelerator-optimized machine types.
Create a MIG if you want to manage multiple virtual machines (VMs) as a single entity. MIGs offer high availability and scalability by automatically managing the VMs in the group. To learn more about MIGs, see Managed instance groups in the Compute Engine documentation.
To learn about other ways to create VMs or clusters, see the Overview page.
Before you begin
Before creating a MIG, complete the following steps if you haven't already:
- Choose a consumption option: the option that you pick determines how you want to get and use GPU resources.
- Obtain capacity: to learn how to obtain capacity for your consumption option.
- Optional: Create a placement policy: to place your VMs in a single block or sub-block and minimize network latency, you can optionally use a compact placement policy. This approach is useful for workloads that require fast communication among VMs. However, if you need to place your VMs on a specific block to meet particular hardware or network requirements, skip this step and specify the block name when you create the instance template.
- Create a regional instance template: to specify the VM configuration, including whether to create your VMs in a specific block within the reservation.
To learn more, see Choose a consumption option.
To learn more, see Obtain capacity.
For instructions, see Create a compact placement policy.
For instructions, see Create a regional instance template.
Limitations
Limitations for A4 or A3 Ultra MIGs
When you create a MIG with A4 or A3 Ultra VMs, the following limitations apply:
If the instance template to use for the MIG specifies the flex-start provisioning model (Preview), then the following limitations apply:
You can only create zonal MIGs.
You can only add VMs to the MIG using resize requests.
If you create a regional MIG, then the MIG can only create VMs in the zone that contains your VPC network's profile.
You can't configure instance flexibility in the MIG.
Limitations for MIG resize requests
When you create MIG resize requests, the following limitations apply:
In a regional MIG, you can use only the
ANY_SINGLE_ZONE
target distribution shape (Preview). Other distribution shapes aren't supported.You can only set the standby pool mode of the MIG to
manual
(default).You can't set autoscaling.
If the MIG contains accepted resize requests, then you can't do the following:
You can't add a second instance template to initiate a canary update in the MIG.
You can't change the target size of the MIG.
You can't delete or abandon the managed instances in a
CREATING
status that the MIG creates for a resize request. To delete those managed instances, you must cancel the resize request.
Overview
This document describes how to complete the following tasks:
Optional: Create a compact placement policy. Use this policy to place your VMs in a single or adjacent blocks.
However, if you want your VMs to be on a specific block, skip this step and provide the name of the required block during the instance template creation.
Required: Create an instance template. This instance template is used to define the VM properties that the MIG will use to create each VM in the group.
Compact placement policy
When you apply compact placement policies to your VMs, Compute Engine makes best-effort
attempts to create VMs as close to each other as possible. If you require a minimum compactness to
minimize network latency, then specify the maxDistance
field
(Preview)
when creating a placement policy. A lower maxDistance
value ensures closer VM
placement, but it also increases the chance that some VMs won't be created.
The following table shows the machine series and number of VMs that each maxDistance
value supports:
Maximum distance value | Description | Supported machine series | Maximum number of VMs |
---|---|---|---|
Unspecified (Not recommended) | Compute Engine makes best-effort attempts to place the VMs as close to each other as possible, but with no maximum distance between VMs. | A4 and A3 Ultra | 1,500 |
3 | Compute Engine creates VMs in adjacent blocks. | A4 | 1,500 |
2 | Compute Engine creates VMs in the same block. | A4 and A3 Ultra | For A4 VMs: 150, for A3 Ultra VMs: 256 |
Create a compact placement policy
To create a compact placement policy, select one of the following options:gcloud
To create a compact placement policy, use the
gcloud beta compute resource-policies create group-placement
command:
gcloud beta compute resource-policies create group-placement POLICY_NAME \ --collocation=collocated \ --max-distance=MAX_DISTANCE \ --region=REGION
Replace the following:
POLICY_NAME
: the name of the compact placement policy.MAX_DISTANCE
: the maximum distance configuration for your VMs. The value must be3
to place VMs in the adjacent blocks, or2
to place VMs in the same block.REGION
: the region where you want to create the placement policy. Specify a region in which the machine type that you want to use is available. For information about regions, see GPU regions and zones.
REST
To create a compact placement policy, make a POST
request to the
beta
resourcePolicies.insert
method. In the request body, include the
collocation
field set to COLLOCATED
, and the maxDistance
field.
POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/resourcePolicies { "name": "POLICY_NAME", "groupPlacementPolicy": { "collocation": "COLLOCATED", "maxDistance": MAX_DISTANCE } }
Replace the following:
PROJECT_ID
: your project IDPOLICY_NAME
: the name of the compact placement policy.MAX_DISTANCE
: the maximum distance configuration for your VMs. The value must be3
to place VMs in the adjacent blocks, or2
to place VMs in the same block.REGION
: the region where you want to create the placement policy. Specify a region in which the machine type that you want to use is available. For information about regions, see GPU regions and zones.
Instance template
Each VM in a MIG is based on an instance template. To create an instance template, complete the following steps:
- Create VPC networks. Use these networks to provide connectivity between the VMs.
- Create an instance template. Use this instance template to specify the machine type, network, and other VM properties that you want to use to create VMs in the MIG.
Create VPC networks
Based on the machine type that you want to use and the number of network interfaces in the machine type, you need to create Virtual Private Cloud (VPC) networks as follows:
Machine type | Physical NIC count* | Network interfaces† | Number of VPC networks to create |
---|---|---|---|
a4-highgpu-8g |
10 |
|
3 |
a3-ultragpu-8g |
10 |
|
3 |
Set up the networks either manually by following the instruction guides or automatically by using the provided script.
Instruction guides
To create the networks, you can use the following instructions:
- To create the host networks, see Create and manage Virtual Private Cloud networks.
- To create the GPU networks, see Create a Virtual Private Cloud network for RDMA NICs.
Script
To create the networks, you can use the following script.
#!/bin/bash # Create standard VPCs (network and subnets) for the gVNICs for N in $(seq 0 1); do gcloud compute networks create GVNIC_NAME_PREFIX-net-$N \ --subnet-mode=custom gcloud compute networks subnets create GVNIC_NAME_PREFIX-sub-$N \ --network=GVNIC_NAME_PREFIX-net-$N \ --region=REGION \ --range=10.$N.0.0/16 gcloud compute firewall-rules create GVNIC_NAME_PREFIX-internal-$N \ --network=GVNIC_NAME_PREFIX-net-$N \ --action=ALLOW \ --rules=tcp:0-65535,udp:0-65535,icmp \ --source-ranges=10.0.0.0/8 done # Create SSH firewall rules gcloud compute firewall-rules create GVNIC_NAME_PREFIX-ssh \ --network=GVNIC_NAME_PREFIX-net-0 \ --action=ALLOW \ --rules=tcp:22 \ --source-ranges=IP_RANGE # Assumes that an external IP is only created for vNIC 0 gcloud compute firewall-rules create GVNIC_NAME_PREFIX-allow-ping-net-0 \ --network=GVNIC_NAME_PREFIX-net-0 \ --action=ALLOW \ --rules=icmp \ --source-ranges=IP_RANGE # List and make sure network profiles exist gcloud compute network-profiles list # Create network for CX-7 gcloud compute networks create RDMA_NAME_PREFIX-mrdma \ --network-profile=ZONE-vpc-roce \ --subnet-mode custom # Create subnets. for N in $(seq 0 7); do gcloud compute networks subnets create RDMA_NAME_PREFIX-mrdma-sub-$N \ --network=RDMA_NAME_PREFIX-mrdma \ --region=REGION \ --range=10.$((N+2)).0.0/16 # offset to avoid overlap with gVNICs done
Replace the following:
GVNIC_NAME_PREFIX
: the name prefix to use for the standard VPC networks and subnets that use gVNIC NICs.RDMA_NAME_PREFIX
: the name prefix to use for the VPC networks and subnets that use RDMA NICs.ZONE
: specify a zone in which the machine type that you want to use is available. For information about regions, see GPU regions and zones.REGION
: the region where you want to create the subnets. This region must correspond to the zone specified. For example, if your zone iseurope-west1-b
, then your region iseurope-west1
.IP_RANGE
: the IP range to use for the SSH firewall rules.
Create an instance template
Before creating an instance template, ensure that you created the VPC networks as mentioned in the previous section.
gcloud
The parameters that you need to specify depend on the consumption option that you are using for this deployment. Select the tab that corresponds to your consumption option's provisioning model.
Flex-start
To create a regional instance template, use the
gcloud beta compute instance-templates create
command.
gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \ --machine-type=MACHINE_TYPE \ --image-family=IMAGE_FAMILY \ --image-project=IMAGE_PROJECT \ --instance-template-region=REGION \ --boot-disk-type=hyperdisk-balanced \ --boot-disk-size=DISK_SIZE \ --scopes=cloud-platform \ --network-interface=nic-type=GVNIC,network=GVNIC_NAME_PREFIX-net-0,subnet=GVNIC_NAME_PREFIX-sub-0 \ --network-interface=nic-type=GVNIC,network=GVNIC_NAME_PREFIX-net-1,subnet=GVNIC_NAME_PREFIX-sub-1,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-0,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-1,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-2,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-3,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-4,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-5,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-6,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-7,no-address \ --reservation-affinity=none \ --instance-termination-action=DELETE \ --max-run-duration=RUN_DURATION \ --maintenance-policy=TERMINATE \ --provisioning-model=FLEX_START
Replace the following:
INSTANCE_TEMPLATE_NAME
: the name of the instance template.MACHINE_TYPE
: the machine type to use for the VM. Specify either an A4 or A3 Ultra machine type. For more information, see GPU machine types.IMAGE_FAMILY
: the image family of the OS image that you want to use. For a list of supported operating systems, see Supported operating systems.IMAGE_PROJECT
: the project ID of the OS image.REGION
: the region where you want to create the instance template. Specify a region in which the machine type that you want to use is available. If you want to specify a compact placement policy, then you must use the same region as the compact placement policy. For information about regions, see GPU regions and zones.DISK_SIZE
: the size of the boot disk in GB.GVNIC_NAME_PREFIX
: the name prefix to use for the standard VPC networks and subnets that use gVNIC NICs.RDMA_NAME_PREFIX
: the name prefix to use for the VPC networks and subnets that use RDMA NICs.RUN_DURATION
: the duration you want the requested VMs to run. You must format the value as the number of days, hours, minutes, or seconds followed byd
,h
,m
, ands
respectively. For example, specify30m
for 30 minutes or1d2h3m4s
for one day, two hours, three minutes, and four seconds. The value must be between 10 minutes and seven days.
Reservation-bound
To create a regional instance template, use the
gcloud compute instance-templates create
command.
Before running the command, optionally add the flag for a compact placement policy.
gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \ --machine-type=MACHINE_TYPE \ --image-family=IMAGE_FAMILY \ --image-project=IMAGE_PROJECT \ --instance-template-region=REGION \ --boot-disk-type=hyperdisk-balanced \ --boot-disk-size=DISK_SIZE \ --scopes=cloud-platform \ --network-interface=nic-type=GVNIC,network=GVNIC_NAME_PREFIX-net-0,subnet=GVNIC_NAME_PREFIX-sub-0 \ --network-interface=nic-type=GVNIC,network=GVNIC_NAME_PREFIX-net-1,subnet=GVNIC_NAME_PREFIX-sub-1,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-0,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-1,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-2,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-3,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-4,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-5,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-6,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-7,no-address \ --reservation-affinity=specific \ --reservation=RESERVATION \ --provisioning-model=RESERVATION_BOUND \ --instance-termination-action=DELETE \ --maintenance-policy=TERMINATE
Complete the following steps:
-
Replace the following:
INSTANCE_TEMPLATE_NAME
: the name of the instance template.MACHINE_TYPE
: the machine type to use for the VM. Specify either an A4 or A3 Ultra machine type. For more information, see GPU machine types.IMAGE_FAMILY
: the image family of the OS image that you want to use. For a list of supported operating systems, see Supported operating systems.IMAGE_PROJECT
: the project ID of the OS image.REGION
: the region where you want to create the instance template. Specify a region in which the machine type that you want to use is available. If you want to specify a compact placement policy, then you must use the same region as the compact placement policy. For information about regions, see GPU regions and zones.DISK_SIZE
: the size of the boot disk in GB.GVNIC_NAME_PREFIX
: the name prefix to use for the standard VPC networks and subnets that use gVNIC NICs.RDMA_NAME_PREFIX
: the name prefix to use for the VPC networks and subnets that use RDMA NICs.RESERVATION
: either the reservation name or a specific block within a reservation. To get the reservation name or the available blocks, see View capacity. Choose one of the following:Reservation value When to use projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME
Use this value when one of the following is true:
- You are using a compact placement policy. Compute Engine applies the policy to the reservation and creates the VMs on a single block.
- You aren't using a compact placement policy, and it's acceptable to create the VMs on any of the reserved blocks.
projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME/reservationBlocks/RESERVATION_BLOCK_NAME
Use this value when you aren't using a compact placement policy, and you want to create VMs on a specific reserved block.
Optional: If you chose to use a compact placement policy, then add the following flag to the command:
--resource-policies=POLICY_NAME
Replace the following:
POLICY_NAME
: the name of the compact placement policy.
- Run the command.
Spot
To create a regional instance template, use the
gcloud compute instance-templates create
command.Before running the command, optionally add the flag for a compact placement policy.
gcloud compute instance-templates create INSTANCE_TEMPLATE_NAME \ --machine-type=MACHINE_TYPE \ --image-family=IMAGE_FAMILY \ --image-project=IMAGE_PROJECT \ --instance-template-region=REGION \ --boot-disk-type=hyperdisk-balanced \ --boot-disk-size=DISK_SIZE \ --scopes=cloud-platform \ --network-interface=nic-type=GVNIC,network=GVNIC_NAME_PREFIX-net-0,subnet=GVNIC_NAME_PREFIX-sub-0 \ --network-interface=nic-type=GVNIC,network=GVNIC_NAME_PREFIX-net-1,subnet=GVNIC_NAME_PREFIX-sub-1,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-0,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-1,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-2,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-3,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-4,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-5,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-6,no-address \ --network-interface=nic-type=MRDMA,network=RDMA_NAME_PREFIX-mrdma,subnet=RDMA_NAME_PREFIX-mrdma-sub-7,no-address \ --provisioning-model=SPOT \ --instance-termination-action=TERMINATION_ACTION
Complete the following steps:
-
Replace the following:
INSTANCE_TEMPLATE_NAME
: the name of the instance template.MACHINE_TYPE
: the machine type to use for the VM. Specify either an A4 or A3 Ultra machine type. For more information, see GPU machine types.IMAGE_FAMILY
: the image family of the OS image that you want to use. For a list of supported operating systems, see Supported operating systems.IMAGE_PROJECT
: the project ID of the OS image.REGION
: the region where you want to create the instance template. Specify a region in which the machine type that you want to use is available. If you want to specify a compact placement policy, then you must use the same region as the compact placement policy. For information about regions, see GPU regions and zones.DISK_SIZE
: the size of the boot disk in GB.GVNIC_NAME_PREFIX
: the name prefix to use for the standard VPC networks and subnets that use gVNIC NICs.RDMA_NAME_PREFIX
: the name prefix to use for the VPC networks and subnets that use RDMA NICs.TERMINATION_ACTION
: the action to take when Compute Engine preempts the instance, eitherSTOP
(default) orDELETE
.
-
Optional: If you chose to use a compact placement policy, then add the following flag to the command:
--resource-policies=POLICY_NAME
Replace the following:
POLICY_NAME
: the name of the compact placement policy.
- Run the command.
REST
The parameters that you need to specify depend on the consumption option that you are using for this deployment. Select the tab that corresponds to your consumption option's provisioning model.
Flex-start
To create a regional instance template, make a
POST
request to thebeta regionInstanceTemplates.insert
method.POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceTemplates { "name":"INSTANCE_TEMPLATE_NAME", "properties":{ "disks":[ { "boot":true, "initializeParams":{ "diskSizeGb":"DISK_SIZE", "diskType":"hyperdisk-balanced", "sourceImage":"projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY" }, "mode":"READ_WRITE", "type":"PERSISTENT" } ], "machineType":"MACHINE_TYPE", "networkInterfaces": [ { "accessConfigs": [ { "name": "external-nat", "type": "ONE_TO_ONE_NAT" } ], "network": "projects/NETWORK_PROJECT_ID/global/networks/GVNIC_NAME_PREFIX-net-0", "nicType": "GVNIC", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/GVNIC_NAME_PREFIX-sub-0" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/GVNIC_NAME_PREFIX-net-1", "nicType": "GVNIC", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/GVNIC_NAME_PREFIX-sub-1" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-0" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-1" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-2" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-3" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-4" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-5" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-6" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-7" } ], "reservationAffinity": { "consumeReservationType": "NO_RESERVATION" }, "scheduling": { "instanceTerminationAction": "DELETE", "maxRunDuration": { "seconds": RUN_DURATION }, "onHostMaintenance": "TERMINATE", "provisioningModel": "FLEX_START" } } }
Replace the following:
INSTANCE_TEMPLATE_NAME
: the name of the instance template.MACHINE_TYPE
: the machine type to use for the VM. Specify either an A4 or A3 Ultra machine type. For more information, see GPU machine types.IMAGE_FAMILY
: the image family of the OS image that you want to use. For a list of supported operating systems, see Supported operating systems.IMAGE_PROJECT
: the project ID of the OS image.REGION
: the region where you want to create the instance template. Specify a region in which the machine type that you want to use is available. If you want to specify a compact placement policy, then you must use the same region as the compact placement policy. For information about regions, see GPU regions and zones.DISK_SIZE
: the size of the boot disk in GB.NETWORK_PROJECT_ID
: the project ID of the network.GVNIC_NAME_PREFIX
: the name prefix to use for the standard VPC networks and subnets that use gVNIC NICs.REGION
: the region of the subnetwork.RDMA_NAME_PREFIX
: the name prefix to use for the VPC networks and subnets that use RDMA NICs.RUN_DURATION
: the duration, in seconds, you want the requested VMs to run. The value must be between600
, which is 600 seconds (10 minutes), and604800
, which is 604,800 seconds (seven days).
Reservation-bound
To create a regional instance template, make a
POST
request to theregionInstanceTemplates.insert
method.Before submitting the request, optionally add the
properties
subfield for a compact placement policy to the request body.POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceTemplates { "name":"INSTANCE_TEMPLATE_NAME", "properties":{ "disks":[ { "boot":true, "initializeParams":{ "diskSizeGb":"DISK_SIZE", "diskType":"hyperdisk-balanced", "sourceImage":"projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY" }, "mode":"READ_WRITE", "type":"PERSISTENT" } ], "machineType":"MACHINE_TYPE", "networkInterfaces": [ { "accessConfigs": [ { "name": "external-nat", "type": "ONE_TO_ONE_NAT" } ], "network": "projects/NETWORK_PROJECT_ID/global/networks/GVNIC_NAME_PREFIX-net-0", "nicType": "GVNIC", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/GVNIC_NAME_PREFIX-sub-0" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/GVNIC_NAME_PREFIX-net-1", "nicType": "GVNIC", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/GVNIC_NAME_PREFIX-sub-1" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-0" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-1" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-2" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-3" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-4" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-5" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-6" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-7" } ], "reservationAffinity":{ "consumeReservationType":"SPECIFIC_RESERVATION", "key":"compute.googleapis.com/reservation-name", "values":[ "RESERVATION" ] }, "scheduling":{ "provisioningModel":"RESERVATION_BOUND", "instanceTerminationAction":"DELETE", "onHostMaintenance": "TERMINATE", "automaticRestart":true } } }
Complete the following steps:
-
Replace the following:
INSTANCE_TEMPLATE_NAME
: the name of the instance template.MACHINE_TYPE
: the machine type to use for the VM. Specify either an A4 or A3 Ultra machine type. For more information, see GPU machine types.IMAGE_FAMILY
: the image family of the OS image that you want to use. For a list of supported operating systems, see Supported operating systems.IMAGE_PROJECT
: the project ID of the OS image.REGION
: the region where you want to create the instance template. Specify a region in which the machine type that you want to use is available. If you want to specify a compact placement policy, then you must use the same region as the compact placement policy. For information about regions, see GPU regions and zones.DISK_SIZE
: the size of the boot disk in GB.NETWORK_PROJECT_ID
: the project ID of the network.GVNIC_NAME_PREFIX
: the name prefix to use for the standard VPC networks and subnets that use gVNIC NICs.REGION
: the region of the subnetwork.RDMA_NAME_PREFIX
: the name prefix to use for the VPC networks and subnets that use RDMA NICs.RESERVATION
: either the reservation name or a specific block within a reservation. To get the reservation name or the available blocks, see View capacity. Choose one of the following:Reservation value When to use projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME
Use this value when one of the following is true:
- You are using a compact placement policy. Compute Engine applies the policy to the reservation and creates the VMs on a single block.
- You aren't using a compact placement policy, and it's acceptable to create the VMs on any of the reserved blocks.
projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME/reservationBlocks/RESERVATION_BLOCK_NAME
Use this value when you aren't using a compact placement policy, and you want to create VMs on a specific reserved block.
Optional: If you chose to use a compact placement policy, then add the following
properties
subfield to the request body:"resourcePolicies": [ "projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME" ]
Replace the following:
PROJECT_ID
: the project ID of the compact placement policy.REGION
: the region of the compact placement policy.POLICY_NAME
: the name of the compact placement policy.
- Submit the request.
Spot
To create a regional instance template, make a
POST
request to theregionInstanceTemplates.insert
method.Before submitting the request, optionally add the
properties
subfield for a compact placement policy to the request body.POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceTemplates { "name":"INSTANCE_TEMPLATE_NAME", "properties":{ "disks":[ { "boot":true, "initializeParams":{ "diskSizeGb":"DISK_SIZE", "diskType":"hyperdisk-balanced", "sourceImage":"projects/IMAGE_PROJECT/global/images/family/IMAGE_FAMILY" }, "mode":"READ_WRITE", "type":"PERSISTENT" } ], "machineType":"MACHINE_TYPE", "networkInterfaces": [ { "accessConfigs": [ { "name": "external-nat", "type": "ONE_TO_ONE_NAT" } ], "network": "projects/NETWORK_PROJECT_ID/global/networks/GVNIC_NAME_PREFIX-net-0", "nicType": "GVNIC", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/GVNIC_NAME_PREFIX-sub-0" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/GVNIC_NAME_PREFIX-net-1", "nicType": "GVNIC", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/GVNIC_NAME_PREFIX-sub-1" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-0" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-1" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-2" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-3" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-4" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-5" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-6" }, { "network": "projects/NETWORK_PROJECT_ID/global/networks/RDMA_NAME_PREFIX-mrdma", "nicType": "MRDMA", "subnetwork": "projects/NETWORK_PROJECT_ID/region/REGION/subnetworks/RDMA_NAME_PREFIX-mrdma-sub-7" } ], "scheduling": { "provisioningModel": "SPOT", "instanceTerminationAction": "TERMINATION_ACTION" } } }
Complete the following steps:
-
Replace the following:
INSTANCE_TEMPLATE_NAME
: the name of the instance template.MACHINE_TYPE
: the machine type to use for the VM. Specify either an A4 or A3 Ultra machine type. For more information, see GPU machine types.IMAGE_FAMILY
: the image family of the OS image that you want to use. For a list of supported operating systems, see Supported operating systems.IMAGE_PROJECT
: the project ID of the OS image.REGION
: the region where you want to create the instance template. Specify a region in which the machine type that you want to use is available. If you want to specify a compact placement policy, then you must use the same region as the compact placement policy. For information about regions, see GPU regions and zones.DISK_SIZE
: the size of the boot disk in GB.NETWORK_PROJECT_ID
: the project ID of the network.GVNIC_NAME_PREFIX
: the name prefix to use for the standard VPC networks and subnets that use gVNIC NICs.REGION
: the region of the subnetwork.RDMA_NAME_PREFIX
: the name prefix to use for the VPC networks and subnets that use RDMA NICs.TERMINATION_ACTION
: the action to take when Compute Engine preempts the instance, eitherSTOP
(default) orDELETE
.
-
Optional: If you chose to use a compact placement policy, then add the following
properties
subfield to the request body:"resourcePolicies": [ "projects/PROJECT_ID/regions/REGION/resourcePolicies/POLICY_NAME" ]
Replace the following:
PROJECT_ID
: the project ID of the compact placement policy.REGION
: the region of the compact placement policy.POLICY_NAME
: the name of the compact placement policy.
- Submit the request.
What's next?
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-05-21 UTC.