Create a MIG for HPC workloads with reservation-bound consumption

This tutorial shows you how to create a managed instance group (MIG) that uses aH4D machine type.The MIG uses thereservation-bound provisioning modelto obtain compute resources.

Creating a MIG lets you manage multiple virtual machines (VMs) as a singleentity. Each VM in a MIG is based on an instance template. By automaticallymanaging the VMs in the group, MIGs offer high availability and scalability. Tolearn more about MIGs, seeManaged instance groups.

To learn about HPC VM and HPC cluster creation options, seeOverview of HPC cluster creation.

This tutorial is intended for HPC engineers, platform administrators andoperators, and for data and MPI specialists who are interested in creating agroup of interconnected HPC instances to run their workloads. Theresulting instances don't use an orchestrator for instance management or jobscheduling.

If you want to create a managed instance group but don't need to create adense deployment of instances,see insteadBasic scenarios for creating managed instance groups (MIGs).

Objectives

  • Reserve blocks of capacity for the VM instances.
  • Optional: Create Virtual Private Cloud (VPC) networks.
  • Optional: Create a workload policy.
  • Create an instance template.
  • Create a MIG using one of the following methods:
    • Create a MIG with a target size.
    • Create a MIG and a resize request.
  • Clean up the resources you created.

Costs

In this document, you use the following billable components of Google Cloud:

To generate a cost estimate based on your projected usage, use thepricing calculator.

New Google Cloud users might be eligible for afree trial.

When you finish the tasks that are described in this document, you can avoid continued billing by deleting the resources that you created. For more information, seeClean up.

Before you begin

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. Install the Google Cloud CLI.

  3. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  4. Toinitialize the gcloud CLI, run the following command:

    gcloudinit

  5. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.
    Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

    • Create a Google Cloud project:

      gcloud projects createPROJECT_ID

      ReplacePROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set projectPROJECT_ID

      ReplacePROJECT_ID with your Google Cloud project name.

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the required API:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

    gcloudservicesenablecompute.googleapis.com

  8. Install the Google Cloud CLI.

  9. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  10. Toinitialize the gcloud CLI, run the following command:

    gcloudinit

  11. Create or select a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.create permission.Learn how to grant roles.
    Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

    • Create a Google Cloud project:

      gcloud projects createPROJECT_ID

      ReplacePROJECT_ID with a name for the Google Cloud project you are creating.

    • Select the Google Cloud project that you created:

      gcloud config set projectPROJECT_ID

      ReplacePROJECT_ID with your Google Cloud project name.

  12. Verify that billing is enabled for your Google Cloud project.

  13. Enable the required API:

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

    gcloudservicesenablecompute.googleapis.com

  14. Grant roles to your user account. Run the following command once for each of the following IAM roles:roles/compute.instanceAdmin.v1,roles/compute.networkAdmin

    gcloudprojectsadd-iam-policy-bindingPROJECT_ID--member="user:USER_IDENTIFIER"--role=ROLE

    Replace the following:

    • PROJECT_ID: Your project ID.
    • USER_IDENTIFIER: The identifier for your user account. For example,myemail@example.com.
    • ROLE: The IAM role that you grant to your user account.

Reserve capacity

To use the commands in this tutorial, you must reserve the capacity for creatingthe instances in the MIG.

Create a future reservation for blocks of capacity

This action lets you reserve blocks of capacity for a defined duration, startingon a specific date and time that you choose. The reservation reservesblocks or sub-blocks ofcapacity in acluster,which allows for dense deployments of VM instances.

To create a future reservation for a dense deployment, the process is asfollows:

  1. Follow the process toreserve capacity by contacting your account teamin the AI Hypercomputer documentation. In your future reservationrequest, provide the information as documented, with the followingexceptions:

    • Machine type: Specify H4D machine typeh4d-highmem-192-lssd.
    • Zone: Specify one of the zones where H4D instances are available, asdocumented in theAvailable regions and zonestable. To display the available zones only for H4D, in theSelect a machine series list, selectH4D.
    • Maintenance scheduling type: For H4D instances, you can specifyeitherGROUPED orINDEPENDENT.
    • Reservation operational mode: For H4D instances, specify the valueHIGHLY_AVAILABLE_CAPACITY.

  2. Quota is automatically increased before capacity is delivered. No action isrequired from you.

  3. When you create the instance template, specify the reservation-boundprovisioning model. The VM instances in the MIG are provisioned from yourreserved capacity.

