Create VMs in bulk

Linux Windows

When you want to create a large number of virtual machine (VM) instances thatare identical and independent from each other, create VMs in bulk using theGoogle Cloud CLI or the Compute Engine API. You can create these VMs across allzones in a region ordistributed across certain zones.

For more details and associated limitations, seeAbout bulk creation ofVMs.If you want to create instances with attached GPUs, seeCreate GPU VMs in bulk instead.

Before you begin

Required roles

To get the permissions that you need to create VMs in bulk, ask your administrator to grant you theCompute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on the project. For more information about granting roles, seeManage 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 theRequired 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 alegacy 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 withcustom roles or otherpredefined roles.

Create VMs in bulk in a region

To create VMs in bulk in a region, use the gcloud CLI or theCompute Engine API.

If you specify a machine type or support for additional hardware such as a GPUor a local SSD, Compute Engine places the VMs in a zone within theregion that supports the machine type and the additional hardware.

gcloud

To create VMs in bulk in a region, use the followinggcloud computeinstances bulk createcommand:

gcloud compute instances bulk create \    ( --name-pattern="NAME_PATTERN" | --predefined-names=[PREDEFINED_NAMES] ) \    --region=REGION \    --count=COUNT \    [ --min-count=MIN_COUNT \ ]    [--location-policy=LOCATION_POLICY \ ]    [--target-distribution-shape=TARGET_DISTRIBUTION_SHAPE ]

