Prerequisites for MIGs

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:

  1. Choose a consumption option: the option that you pick determines how you want to get and use GPU resources.
  2. To learn more, see Choose a consumption option.

  3. Obtain capacity: to learn how to obtain capacity for your consumption option.
  4. To learn more, see Obtain capacity.

  5. 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.
  6. For instructions, see Create a compact placement policy.

  7. Create a regional instance template: to specify the VM configuration, including whether to create your VMs in a specific block within the reservation.
  8. 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:

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:

  1. 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.

  2. 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 be 3 to place VMs in the adjacent blocks, or 2 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 ID
  • POLICY_NAME: the name of the compact placement policy.
  • MAX_DISTANCE: the maximum distance configuration for your VMs. The value must be 3 to place VMs in the adjacent blocks, or 2 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:

  1. Create VPC networks. Use these networks to provide connectivity between the VMs.
  2. 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
  • 2 gVNIC network interfaces used for host to host communication
  • 1 RDMA network interface (attached to a network with 8 subnets) for GPU to GPU communication
3
a3-ultragpu-8g 10
  • 2 gVNIC network interfaces used for host to host communication.
  • 1 RDMA network interface (attached to a network with 8 subnets) for GPU to GPU communication.
3
*For more information about NIC arrangement, see Review network bandwidth and NIC arrangement.
For more information about the network interfaces, see Using Google Virtual NIC and RDMA network profiles.

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:

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 is europe-west1-b, then your region is europe-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 by d, h, m, and s respectively. For example, specify 30m for 30 minutes or 1d2h3m4s 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:

  1. 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.

  2. 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.
  3. 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:

  1. 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, either STOP (default) or DELETE.

  2. 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.
  3. 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 the beta 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 between 600, which is 600 seconds (10 minutes), and 604800, which is 604,800 seconds (seven days).

Reservation-bound

To create a regional instance template, make a POST request to the regionInstanceTemplates.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:

  1. 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.

  2. 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.
  3. Submit the request.

Spot

To create a regional instance template, make a POST request to the regionInstanceTemplates.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:

  1. 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, either STOP (default) or DELETE.

  2. 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.
  3. Submit the request.

What's next?