You're charged for the entire reservation period, whether or not you use thereserved resources for the entire period. For more information, seeReservation billing.

Create a future reservation in calendar mode

If you need to use the reserved capacity for less than 90 days, you can create afuture reservation in calendar mode using Dynamic Workload Scheduler. To get futurereservation resources, the process is as follows:

  1. Search for available capacity and reserve resourcesby using the Google Cloud console, gcloud CLI, orCompute Engine API.
  2. No quota is charged and no action is required from you.
  3. When you create the instance template, specify the reservation-boundprovisioning model. The VM instances in the MIG are provisioned from yourreserved capacity.

You're charged for the entire reservation period, whether or not you use thereserved resources for the entire period. For more information, seeDynamic Workload Scheduler pricing.

Optional: Create VPC networks

Unless you choose to disable it, each project has adefault network, which canbe used to provide network connectivity for your instances. When you create aVM, you can specify a VPC network and subnet. If you omit this configuration,the default network and subnet are used.

H4D instances can be configured to use Cloud RDMA. Cloud RDMAenables low-latency reliable messaging capabilities by using anIRDMA network driverthat supports Remote Direct Memory Access (RDMA) between Compute Engineinstances.

For this tutorial:

  • If you want to configure the H4D instances to use Cloud RDMA,complete the steps in this section.
  • If you don't want to use Cloud RDMA, then you can skip this sectionand use the default network instead.

To use Cloud RDMA with H4D instances, you must have at least twonetworks configured, one for each type of network interface (NIC):

  • NIC typeGVNIC: uses thegve driver for TCP/IP and Internet traffic for normal VM-VM and VM-Internet communication.
  • NIC typeIRDMA: uses IDPF/iRDMA drivers for Cloud RDMA networking between instances.

Instances that use Cloud RDMA can have only oneIRDMA interface. You can add up to eight additionalGVNIC network interfaces for a total of 10 vNICs per instance.

To set up theFalcon VPC networks to use with your instances, you can either follow the documented instructions or use the provided script.

Instruction guides

To create the networks, you can use the following instructions:

Script