Replace the following:

  • NAME_PATTERN: the name pattern for the VMs. Use asequence of hash (#) characters for Compute Engine to replacewith a sequence of numbers. For example, usingvm-# for the name patterngenerates VMs with names such asvm-1 andvm-2, up to the number ofVMs specified by--count, which must be less than or equal to the numberof VMs that the name pattern allows.

    When using a name pattern, Compute Engine tries to avoid nameconflicts by checking the names of existing VMs created from previousrequests.

  • PREDEFINED_NAMES: a list of predefined names forthe VMs to create. If using this flag and specifyingCOUNT,COUNT mustequal the number of names provided.

  • REGION: the region to create the VMs in.

  • COUNT: the number of VMs to create. This must beless than or equal to the number of VMs allowed byNAME_PATTERN. Or, ifusing--predefined-names, you don't have to specifyCOUNT, but if youdo, it must be equal to the number of names provided.

  • MIN_COUNT: the minimum number of VMs to create. Thefollowing table describes the behavior of the request depending on how youset this flag:

    ValueDescription
    Not setDefault value isCOUNT. If Compute Enginecan't create the number of VMs specified byCOUNT, therequest fails and no VMs are created.
    1Compute Engine creates as many VMs as possible,up toCOUNT.
    Greater than1 andless thanCOUNTCompute Engine creates at leastMIN_COUNT VMsup to a maximum ofCOUNT VMs. IfMIN_COUNT VMs can'tbe created, the request fails and no VMs are created.

  • LOCATION_POLICY: the zones to include or excludewithin a region. Use a list of key-value pairs, with the zone as the keyand the policy as the value. Valid values for the policy areallow,which is the default, anddeny. The following is an example value forthis flag:

    --location-policy=us-east1-b=allow,us-east1-c=deny

  • TARGET_DISTRIBUTION_SHAPE: the distribution of the VMs acrossthe specified zones. Use the--location-policy flag to specify thezones. The following table shows the valid values for this flag:

    ValueDescription
    ANY_SINGLE_ZONEEnforces VM placement in a single zone, and prioritizes utilizationof unused reservations. Use this to avoid cross-zone network egressor to reduce network latency. This is the default value.
    BALANCEDAttempts to distribute VMs evenly across all zones in the region.
    ANYAllows distribution of VMs across multiple zones in a region.Chooses zones that have available resources and that maximize unusedzonal reservations.

REST

To create VMs in bulk in a region, use the followinginstances.bulkInsertmethod:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instances/bulkInsert{  ...  "namePattern": "NAME_PATTERN",  "perInstanceProperties": {    "PREDEFINED_NAME_1": {},    "PREDEFINED_NAME_2": {},    ...  },  "count":COUNT,  "minCount":MIN_COUNT,  "locationPolicy": {    "LOCATION_POLICY"    },    "targetShape": "TARGET_DISTRIBUTION_SHAPE"  ...}

Replace the following:

  • PROJECT_ID: the project ID.

  • REGION: the region to create the VMs in.

  • NAME_PATTERN: the name pattern for the VMs. Specifyeither this orperInstanceProperties. Use a sequence of hash (#)characters for Compute Engine to replace with a sequence ofnumbers. For example, usingvm-# for the name pattern generates VMs withnames such asvm-1 andvm-2, up to the number of VMs specified by--count, which must be less than or equal to the number of VMs that thename pattern allows.

    When using a name pattern, Compute Engine tries to avoid nameconflicts by checking the names of existing VMs created from previousrequests.

  • PREDEFINED_NAME_1,PREDEFINED_NAME_2, ...: a list of predefined namesfor the VMs to create. Specify either this ornamePattern. If using thisflag and specifyingCOUNT,COUNT must equal the number of namesprovided.

  • COUNT: the number of VMs to create. This must beless than or equal to the number of VMs allowed byNAME_PATTERN. Or, ifusingperInstanceProperties, you don't have to specifyCOUNT, but ifyou do, it must be equal to the number of names provided.

  • MIN_COUNT: the minimum number of VMs to create. Thefollowing table describes the behavior of the request depending on how youset this flag:

    ValueDescription
    Not setDefault value isCOUNT. If Compute Enginecan't create the number of VMs specified byCOUNT, therequest fails and no VMs are created.
    1Compute Engine creates as many VMs as possible,up toCOUNT.
    Greater than1 andless thanCOUNTCompute Engine creates at leastMIN_COUNT VMsup to a maximum ofCOUNT VMs. IfMIN_COUNT VMs can'tbe created, the request fails and no VMs are created.

  • LOCATION_POLICY: the zones to include or excludewithin a region. Use a list of key-value pairs, with the zone as the keyand the policy as the value. Valid values for the policy areALLOW,which is the default, andDENY. The following is an example value forthis field:

    "locations": {  "zones/us-central1-a": { "preference": "ALLOW" },  "zones/us-central1-c": { "preference": "DENY"  },  ...},

  • TARGET_DISTRIBUTION_SHAPE: the distribution of VMs across thespecified zones. Use thelocationPolicy field to specify the zones. Thefollowing table shows the valid values for this field:

    ValueDescription
    ANY_SINGLE_ZONEEnforces VM placement in a single zone, and prioritizes utilizationof unused reservations. Use this to avoid cross-zone network egressor to reduce network latency. This is the default value.
    BALANCEDAttempts to distribute VMs evenly across all zones in the region.
    ANYAllows distribution of VMs across multiple zones in a region.Chooses zones that have available resources and that maximize unusedzonal reservations.

Create VMs in bulk in a zone

To create VMs in bulk in a zone, use the gcloud CLI or theCompute Engine API.

gcloud

To create VMs in bulk in a specific zone, use the followinggcloud computeinstances bulk createcommand.

gcloud compute instances bulk create \    ( --name-pattern="NAME_PATTERN" | --predefined-names=[PREDEFINED_NAMES] ) \    --zone=ZONE \    --count=COUNT \    [ --min-count=MIN_COUNT ]

Replace the following:

  • NAME_PATTERN: the name pattern for the VMs. Use asequence of hash (#) characters for Compute Engine to replacewith a sequence of numbers. For example, usingvm-# for the name patterngenerates VMs with names such asvm-1 andvm-2, up to the number ofVMs specified by--count, which must be less than or equal to the numberof VMs that the name pattern allows.

    When using a name pattern, Compute Engine tries to avoid nameconflicts by checking the names of existing VMs created from previousrequests.

  • PREDEFINED_NAMES: a list of predefined names forthe VMs to create. If using this flag and specifyingCOUNT,COUNT mustequal the number of names provided.

  • ZONE: the zone to create the VMs in.

  • COUNT: the number of VMs to create. This must beless than or equal to the number of VMs allowed byNAME_PATTERN. Or, ifusing--predefined-names, you don't have to specifyCOUNT, but if youdo, it must be equal to the number of names provided.

  • MIN_COUNT: the minimum number of VMs to create. Thefollowing table describes the behavior of the request depending on how youset this flag:

    ValueDescription
    Not setDefault value isCOUNT. If Compute Enginecan't create the number of VMs specified byCOUNT, therequest fails and no VMs are created.
    1Compute Engine creates as many VMs as possible,up toCOUNT.
    Greater than1 andless thanCOUNTCompute Engine creates at leastMIN_COUNT VMsup to a maximum ofCOUNT VMs. IfMIN_COUNT VMs can'tbe created, the request fails and no VMs are created.

REST

To create VMs in bulk in a zone, use the followinginstances.bulkInsertmethod.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/bulkInsert{  ...  "namePattern": "NAME_PATTERN",  "perInstanceProperties": {    "PREDEFINED_NAME_1": {},    "PREDEFINED_NAME_2": {},    ...  },  "count":COUNT,  "minCount":MIN_COUNT,  ...}

Replace the following:

  • PROJECT_ID: the project ID.

  • ZONE: the zone to create the VMs in.

  • NAME_PATTERN: the name pattern for the VMs. Specifyeither this orperInstanceProperties. Use a sequence of hash (#)characters for Compute Engine to replace with a sequence ofnumbers. For example, usingvm-# for the name pattern generates VMs withnames such asvm-1 andvm-2, up to the number of VMs specified by--count, which must be less than or equal to the number of VMs that thename pattern allows.

    When using a name pattern, Compute Engine tries to avoid nameconflicts by checking the names of existing VMs created from previousrequests.

  • PREDEFINED_NAME_1,PREDEFINED_NAME_2, ...: a list of predefined namesfor the VMs to create. Specify either this ornamePattern. If using thisflag and specifyingCOUNT,COUNT must equal the number of namesprovided.

  • COUNT: the number of VMs to create. This must beless than or equal to the number of VMs allowed byNAME_PATTERN. Or, ifusingperInstanceProperties, you don't have to specifyCOUNT, but ifyou do, it must be equal to the number of names provided.

  • MIN_COUNT: the minimum number of VMs to create. Thefollowing table describes the behavior of the request depending on how youset this flag:

    ValueDescription
    Not setDefault value isCOUNT. If Compute Enginecan't create the number of VMs specified byCOUNT, therequest fails and no VMs are created.
    1Compute Engine creates as many VMs as possible,up toCOUNT.
    Greater than1 andless thanCOUNTCompute Engine creates at leastMIN_COUNT VMsup to a maximum ofCOUNT VMs. IfMIN_COUNT VMs can'tbe created, the request fails and no VMs are created.

Create VMs with custom hostnames in bulk

You can create VMs with custom hostnames in bulk in a region or in a zone byusing the gcloud CLI or the Compute Engine API.

You must manually configure the DNS record for your custom hostname. For moreinformation, seelimitations.

If you don't specify a hostname, Compute Engine sets the hostname forVMs as one of the following:

  • VM_NAME.c.PROJECT_ID.internalwhen you enable global DNS
  • VM_NAME.ZONE.c.PROJECT_ID.internalwhen you enable zonal DNS

For more information,seeinternal DNS names.

gcloud

To create VMs in bulk with custom hostnames in a specific region, use thefollowinggcloud beta compute instances bulk create command.

gcloud beta compute instances bulk create \    ( --name-pattern="NAME_PATTERN" | --predefined-names=[PREDEFINED_NAMES] ) \    --per-instance-hostnames=[VM_NAME=HOSTNAME,...] \    --zone=REGION \    --count=COUNT \    [ --min-count=MIN_COUNT ]    [--location-policy=LOCATION_POLICY \ ]    [--target-distribution-shape=TARGET_DISTRIBUTION_SHAPE ]

Replace the following:

  • NAME_PATTERN: the name pattern for the VMs. Use asequence of hash (#) characters for Compute Engine to replacewith a sequence of numbers. For example, usingvm-# for the name patterngenerates VMs with names such asvm-1 andvm-2, up to the number ofVMs specified by--count, which must be less than or equal to the numberof VMs that the name pattern allows.

    When using a name pattern, Compute Engine tries to avoid nameconflicts by checking the names of existing VMs created from previousrequests.

  • PREDEFINED_NAMES: a list of predefined names forthe VMs to create. If using this flag and specifyingCOUNT,COUNT mustequal the number of names provided.

  • [VM_NAME=HOSTNAME, ...]: alist of key-value pairs of predefined names for the VMs and fully qualifieddomain hostnames that you want to assign for the VMs. Custom hostnames mustconform toRFC 1035 requirements for valid hostnames.

  • REGION: the zone to create the VMs in.

  • COUNT: the number of VMs to create. This must beless than or equal to the number of VMs allowed byNAME_PATTERN. Or, ifusing--predefined-names, you don't have to specifyCOUNT, but if youdo, it must be equal to the number of names provided.

  • MIN_COUNT: the minimum number of VMs to create. Thefollowing table describes the behavior of the request depending on how youset this flag:

    ValueDescription
    Not setDefault value isCOUNT. If Compute Enginecan't create the number of VMs specified byCOUNT, therequest fails and no VMs are created.
    1Compute Engine creates as many VMs as possible,up toCOUNT.
    Greater than1 andless thanCOUNTCompute Engine creates at leastMIN_COUNT VMsup to a maximum ofCOUNT VMs. IfMIN_COUNT VMs can'tbe created, the request fails and no VMs are created.

  • LOCATION_POLICY: the zones to include or excludewithin a region. Use a list of key-value pairs, with the zone as the keyand the policy as the value. Valid values for the policy areALLOW,which is the default, andDENY. The following is an example value forthis field:

    "locations": {  "zones/us-central1-a": { "preference": "ALLOW" },  "zones/us-central1-c": { "preference": "DENY"  },  ...},

  • TARGET_DISTRIBUTION_SHAPE: the distribution of VMs across thespecified zones. Use thelocationPolicy field to specify the zones. Thefollowing table shows the valid values for this field:

    ValueDescription
    ANY_SINGLE_ZONEEnforces VM placement in a single zone, and prioritizes utilizationof unused reservations. Use this to avoid cross-zone network egressor to reduce network latency. This is the default value.
    BALANCEDAttempts to distribute VMs evenly across all zones in the region.
    ANYAllows distribution of VMs across multiple zones in a region.Chooses zones that have available resources and that maximize unusedzonal reservations.

REST

To create VMs with custom hostnames in bulk in a specific region, use the followinginstances.bulkInsert method:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/instances/bulkInsert{  ...  "namePattern": "NAME_PATTERN",  "perInstanceProperties": {    "PREDEFINED_NAME_1": {"hostname":HOSTNAME_1},    "PREDEFINED_NAME_2": {"hostname":HOSTNAME_2},    ...  },  "count":COUNT,  "minCount":MIN_COUNT,  "locationPolicy": {    "LOCATION_POLICY"    },    "targetShape": "TARGET_DISTRIBUTION_SHAPE"  ...}

Replace the following:

  • PROJECT_ID: the project ID.

  • REGION: the region to create the VMs in.

  • NAME_PATTERN: the name pattern for the VMs. Specifyeither this orperInstanceProperties. Use a sequence of hash (#)characters for Compute Engine to replace with a sequence ofnumbers. For example, usingvm-# for the name pattern generates VMs withnames such asvm-1 andvm-2, up to the number of VMs specified by--count, which must be less than or equal to the number of VMs that thename pattern allows.

    When using a name pattern, Compute Engine tries to avoid nameconflicts by checking the names of existing VMs created from previousrequests.

  • PREDEFINED_NAME_1,PREDEFINED_NAME_2, ...: a list of predefined namesfor the VMs to create. Specify either this ornamePattern. If using thisflag and specifyingCOUNT,COUNT must equal the number of namesprovided.

  • HOSTNAME_1,HOSTNAME_2, ...: fully qualified domainhostnames that you want to assign for the VMs. Custom hostnames mustconform toRFC 1035 requirements for valid hostnames.

    For example, to create two VMsvm-1 andvm-2 with customhostnamesmy-host1234.example.com andtest.example.com respectively,specify thehostname property inperInstanceProperties as follows:

    {..."perInstanceProperties": {"vm-1": { "hostname": "my-host1234.example.com" },"vm-2": { "hostname": "test.example.com" },...}},

  • COUNT: the number of VMs to create. This must beless than or equal to the number of VMs allowed byNAME_PATTERN. Or, ifusingperInstanceProperties, you don't have to specifyCOUNT, but ifyou do, it must be equal to the number of names provided.

  • MIN_COUNT: the minimum number of VMs to create. Thefollowing table describes the behavior of the request depending on how youset this flag:

    ValueDescription
    Not setDefault value isCOUNT. If Compute Enginecan't create the number of VMs specified byCOUNT, therequest fails and no VMs are created.
    1Compute Engine creates as many VMs as possible,up toCOUNT.
    Greater than1 andless thanCOUNTCompute Engine creates at leastMIN_COUNT VMsup to a maximum ofCOUNT VMs. IfMIN_COUNT VMs can'tbe created, the request fails and no VMs are created.

  • LOCATION_POLICY: the zones to include or excludewithin a region. Use a list of key-value pairs, with the zone as the keyand the policy as the value. Valid values for the policy areALLOW,which is the default, andDENY. The following is an example value forthis field:

    "locations": {  "zones/us-central1-a": { "preference": "ALLOW" },  "zones/us-central1-c": { "preference": "DENY"  },  ...},

  • TARGET_DISTRIBUTION_SHAPE: the distribution of VMs across thespecified zones. Use thelocationPolicy field to specify the zones. Thefollowing table shows the valid values for this field:

    ValueDescription
    ANY_SINGLE_ZONEEnforces VM placement in a single zone, and prioritizes utilizationof unused reservations. Use this to avoid cross-zone network egressor to reduce network latency. This is the default value.
    BALANCEDAttempts to distribute VMs evenly across all zones in the region.
    ANYAllows distribution of VMs across multiple zones in a region.Chooses zones that have available resources and that maximize unusedzonal reservations.

Check the status of a request to create VMs in bulk

When you create a mutation request, Compute Engine returns anoperationresource that you can poll to get the status of the operation. For moreinformation, seeHandling API responses.

To get the status of a bulk insert request,send an HTTPGET requestto theoperation resource:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/operations/OPERATION_ID

To get the status of a regional bulk insert request, send the following request:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/regions/REGION/operations/OPERATION_ID

Replace the following:

  • PROJECT_ID: the ID of the project in which you'recreating VMs
  • REGION: the region in which you are creating VMs
  • ZONE: the zone in which you are creating VMs
  • OPERATION_ID: the bulk insert operation ID

TheinstancesBulkInsertOperationMetadata object in the response contains detailsabout the operation on a per-zone basis in theperLocationStatus field.For each zone included in the bulk creation request,perLocationStatuscontains the following fields:

  • status: The status is one of the following:
    • CREATING: VM creation is in progress in the zone.
    • ROLLING_BACK: The request failed in the zone and it's being rolled back.
    • DONE: VM creation or rollback has completed successfully in the zone.
  • targetVmCount: The number of VMs that Compute Engine attempts to create in the zone.Compute Engine determines this count after initial checks, and itdoesn't change during the operation. When you check the operation status, thisfield is always present for each zone.
  • createdVmCount: The number of VMs already created in the zone. This valuedoes not exceedtargetVmCount for a given zone.
    • failedToCreateVmCount: The number of VMs that failed to create in the zone.
    • deletedVmCount: The number of VMs that were deleted in the zone as part ofrolling back of a failed operation.

Theprogress field in the response represents the percentage of completion ofthe operation.

The status of the bulk insert operation isRUNNING untilCompute Engine successfully creates at least the minimum number ofVMs and no more VM creation or rollback of the request happens.

When the bulk insert operation is in progress, you should see a responsesimilar to the following:

{  "kind" : "compute#operation",  "id": "4653028658507445766",  "name": "operation-1587661030638-5a3f823c143e3-e33bbfa3-bd72185c",  "operationType": "bulkInsert",  "targetLink":  "https://www.googleapis.com/compute/v1/projects/my-project"  "targetId": 4653028658507445766,  "status": "RUNNING",  "progress": 2,  "user": "example@google.com",  "insertTime": "2023-04-23T09:57:13.474-07:00",  "startTime": "2023-04-23T09:57:13.474-07:00",  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/operations/operation-1587661030638-5a3f823c143e3-e33bbfa3-bd72185c",  "operationGroupId": "4653028658507445766",  "metadata":    "instances_bulk_insert_operation_metadata": {      "per_location_status": {         "zones/us-central1-a": {           "status": "CREATING",           "targetVmCount": 50,           "createdVmCount": 1         }      }    }}

In this example, one instance has been successfully created and the operationis 2% completed.

The operation returns the statusDONE when Compute Enginesuccessfully creates at least the minimum number of VMs specified byminCount,or when Compute Engine completes the rollback of the request.After successful creation of the requested number of VMs, you get a responsesimilar to the following:

{  "endTime": "2023-04-23T09:58:13.474-07:00",  "id": "5053101474378293244",  "insertTime": "2023-04-23T09:57:13.474-07:00",  "instancesBulkInsertOperationMetadata": {    "perLocationStatus": {      "zones/us-central1-a": {        "status": "DONE",        "createdVmCount": 50,        "targetVmCount": 50      }    }  },  "kind": "compute#operation",  "name": "operation-1587661030638-5a3f823c143e3-e33bbfa3-bd72185c",  "operationGroupId": "4653028658507445766",  "operationType": "bulkInsert",  "progress": 100,  "selfLink": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/operations/operation-1587661030638-5a3f823c143e3-e33bbfa3-bd72185c",  "startTime": "2023-09-11T16:21:55.629-07:00",  "status": "DONE",  "targetId": "625521788110",  "targetLink": "https://www.googleapis.com/compute/v1/projects/my-project",  "user": "example@google.com",  "zone": "https://www.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a"}

For more information, see the documentation for theinstancesBulkInsertOperationMetadata object.

Check the status of a single VM

To check the status of a single VM created from a request to create VMs in bulk,use the gcloud CLI or the Compute Engine API.

gcloud

  1. From theOperation returned by the request, get the value of theoperationGroupId property.

  2. Use theoperationGroupId property as a filter with thegcloud computeoperations list commandto search across all operations and all zones in the project for VMsassociated with the regional or zonal request:

    gcloud compute operations list \   --filter=(operationGroupId=OPERATION_GROUP_ID)

  3. Get the rest of the VM's properties by doing any of the following:

    • From the list of operations, thetargetLink represents the path ofthe VM. Use thegcloud compute instances describecommand with thispath as the name of the VM to get the VM's properties:

      gcloud compute instances describeVM_NAME

    • Use thegcloud compute instances listcommand with a filterthat includes the names of the VMs from the list of operations:

      gcloud compute instances listVM_NAME \   --filter=(name=VM_NAME_1) OR (name=VM_NAME_2)

    • Use thegcloud compute instances listcommand to get theproperties of VMs from across all zones and regions, and filter byeither a label that is unique to the instances or by their names:

      gcloud compute instances list \   --filter=(name=VM_NAME_1) OR (name=VM_NAME_2)

REST

  1. From theOperation returned by the request, get the value of theoperationGroupId property.

  2. Use theoperationGroupId property to get the list of VMoperations associated with the regional or zonal request:

    • If you sent a regional request, then, to search acrossall operations and all zones in the project, use theglobalOperations.aggregatedListmethodand includeoperationGroupId property as a filter:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/aggregated/operations?filter=(operationGroupId=OPERATION_GROUP_ID)

    • If you sent a zonal request, then, to list the operations in thatzone, use thezoneOperations.get methodand include theoperationGroupId property in the body of the request:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/zones/ZONE/instances/bulkInsert{..."operationGroupId":"OPERATION_GROUP_ID"...}

  3. Get the rest of the VM's properties by doing any of the following:

    • From the list of operations, thetargetLink represents the path of theVM. Use theinstances.getmethod with this pathas the name of the VM to get all of the VM's properties:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/zones/ZONE/instances/VM_NAME

    • Use theinstances.getmethod with a filterthat includes the names of the VMs from the list of operations:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/zones/ZONE/instances?filter=(name=VM_NAME_1) OR (name=VM_NAME_2)

    • Use theinstances.aggregatedListmethodto get the properties of VMs from across all zones and regions, andfilter by either a label that is unique to the instances or by theirnames:

      GET https://compute.googleapis.com/compute/v1/projects/PROJECT_NAME/aggregated/instances?filter=(name=VM_NAME_1) OR (name=VM_NAME_2)

Pseudocode examples

The following pseudocode examples show how to customize requests for creatingVMs in bulk.

Create VMs in bulk in one region from a set of regions

The following pseudocode describes how to create 1,000 VMs in one region from aset of regions. When attempting to create VMs in bulk in one region from a setof regions, the request first checks for capacity. If there is not enoughcapacity, the request fails immediately and tries again with the next region inthe set.

  1. Specify the number of VMs to create within a zone.

    nTarget = 1000

  2. Designate the regions to attempt to create the VMs in.

    acceptableRegions = ["us-central1", "us-east1", "us-west1"]

  3. Iterate through the regions, and attempt to create the VMs in each regionuntil successful.

    for region in acceptableRegions:  call bulk API: region=region, location-policy=location-policy, count=nTarget  if request succeeds and the operation succeeds:    break

Create VMs of a specific machine type in bulk in a zone

The following pseudocode describes how to create multiple VMs of aspecified machine type in a zone. When attempting to create VMs in bulk of the samemachine type, the request first checks for availability of those machine types.If there is not enough of the machine type available, the request failsimmediately and tries again with the next machine type.

  1. Specify the number of VMs to create and the region to create them in.

    nTarget = 1000region = "us-central1"

  2. Specify the machine families to attempt to create the VMs of.

    acceptableMachineFamilies = ["n2","c2","e2","n1"]

  3. Iterate through the set of machine types and attempt to create the VMs ofthe machine type until successful.

    for family in acceptableMachineFamilies:  call bulk APIs: region=region, count=nTarget, machineFamily=family  if request succeeds and the operation succeeds:    break

Create more than 5,000 VMs in a zone

When creating VMs in bulk,you can only create 5,000 VMs with eachrequest.The following pseudocode describes how to create more than 5,000 VMs in a zone byissuing multiple requests.

  1. Specify the number of VMs to create, a counter to keep track of the totalnumber of created VMs, the region to create the VMs in, and a variable tostore the zone that Compute Engine creates the VMs in.

    nTarget = 10000nCreated = 0region = "us-central1"targetZone = ""

  2. Issue an initial request to create 5,000 VMs, save the zone returned by therequest, and update the counter of the number of VMs created.

    call bulk API: region=region, count=5000targetZone = zone chosen by bulk APInCreated += # of VMs created

  3. Continue issuing requests to create up to 5,000 VMs at a time in the zoneuntil Compute Engine creates the specified number of VMs.

    while(nTarget - nCreated > 0):  call bulk API: zone=targetZone, count=5000  nCreated += # of VMs created

Create VMs in bulk and view their status

The following procedure shows you how to create a group of VMs that havepredefined names and then view their status:

  1. Specify the number of VMs to create, the zone to create them in, and adata structure to store the names in.

    nTarget = 1000targetZone = "us-central-1a"names = []

  2. Generate the patterned names for the VMs and add the names to the datastructure.

    for n in range(0, 1000):  names.push("instance-%d".format(n))

  3. Create the VMs, and useperInstanceProperties to specify the names.

    call bulk API(zone=targetZone, count=nTarget, names=perInstanceProperties)

  4. Get the details of the VMs by using theinstances.listmethod with a filter forthe names of VMs to return the details about.

    instances.list(filter=(name = "instance-1") OR (name = "instance-2") ...)

What's next

After creating VMs in bulk, do either or both of the following to simplifymanagement of those VMs:

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 2025-12-15 UTC.