Create a managed instance group (MIG)

This document describes how to create a managed instance group (MIG) that is deployed on Hypercompute Cluster. For more information about Hypercompute Cluster, see Hypercompute Cluster.

A MIG is a group of virtual machine (VM) instances that you treat as a single entity. Each VM in a MIG is based on an instance template. For more information, 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

  • Select the tab for how you plan to use the samples on this page:

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    REST

    To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init

    For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Required roles

To get the permissions that you need to create a MIG, ask your administrator to grant you the Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.

This predefined role contains the permissions required to create a MIG. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to create a MIG:

  • To create a MIG: compute.instanceGroupManagers.create on the project

You might also be able to get these permissions with custom roles or other predefined roles.

Prerequisites

Before creating a MIG, complete the following steps if you haven't already:

  1. Create a reservation: to have the necessary resources for the VMs in your MIG, you first need to reserve blocks of resources.

    For instructions, see Request capacity.

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

    For instructions, see Create a compact placement policy.

  3. Create a regional instance template: to specify the VM configuration, including whether to create your VMs in a specific block within the reservation.

    For instructions, see Create a regional instance template.

Limitations

When creating a MIG, the following limitations apply:

  • You cannot configure instance flexibility in the MIG.

  • If you use resize request to create VMs in a MIG, the following limitations also apply:

    • In a regional MIG, you can use only the ANY_SINGLE_ZONE target distribution shape (Preview). Other distribution shapes aren't supported.

    • You must not set autoscaling.

    • You can only set the standby pool mode of the MIG to manual (default).

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

Create a MIG

After you complete the steps in the Prerequisites section, create a MIG based on your scenario as follows:

Scenario Method to create a MIG and VMs in it Example
You have a job that requires distribution across an exact number of VMs. Create a MIG without any VMs in it, and then create a resize request in the MIG. The resize request helps you to obtain multiple VMs all at once.

See Create a MIG and a resize request.

 Distributed ML training and fine-tuning jobs
You have multiple or parallel jobs that can start with any number of VMs. Create a MIG and use the target size to specify the number of VMs that you want in the group.

See Create a MIG with target size.

 ML inference jobs

Create a MIG and a resize request

If you require multiple VMs all at once to start a job, then create a MIG, and create a resize request in the MIG as described in this section. A resize request helps you to obtain the required VMs all at once.

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

gcloud

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

    1. Create a zonal MIG using the beta instance-groups managed create command as follows:

      gcloud beta compute instance-groups managed create MIG_NAME \
  --template=INSTANCE_TEMPLATE_URL \
  --size=0 \
  –-zone=ZONE

    2. Create a resize request in the zonal MIG using the beta instance-groups managed resize-requests create command as follows:

      gcloud beta compute instance-groups managed resize-requests create MIG_NAME \
  --resize-request=RESIZE_REQUEST_NAME \
  --resize-by=COUNT \
  --zone=ZONE

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

    1. Create a regional MIG using the beta instance-groups managed create command as follows:

      gcloud beta compute instance-groups managed create MIG_NAME \
    --template=INSTANCE_TEMPLATE_URL \
    --size=0 \
    --zones=ZONE \
    --target-distribution-shape=any-single-zone \
    --instance-redistribution-type=none \

    2. Create a resize request in the regional MIG using the beta instance-groups managed resize-requests create command as follows:

      gcloud beta compute instance-groups managed resize-requests create MIG_NAME \
    --resize-request=RESIZE_REQUEST_NAME \
    --resize-by=COUNT \
    --region=REGION

Replace the following:

  • MIG_NAME: the name of the MIG.

  • INSTANCE_TEMPLATE_URL: the URL of the instance template that you want to use to create VMs in the MIG. Specify one of the following values:

    • For a regional instance template: projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_NAME
    • For a global instance template: INSTANCE_TEMPLATE_NAME

  • ZONE: the zone in which you want to create the MIG. For a regional MIG also, you must specify a zone.

  • REGION: the region in which the MIG is located.

  • RESIZE_REQUEST_NAME: the name of the resize request, which must be unique within the specified MIG. Otherwise, creating the resize request fails.

  • COUNT: the number of VMs to add to the MIG all at once.

REST

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

    1. Create a zonal MIG by making a POST request to the beta.instanceGroupManagers.insert method as follows:

      POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers

{
  "versions": [
    {
      "instanceTemplate": "INSTANCE_TEMPLATE_URL"
    }
  ],
  "name": "MIG_NAME",
  "targetSize": 0
}

    2. Create a resize request in the zonal MIG by making a POST request to the beta.instanceGroupManagerResizeRequests.insert method as follows:

      POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/MIG_NAME/resizeRequests

{
  "name": "RESIZE_REQUEST_NAME",
  "resizeBy": COUNT
}

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

    1. Create a regional MIG by making a POST request to the beta.regionInstanceGroupManagers.insert method as follows:

      POST https://compute.googleapis.com/compute/beta/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"
  }
}

    2. Create a resize request in the regional MIG by making a POST request to the beta.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",
  "resizeBy": COUNT
}

Replace the following:

  • MIG_NAME: the name of the MIG.

  • INSTANCE_TEMPLATE_URL: the URL of the instance template that you want to use to create VMs in the MIG. Specify one of the following values:

    • For a regional instance template: projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_NAME
    • For a global instance template: INSTANCE_TEMPLATE_NAME

  • ZONE: the zone in which you want to create the MIG.

  • REGION: the region in which you want to create the MIG.

  • RESIZE_REQUEST_NAME: the name of the resize request, which must be unique within the specified MIG. Otherwise, creating the resize request fails.

  • COUNT: the number of VMs to add to the MIG all at once.

Create a MIG with target size

If you can start your job without having all VMs at once, then create a MIG with a target size. The target size determines the number of VMs in the MIG. The MIG starts creating VMs based on current resource availability. If any resource is temporarily unavailable, the MIG continuously attempts to create VMs 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 the beta instance-groups managed create command.

The following command creates a regional MIG. To create a zonal MIG, replace the --region flag with the --zone=ZONE flag.

gcloud beta compute instance-groups managed create MIG_NAME \
    --template=INSTANCE_TEMPLATE_URL \
    --size=TARGET_SIZE \
    –-region=REGION

Replace the following:

  • MIG_NAME: the name of the MIG.

  • INSTANCE_TEMPLATE_URL: the URL of the instance template that you want to use to create VMs in the MIG. Specify one of the following values:

    • For a regional instance template: projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_NAME
    • For a global instance template: INSTANCE_TEMPLATE_NAME

  • TARGET_SIZE: the number of VMs that you want in the MIG.

  • REGION: the region in which you want to create the MIG.

REST

To create a MIG with a specified target size, make a POST request to the following API methods:

The following request creates a regional MIG:

  POST https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/regions/REGION/instanceGroupManagers

  {
    "versions": [
      {
        "instanceTemplate": "INSTANCE_TEMPLATE_URL"
      }
    ],
    "name": "MIG_NAME",
    "instanceTemplate": "INSTANCE_TEMPLATE_URL",
    "targetSize": "TARGET_SIZE"
  }

Replace the following:

  • MIG_NAME: the name of the MIG.

  • INSTANCE_TEMPLATE_URL: the URL of the instance template that you want to use to create VMs in the MIG. Specify one of the following values:

    • For a regional instance template: projects/PROJECT_ID/regions/REGION/instanceTemplates/INSTANCE_TEMPLATE_NAME
    • For a global instance template: INSTANCE_TEMPLATE_NAME

  • TARGET_SIZE: the number of VMs that you want in the MIG.

  • REGION: the region in which you want to create the MIG.

What's next