You can create up to nine gVNIC network interfaces and oneIRDMA network interface per instance. Each network interface mustattach to a separate network. To create the networks, you can use the followingscript, which creates two networks for gVNIC and one network for IRDMA.

  1. Optional: Before running the script, list the Falcon VPC network profiles to verify there is one available.
      gcloud compute network-profiles list

  2. Copy the following code and run it in a Linux shell window.

      #!/bin/bash  # Set the number of GVNIC interfaces to create. You can create up to 9.  NUM_GVNIC=NUMBER_OF_GVNIC  # Create regular VPC networks and subnets for the GVNIC interfaces    for N in $(seq 0 $(($NUM_GVNIC - 1))); do      gcloud compute networks createGVNIC_NAME_PREFIX-net-$N \          --subnet-mode=custom      gcloud compute networks subnets createGVNIC_NAME_PREFIX-sub-$N \          --network=GVNIC_NAME_PREFIX-net-$N \          --region=REGION \          --range=10.$N.0.0/16      gcloud compute firewall-rules createGVNIC_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 createGVNIC_NAME_PREFIX-ssh \      --network=GVNIC_NAME_PREFIX-net-0 \      --action=ALLOW \      --rules=tcp:22 \      --source-ranges=IP_RANGE  # Optional: Create a firewall rule for the external IP address for the  #  first GVNIC network interface  gcloud compute firewall-rules createGVNIC_NAME_PREFIX-allow-ping-net-0 \      --network=GVNIC_NAME_PREFIX-net-0 \      --action=ALLOW \      --rules=icmp \      --source-ranges=IP_RANGE  # Create a Falcon VPC network for the Cloud RDMA network interface  gcloud compute networks createRDMA_NAME_PREFIX-irdma \      --network-profile=ZONE-vpc-falcon \      --subnet-mode custom  # Create a subnet in the Falcon VPC network  gcloud compute networks subnets createRDMA_NAME_PREFIX-irdma-sub \      --network=RDMA_NAME_PREFIX-irdma \      --region=REGION \      --range=10.2.0.0/16  # offset to avoid overlap with GVNIC subnet ranges

    Replace the following:

    • NUMBER_OF_GVNIC: the number of GVNIC interfaces to create. Specify a number from 1 to 9.
    • GVNIC_NAME_PREFIX: the name prefix to use for the regular VPC network and subnet that uses a GVNIC NIC type.
    • REGION: the region where you want to create the networks. This must correspond to the zone specified for the--network-profile flag, when creating the Falcon VPC network. For example, if you specify the zone aseurope-west4-b, then your region iseurope-west4.
    • IP_RANGE: the range of IP addresses outside of the VPC network to use for theSSH firewall rules. As a best practice, specify the specific IP address ranges that you need to allow access from, rather than all IPv4 or IPv6 sources. Don't use0.0.0.0/0 or::/0 as a source range because this allows traffic from all IPv4 or IPv6 sources, including sources outside of Google Cloud.
    • RDMA_NAME_PREFIX: the name prefix to use for the VPC network and subnet that uses the IRDMA NIC type.
    • ZONE: thezone where you want to create the networks and compute instances. Use eitherus-central1-a oreurope-west4-b.

  3. Optional: To verify that the VPC network resources are created successfully, check the network settings in the Google Cloud console:

    1. In the Google Cloud console, go to theVPC networks page.

      Go to VPC networks

    2. Search the list for the networks that you created in the previous step.
    3. To view the subnets, firewall rules, and other network settings, click the name of the network.

Optional: Create a workload policy

If you want Compute Engine to place VM instances in a single block or adjacent blocks,then specify instance placement by creating aworkload policy.However if you want Compute Engine to place your instances on a specific block, then skipthis step and provide the name of the block in the reservation affinity when you create the instancetemplate.

If you already have a workload policy, you can reuse it. When you apply a workload policy to yourMIG, Compute Engine makes best-effort attempts to create instances that are as close toeach other as possible. If your application is latency-sensitive and you want the instances to becloser together (maximum compactness), then specify themaxTopologyDistance field whencreating a workload policy.

You cannot update a workload policy after you create it. To make changes in aworkload policy, you must create a new one.

To create a workload policy, select one of the following options:

gcloud

To create a workload policy, use thegcloud compute resource-policies create workload-policy command.

  • For a best-effort placement of VMs, specify only the--type=high-throughput flag in the command:

    gcloud compute resource-policies create workload-policyWORKLOAD_POLICY_NAME \    --type=high-throughput \    --region=REGION

  • For strict colocation of VMs, specify the--max-topology-distance flag in thecommand:

    gcloud compute resource-policies create workload-policyWORKLOAD_POLICY_NAME \    --type=high-throughput \    --max-topology-distance=TOPOLOGY_DISTANCE \    --region=REGION

Replace the following:

  • WORKLOAD_POLICY_NAME: the name of the workload policy.
  • REGION: the region where you want to create the workload policy.Specify a region in which you want to create the MIG and the machine type that you want touse is available. For information about regions and zones, seeAvailable regions and zones.

REST

To create a workload policy, make aPOSTrequest to theresourcePolicies.insert method.

  • For a best-effort placement of VMs, specify only thetype field in the request as follows:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/resourcePolicies  {    "name": "WORKLOAD_POLICY_NAME"    "workloadPolicy": {      "type": "HIGH_THROUGHPUT"    }  }

  • For strict colocation of VMs, specify themaxTopologyDistance field in therequest as follows:

    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/resourcePolicies  {    "name": "WORKLOAD_POLICY_NAME"    "workloadPolicy": {      "type": "HIGH_THROUGHPUT",      "maxTopologyDistance": "TOPOLOGY_DISTANCE"    }  }

