Create VMs in bulk with instance flexibility

This document describes how to specify instance flexibility when you create virtual machines (VMs) in bulk. When you make this specification, you specify a list of machine types that are suitable for the VMs, and Compute Engine provisions VMs using any of the specified machine types based on capacity and quota availability in a region.

For more information about instance flexibility for VMs created in bulk, see About instance flexibility for VMs created in bulk.

Before you begin

For VMs and any related resources that you plan to create, make sure you have enough quota and the required permissions.
If you haven't already, set up authentication. Authentication verifies your identity for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:
Select the tab for how you plan to use the samples on this page:
gcloud
1. Install the Google Cloud CLI. After installation, initialize the Google Cloud CLI by running the following command:
  gcloud init
  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
  
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.
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.
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 VMs in bulk, 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 VMs in bulk. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to create VMs in bulk:

compute.instances.create on the project
To use a custom image to create the VM: compute.images.useReadOnly on the image
To use a snapshot to create the VM: compute.snapshots.useReadOnly on the snapshot
To use an instance template to create the VM: compute.instanceTemplates.useReadOnly on the instance template
To specify a subnet for your VM: compute.subnetworks.use on the project or on the chosen subnet
To specify a static IP address for the VM: compute.addresses.use on the project
To assign an external IP address to the VM when using a VPC network: compute.subnetworks.useExternalIp on the project or on the chosen subnet
To assign a legacy network to the VM: compute.networks.use on the project
To assign an external IP address to the VM when using a legacy network: compute.networks.useExternalIp on the project
To set VM instance metadata for the VM: compute.instances.setMetadata on the project
To set tags for the VM: compute.instances.setTags on the VM
To set labels for the VM: compute.instances.setLabels on the VM
To set a service account for the VM to use: compute.instances.setServiceAccount on the VM
To create a new disk for the VM: compute.disks.create on the project
To attach an existing disk in read-only or read-write mode: compute.disks.use on the disk
To attach an existing disk in read-only mode: compute.disks.useReadOnly on the disk

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

Create VMs with multiple machine types of equal preference

If your workload can operate on several different machine types, you can specify a list of all compatible machine types in a single instance selection. The following examples show how you can specify multiple machine types of equal preference.

gcloud

To create VMs in bulk with a single instance selection, use the gcloud compute instances bulk create command with the --instance-selection-machine-types flag.

gcloud compute instances bulk create \
    --name-pattern=test-bulk-# \
    --region=REGION \
    --count=COUNT \
    --instance-selection-machine-types=c3-standard-8,n2-standard-8,c2-standard-8

REST

In the Compute Engine API, make a POST request to the regionInstances.bulkInsert method. In the request body, include instanceFlexibilityPolicy with one instanceSelections entry that lists the machine types.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instances/bulkInsert
{
  "count": COUNT,
  "namePattern": "test-bulk-#",
  "instanceFlexibilityPolicy": {
    "instanceSelections": {
      "selection-1": {
        "machineTypes": [
          "c3-standard-8",
          "n2-standard-8",
          "c2-standard-8"
        ]
      }
    }
  }
}

Replace the following:

COUNT: the number of VMs to create.
PROJECT_ID: your project ID.
REGION: the region in which to create the VMs.

Create VMs with multiple machine types ranked by preference

If you want Compute Engine to choose machine types in a specific order, you can configure multiple instance selections. Each instance selection includes a list of machine types and a rank, which is an integer that defines the preference for the machine types. A lower rank indicates a higher preference. Compute Engine attempts to create VMs using machine types with a higher preference (lower rank). If those machine types aren't available, Compute Engine uses machine types with a lower preference (higher rank).

The following examples show how to specify multiple instance selections with ranks.

gcloud

To create VMs in bulk with multiple instance selections, use the gcloud compute instances bulk create command and specify the --instance-selection flag multiple times.

gcloud beta compute instances bulk create \
    --name-pattern=test-bulk-# \
    --region=REGION \
    --count=COUNT \
    --instance-selection "name=most-preferred,rank=0,machine-type=c3-standard-16,machine-type=n2-standard-16, machine-type=c2-standard-16" \
    --instance-selection "name=least-preferred,rank=1,machine-type=c3-standard-8,machine-type=n2-standard-8, machine-type=c2-standard-8"

REST

In the Compute Engine API, make a POST request to the regionInstances.bulkInsert method. In the request body, include instanceFlexibilityPolicy and specify multiple entries in instanceSelections, each with a list of machine types and a rank.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instances/bulkInsert
{
  "count": COUNT,
  "namePattern": "test-bulk-#",
  "instanceFlexibilityPolicy": {
    "instanceSelections": {
      "most-preferred": {
        "machineTypes": [
          "c3-standard-16",
          "c2-standard-16"
        ],
        "rank": 1
      },
      "least-preferred": {
        "machineTypes": [
          "n2-standard-16",
          "c3-standard-8",
          "n2-standard-8",
          "c2-standard-8"
        ],
        "rank": 2
      }
    }
  }
}

Replace the following:

COUNT: the number of VMs to create.
PROJECT_ID: your project ID.
REGION: the region in which to create the VMs.

Specify disk overrides in instance selections

By default, the VMs created by a bulk request use the disk configuration from instanceProperties. However, you can specify disk configurations within an instance selection. If you specify disks in an instance selection, that disk configuration overrides the disk configuration in instanceProperties for VMs that use that instance selection.

The following example shows how to specify disks in instance selections.

REST

In the Compute Engine API, make a POST request to the regionInstances.bulkInsert method. In the request body, include instanceFlexibilityPolicy and, for any instanceSelections entry, include the disks field to override instanceProperties.disks.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instances/bulkInsert
{
  "count": COUNT,
  "namePattern": "test-bulk-#",
  "instanceFlexibilityPolicy": {
    "instanceSelections": {
      "selection-1": {
        "machineTypes": [
          "n2-standard-8",
          "c2-standard-8"
        ],
        "disks": [
          {
            "type": "PERSISTENT",
            "initializeParams": {
              "diskType": "pd-ssd",
              "diskSizeGb": 50,
              "sourceImage": "IMAGE_URL"
            },
            "boot": true
          },
          {
            "type": "SCRATCH",
            "initializeParams": {
              "diskType": "local-ssd"
            }
          }
        ]
      },
      "selection-2": {
        "machineTypes": [
          "c3-standard-8"
        ],
        "disks": [
          {
            "type": "PERSISTENT",
            "initializeParams": {
              "diskType": "hyperdisk-balanced",
              "diskSizeGb": 50,
              "sourceImage": "IMAGE_URL"
            },
            "boot": true
          },
          {
            "type": "PERSISTENT",
            "initializeParams": {
              "diskType": "hyperdisk-balanced",
              "diskSizeGb": 128,
              "sourceImage": "IMAGE_URL"
            }
          }
        ]
      }
    }
  }
}

Replace the following:

COUNT: the number of VMs to create.
IMAGE_URL: URL of the boot disk image.
PROJECT_ID: your project ID.
REGION: the region in which to create the VMs.

Create VMs in bulk with instance flexibility Stay organized with collections Save and categorize content based on your preferences.

Before you begin

gcloud

REST

Required roles

Required permissions

Create VMs with multiple machine types of equal preference

gcloud

REST

Create VMs with multiple machine types ranked by preference

gcloud

REST

Specify disk overrides in instance selections

REST

Create VMs in bulk with instance flexibility