Replace the following:

  • PROJECT_ID: your project ID
  • REGION: the region where you want to create the workload policy. Specify a region in which you want to create the MIG and the machine type that you want to use is available. For information about regions and zones, seeAvailable regions and zones.
  • WORKLOAD_POLICY_NAME: the name of the workload policy.

Create an instance template

To specify the instance and consumption properties for each instance in the MIG,create an instance template by using one of the following methods:

gcloud

To create a regional instance template, use thegcloud compute instance-templates create command.

gcloud compute instance-templates createINSTANCE_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, \      stack-type=STACK_TYPE, \      address=EXTERNAL_IPV4_ADDRESS \--network-interface=nic-type=GVNIC, \      network=GVNIC_NAME_PREFIX-net-1, \      subnet=GVNIC_NAME_PREFIX-sub-1,no-address \--network-interface=nic-type=IRDMA, \      network=RDMA_NAME_PREFIX-irdma, \      subnet=RDMA_NAME_PREFIX-irdma-sub, \      stack-type=IPV4_ONLY,no-address \    --reservation-affinity=specific \    --reservation=RESERVATION \    --provisioning-model=RESERVATION_BOUND \    --instance-termination-action=DELETE \    --maintenance-policy=TERMINATE

Replace the following:

  • INSTANCE_TEMPLATE_NAME: the name of the instance template.
  • MACHINE_TYPE: the H4D machine type to use for the instance.
  • IMAGE_FAMILY: the image family of the OS image that you want to use.For a list of supported operating systems, seeSupported 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.
  • DISK_SIZE: the size of the boot disk in GiB.

  • GVNIC_NAME_PREFIX: the name prefix that you used when creating the standard VPC networks and subnets for the gVNIC interfaces.

    If you are using the default network, include only a single--network-interface field with thenic-type field set toGVNIC. Also, omit thenetwork andsubnetwork settings for this network interface.

  • STACK_TYPE: Optional: the stack type to use for the gVNIC interface. Specify eitherIPV4_ONLY orIPV4_IPV6. If you don't specify a value,IPV4_ONLY is used by default.

  • EXTERNAL_IPV4_ADDRESS: Optional: a static external IPv4 address to use with the gVNIC network interface. You must have previouslyreserved an external IPv4 address. Do one of the following:

    • Specify a valid IPv4 address from the subnet.
    • Use the flagno-address if you don't want the network interface to have an external IP address.
    • Specifyaddress='' if you want the network interface to receive an ephemeral external IP address.

    To specify an external IPv6 address for the GVNIC network interface, use the flag--external-ipv6-address instead.

  • RDMA_NAME_PREFIX: the name prefix that you used when creating the VPC network and subnet for the IRDMA network interface.

    If you are not using Cloud RDMA with your H4D instances, omit the--network-interface field for the IRDMA interface.

  • RESERVATION: the name of the reservation that you want to use.

    RESERVATION: either the reservation name or a specific block within a reservation. To get the reservation name or the available blocks, seeView reserved capacity. Based on your requirement for instance placement, choose one of the following:

    • To create instances across blocks or on a single block:

      projects/RESERVATION_OWNER_PROJECT_ID/reservations/RESERVATION_NAME

      Additionally, for a single block, create the MIG by applying a workload policy that specifies a block collocation (maxTopologyDistance=BLOCK) . Compute Engine then applies the policy to the reservation and creates instances on the same block.

    • To create instances on a specific block:

      projects/RESERVATION_OWNER_PROJECT_ID/reservations/RESERVATION_NAME/reservationBlocks/RESERVATION_BLOCK_NAME
    Tip: If the reservation exists in the current project, then you can omitprojects/RESERVATION_OWNER_PROJECT_ID/reservations/ from the reservation value.

REST

To create a regional instance template, make aPOST request to theregionInstanceTemplates.insert method.

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": [        {          "network": "GVNIC_NAME_PREFIX-net-0",          "subnetwork": "GVNIC_NAME_PREFIX-sub-0",          "accessConfigs": [            {                "type": "ONE_TO_ONE_NAT",                "name": "External IP",                "natIP": "EXTERNAL_IPV4_ADDRESS"            }          ],          "stackType": "IPV4_ONLY",          "nicType": "GVNIC",      },      {          "network": "GVNIC_NAME_PREFIX-net-1",          "subnetwork": "GVNIC_NAME_PREFIX-sub-1",          "stackType": "IPV4_ONLY",          "nicType": "GVNIC",      },      {          "network": "RDMA_NAME_PREFIX-irdma",          "subnetwork": "RDMA_NAME_PREFIX-irdma-sub",          "stackType": "IPV4_ONLY",          "nicType": "IRDMA",      }    ],,    "reservationAffinity":{        "consumeReservationType":"SPECIFIC_RESERVATION",        "key":"compute.googleapis.com/reservation-name",        "values":[          "RESERVATION"        ]      },    "scheduling":{        "provisioningModel":"RESERVATION_BOUND",        "instanceTerminationAction":"DELETE",        "onHostMaintenance": "TERMINATE",        "automaticRestart":true      }  }}

Replace the following:

  • INSTANCE_TEMPLATE_NAME: the name of the instance template.
  • MACHINE_TYPE: the machine type to use for the instance. Specify a H4D machine type. For more information, seeH4D machine types.
  • IMAGE_FAMILY: the image family of the OS image that you want to use. For a list of supported operating systems, seeSupported 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. For information about regions, seeRegions and zones.
  • DISK_SIZE: the size of the boot disk in GiB.

  • GVNIC_NAME_PREFIX: the name prefix that you used when creating the standard VPC networks and subnets for the gVNIC interfaces.

    If you are using the default network, include only a single--network-interface field with thenic-type field set toGVNIC. Also, omit thenetwork andsubnetwork settings for this network interface.

  • EXTERNAL_IPV4_ADDRESS: Optional: a static external IPv4 address to use with the gVNIC network interface. You must have previouslyreserved an external IPv4 address.

    To specify an external IPv6 address for the GVNIC network interface, use the flag--external-ipv6-address instead.

  • RDMA_NAME_PREFIX: the name prefix that you used when creating the VPC network and subnet for the IRDMA network interface.

    If you are not using Cloud RDMA with your H4D instances, omit the--network-interface field for the IRDMA interface.

  • RESERVATION: the name of the reservation that you want to use.

    RESERVATION: either the reservation name or a specific block within a reservation. To get the reservation name or the available blocks, seeView reserved capacity. Based on your requirement for instance placement, choose one of the following:

    • To create instances across blocks or on a single block:

      projects/RESERVATION_OWNER_PROJECT_ID/reservations/RESERVATION_NAME

      Additionally, for a single block, create the MIG by applying a workload policy that specifies a block collocation (maxTopologyDistance=BLOCK) . Compute Engine then applies the policy to the reservation and creates instances on the same block.

    • To create instances on a specific block:

      projects/RESERVATION_OWNER_PROJECT_ID/reservations/RESERVATION_NAME/reservationBlocks/RESERVATION_BLOCK_NAME
    Tip: If the reservation exists in the current project, then you can omitprojects/RESERVATION_OWNER_PROJECT_ID/reservations/ from the reservation value.

After you create the instance template, you canview the templateto see its ID and review its instance properties.

Create a MIG

Depending on your workload requirements, you can create a MIG ineither of the following configurations:

Create a MIG with a target size

If you can start your job without creating all of the VM instances at once, thencreate a MIG with a target size. The target size determines the number ofinstances in the MIG. The MIG starts creating instances based on currentresource availability. If any resource is temporarily unavailable, the MIGcontinuously attempts to create instances to meet the target size.

To create a MIG with a target size, select one of the following options:

gcloud

To create a MIG with a specified target size, use theinstance-groups managedcreate command.

In this step, the commands to create a MIG use a workload policy to specify VM placement. If youdon't want to use a workload policy, then remove the--workload-policy flag.

Create a zonal or regional MIG as follows:

  • To create a zonal MIG, use the following command:
    gcloud compute instance-groups managed createMIG_NAME \  --template=INSTANCE_TEMPLATE_URL \  --size=TARGET_SIZE \  --workload-policy=WORKLOAD_POLICY_URL \  --zone=ZONE
  • To create a regional MIG, use the following command:
    gcloud compute instance-groups managed createMIG_NAME \    --template=INSTANCE_TEMPLATE_URL \    --size=TARGET_SIZE \    --workload-policy=WORKLOAD_POLICY_URL \    --region=REGION
Replace the following:
  • MIG_NAME: the name of the MIG.
  • INSTANCE_TEMPLATE_URL: the URL of the instance template that you want touse to create VMs in the MIG. The URL can contain either theIDor name of the instance template. Specify one of the following values:
    • For a regional instance template:projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_ID
    • For a global instance template:INSTANCE_TEMPLATE_ID
  • TARGET_SIZE: the number of VMs that you want in the MIG.
  • WORKLOAD_POLICY_URL: Optional: the URL of the workload policy. If you don't want to use a workload policy, then you can remove the--workload-policy flag.
  • ZONE: the zone in which you want to create the MIG. If you use a workload policy, then specify a zone within the policy's region.
  • REGION: the region in which you want to create the MIG. If you use a workload policy, then specify the same region as that of the policy. For a regional MIG, instead of a region, you can specify the zones in that region by using the--zones flag.

REST

To create a MIG with a specified target size, make aPOST request as follows.

In this step, the requests to create a MIG use a workload policy to specify VM placement. If youdon't want to use a workload policy, then remove theresourcePolicies.workloadPolicyfield from the request body.

Create a zonal or regional MIG as follows:

  • To create a zonal MIG, make aPOST request to theinstanceGroupManagers.insert method.
    POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers{  "versions": [    {      "instanceTemplate": "INSTANCE_TEMPLATE_URL"    }  ],  "name": "MIG_NAME",  "instanceTemplate": "INSTANCE_TEMPLATE_URL",  "targetSize": "TARGET_SIZE",  "resourcePolicies": {    "workloadPolicy":WORKLOAD_POLICY_URL  }}
  • To create a regional MIG, make aPOST request to theregionInstanceGroupManagers.insert method.
      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers  {    "versions": [      {        "instanceTemplate": "INSTANCE_TEMPLATE_URL"      }    ],    "name": "MIG_NAME",    "instanceTemplate": "INSTANCE_TEMPLATE_URL",    "targetSize": "TARGET_SIZE",    "resourcePolicies": {      "workloadPolicy":WORKLOAD_POLICY_URL    }  }
Replace the following:
  • PROJECT_ID: the project ID.
  • ZONE: the zone in which you want to create the MIG. If you use a workload policy, then specify a zone within the policy's region.
  • REGION: the region in which you want to create a MIG. If you use a workload policy, then specify the same region as that of the policy.
  • INSTANCE_TEMPLATE_URL: the URL of the instance template that you want touse to create VMs in the MIG. The URL can contain either theIDor name of the instance template. Specify one of the following values:
    • For a regional instance template:projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_ID
    • For a global instance template:INSTANCE_TEMPLATE_ID
  • MIG_NAME: the name of the MIG.
  • TARGET_SIZE: the number of VMs that you want in the MIG.
  • WORKLOAD_POLICY_URL: Optional: the URL of the workload policy. If you don't want to use a workload policy, then you can remove theresourcePolicies.workloadPolicy field.

Create a MIG and a resize request

To create all the requested instances at the same time, create a MIG without anyinstances in it. After creating the empty MIG, you then create a resize requestin the MIG. When the resources are available to create all the instances atonce, the resize request adds the instances to the MIG.

To create a MIG and resize request, select one of the following options:

gcloud

In this step, the commands to create a MIG use a workload policy to specify VM placement. If youdon't want to use a workload policy, then remove the--workload-policy flag.

Create a zonal or regional MIG and a resize request as follows:

  • To create a zonal MIG and a resize request in it, do the following:

    1. Create a zonal MIG using theinstance-groups managed create commandas follows.

      gcloud compute instance-groups managed createMIG_NAME \    --template=INSTANCE_TEMPLATE_URL \    --size=0 \    --workload-policy=WORKLOAD_POLICY_URL \    --zone=ZONE

    2. Create a resize request in the zonal MIG using theinstance-groups managed resize-requests create commandas follows:

      gcloud compute instance-groups managed resize-requests createMIG_NAME \    --resize-request=RESIZE_REQUEST_NAME \POPULATION_METHOD \    --zone=ZONE

  • To create a regional MIG and a resize request in it, do the following:

    1. Create a regional MIG using theinstance-groups managed create commandas follows.

      gcloud compute instance-groups managed createMIG_NAME \    --template=INSTANCE_TEMPLATE_URL \    --size=0 \    --workload-policy=WORKLOAD_POLICY_URL \    --zones=ZONE \    --target-distribution-shape=any-single-zone \    --instance-redistribution-type=none

    2. Create a resize request in the regional MIG using thebetainstance-groups managed resize-requests create commandas follows:

      gcloud beta compute instance-groups managed resize-requests createMIG_NAME \    --resize-request=RESIZE_REQUEST_NAME \POPULATION_METHOD \    --region=REGION

Replace the following:

  • MIG_NAME: the name of the MIG.
  • INSTANCE_TEMPLATE_URL: the URL of the instance template that you want touse to create VMs in the MIG. The URL can contain either theIDor name of the instance template. Specify one of the following values:
    • For a regional instance template:projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_ID
    • For a global instance template:INSTANCE_TEMPLATE_ID
  • WORKLOAD_POLICY_URL: Optional: the URL of the workload policy. If you don't want to use a workload policy, then you can remove the--workload-policy flag.
  • ZONE: the zone in which you want to create the MIG. For a regional MIG also, you must specify a zone. This zone must be the zone that contains the profile for yourVPC network and must be azone where the machine type is available. For more information, seeLimitations.
  • RESIZE_REQUEST_NAME: the name of the resize request, which must be unique within the specified MIG. Otherwise, creating the resize request fails.

  • POPULATION_METHOD: the method of adding instances to the MIG. Use one of the following:

    • --resize-by=COUNT: add the specified number of instances to the MIG all at once. The instance names are automatically-generated.
    • --instances=INSTANCE_NAME_LIST: add instances with the specified names to the MIG all at once. ReplaceINSTANCE_NAME_LIST with a comma-separated list of instance names. The number of names you provide determines the number of instances to create with this resize request.
  • REGION: the region in which the MIG is located.

REST

In this step, the requests to create a MIG use a workload policy to specify VM placement. If youdon't want to use a workload policy, then remove theresourcePolicies.workloadPolicyfield from the request body.

Create a zonal or regional MIG and a resize request as follows:

  • To create a zonal MIG and a resize request in it, do the following:
    1. Create a zonal MIG by making aPOST request to theinstanceGroupManagers.insert method as follows.
      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers{  "versions": [    {      "instanceTemplate": "INSTANCE_TEMPLATE_URL"    }  ],  "name": "MIG_NAME",  "targetSize": 0,  "resourcePolicies": {    "workloadPolicy":WORKLOAD_POLICY_URL  }}
    2. Create a resize request in the zonal MIG by making aPOST request to theinstanceGroupManagerResizeRequests.insert method as follows:
      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/MIG_NAME/resizeRequests{  "name": "RESIZE_REQUEST_NAME",POPULATION_METHOD}
  • To create a regional MIG and a resize request in it, do the following:
    1. Create a regional MIG by making aPOST request to theregionInstanceGroupManagers.insert method as follows.
      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instanceGroupManagers{  "versions": [    {      "instanceTemplate": "INSTANCE_TEMPLATE_URL"    }  ],  "name": "MIG_NAME",  "targetSize": 0,  "distributionPolicy": {    "targetShape": "ANY_SINGLE_ZONE",    "zones": [      {        "zone": "projects/PROJECT_ID/zones/ZONE"      }    ]  },  "updatePolicy": {    "instanceRedistributionType": "NONE"  },  "resourcePolicies": {    "workloadPolicy":WORKLOAD_POLICY_URL  }}
    2. Create a resize request in the regional MIG by making aPOST request to thebeta.regionInstanceGroupManagerResizeRequests.insert method as follows:
      POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceGroupManagers/MIG_NAME/resizeRequests{  "name": "RESIZE_REQUEST_NAME",POPULATION_METHOD}

Replace the following:

  • PROJECT_ID: the project ID.
  • ZONE: the zone in which you want to create the MIG. For a regional MIG also, you must specify a zone. This zone must be the zone that contains the profile for yourVPC network and must be azone where the machine type is available. For more information, seeLimitations.
  • REGION: the region in which you want to create the MIG.
  • INSTANCE_TEMPLATE_URL: the URL of the instance template that you want touse to create VMs in the MIG. The URL can contain either theIDor name of the instance template. Specify one of the following values:
    • For a regional instance template:projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_ID
    • For a global instance template:INSTANCE_TEMPLATE_ID
  • MIG_NAME: the name of the MIG.
  • WORKLOAD_POLICY_URL: Optional: the URL of the workload policy. If you don't want to use a workload policy, then you can remove theresourcePolicies.workloadPolicy field.
  • RESIZE_REQUEST_NAME: the name of the resize request, which must be unique within the specified MIG. Otherwise, creating the resize request fails.

  • POPULATION_METHOD: the method of adding instances to the MIG. Use one of the following:

    • "resizeBy":COUNT: replaceCOUNT with the specified number of instances to add to the MIG all at once. The instance names are automatically-generated.
    • "instanceNames":INSTANCE_NAME_LIST: add instances with the specified names to the MIG all at once. ReplaceINSTANCE_NAME_LIST with a comma-separated list of instance names. The number of names you provide determines the number of instances to create with this resize request.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, either delete the project that contains the resources, or keep the project and delete the individual resources.

Delete your project

Caution: Deleting a project has the following effects:
  • Everything in the project is deleted. If you used an existing project for the tasks in this document, when you delete it, you also delete any other work you've done in the project.
  • Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as anappspot.com URL, delete selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple architectures, tutorials, or quickstarts, reusing projects can help you avoid exceeding project quota limits.

Delete a Google Cloud project:

gcloud projects deletePROJECT_ID

Delete the resources

  1. Delete resize requests in a MIG.

  2. Delete the MIG and instances.

  3. If the auto-delete state for the disks was set toFalse in the instancetemplate, then the disks are not automatically deleted when the VM instanceis deleted. You can delete the disks using one of the following methods:

    Console

    1. In the Google Cloud console, go to theDisks page.

    Go to Disks

    1. Select the rows that contain the disks that you created in thistutorial. Make sure theIn use by column is empty for each disk.

    2. ClickDelete, and thenclickDelete to confirm.

    gcloud

    Use thegcloud compute disks deletecommand.

    gcloud compute disks deleteDISK_NAME\    --projectPROJECT_ID --zoneZONE

    Replace the following:

    • DISK_NAME: the name of the disk to delete
    • PROJECT_ID: the ID of the project that containsthe disk
    • ZONE: the zone of the disk

    REST

    Use thedisks.delete methodto delete the disks.

    DELETE https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/disks/DISK_NAME

    Replace the following:

    • PROJECT_ID: the ID of the project that containsthe disk
    • ZONE: the zone of the disk
    • DISK_NAME: the name of the disk to delete

  4. Delete the networks.

  5. Delete the instance template.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-18 UTC.