BulkInsertInstanceResource

A transient resource used in compute.instances.bulkInsert and compute.regionInstances.bulkInsert . This resource is not persisted anywhere, it is used only for processing the requests.

JSON representation 
{
  "count": string,
  "minCount": string,
  "namePattern": string,
  "perInstanceProperties": {
    string: {
      object (PerInstanceProperties)
    },
    ...
  },
  "sourceInstanceTemplate": string,
  "instanceProperties": {
    object (InstanceProperties)
  },
  "locationPolicy": {
    object (LocationPolicy)
  },
  "instanceFlexibilityPolicy": {
    object (InstanceFlexibilityPolicy)
  }
}
Fields
count

string (int64 format)

The maximum number of instances to create.
minCount

string (int64 format)

The minimum number of instances to create. If no

minCount

is specified then

count

is used as the default value. If

minCount

instances cannot be created, then no instances will be created and instances already created will be deleted.
namePattern

string

The string pattern used for the names of the VMs. Either

namePattern

or

perInstanceProperties

must be set. The pattern must contain one continuous sequence of placeholder hash characters (#) with each character corresponding to one digit of the generated instance name. Example: a

namePattern

of

inst-####

generates instance names such as

inst-0001

and

inst-0002

. If existing instances in the same project and zone have names that match the name pattern then the generated instance numbers start after the biggest existing number. For example, if there exists an instance with name

inst-0050

, then instance names generated using the pattern

inst-####

begin with

inst-0051

. The name pattern placeholder

#...#

can contain up to 18 characters.
perInstanceProperties

map (key: string, value: object (PerInstanceProperties))

Per-instance properties to be set on individual instances. Keys of this map specify requested instance names. Can be empty if

namePattern

is used.
sourceInstanceTemplate

string

Specifies the instance template from which to create instances. You may combine

sourceInstanceTemplate

with

instanceProperties

to override specific values from an existing instance template. Bulk API follows the semantics of JSON Merge Patch described by RFC 7396.

It can be a full or partial URL. For example, the following are all valid URLs to an instance template:

This field is optional.
instanceProperties

object (InstanceProperties)

The instance properties defining the VM instances to be created. Required if

sourceInstanceTemplate

is not provided.
locationPolicy

object (LocationPolicy)

Policy for choosing target zone. For more information, see Create VMs in bulk.
instanceFlexibilityPolicy

object (InstanceFlexibilityPolicy)

A flexible specification of machine type of instances to create.

Available from 2026-03-01..

PerInstanceProperties

Per-instance properties to be set on individual instances. To be extended in the future.

JSON representation 
{
  "name": string,
  "hostname": string
}
Fields
name

string

Output only. This field is only temporary. It will be removed. Do not use it.
hostname

string

Specifies the hostname of the instance. More details in: https://documentation.s3ns.fr/compute/docs/instances/custom-hostname-vm#naming_convention

LocationPolicy

Configuration for location policy among multiple possible locations (e.g. preferences for zone selection among zones in a single region).

JSON representation 
{
  "locations": {
    string: {
      object (Location)
    },
    ...
  },
  "targetShape": enum (TargetShape),
  "zones": [
    {
      object (ZoneConfiguration)
    }
  ]
}
Fields
locations

map (key: string, value: object (Location))

Location configurations mapped by location name. Currently only zone names are supported and must be represented as valid internal URLs, such as

zones/us-central1-a

. The bulkInsert operation doesn't create instances in an AI zone, even if an AI zone is available in the specified region. For example, if you set a DENY preference for us-central1-a, Compute Engine will consider us-central1-b and us-central1-c for instance creation, but not us-central1-ai1a. Also, you can't use the locations[] configuration to allow instance creation in an AI zone. To include an AI zone in bulkInsert operations, use the locationPolicy.zones[] field.
targetShape

enum (TargetShape)

Strategy for distributing VMs across zones in a region.
zones[]

object (ZoneConfiguration)

The bulkInsert operation applies any preferences set in the locations field to the specific zones listed in the zones field if the same zones are specified in both fields.

Available from 2026-03-01..

Location

JSON representation 
{
  "preference": enum (Preference),
  "constraints": {
    object (Constraints)
  }
}
Fields
preference

enum (Preference)

Preference for a given location. Set to either

ALLOW

or

DENY

.
constraints

object (Constraints)

Constraints that the caller requires on the result distribution in this zone.

Preference

The Preference enumeration may be a subject of a future extension.

Enums
PREFERENCE_UNSPECIFIED Default value, unused.
DENY Location is prohibited.
ALLOW Location is allowed for use.

Constraints

Per-zone constraints on location policy for this zone.

JSON representation 
{
  "maxCount": integer
}
Fields
maxCount

integer

Maximum number of items that are allowed to be placed in this zone. The value must be non-negative.

TargetShape

Strategy for distributing VMs across zones in a region.

Enums
ANY GCE picks zones for creating VM instances to fulfill the requested number of VMs within present resource constraints and to maximize utilization of unused zonal reservations. Recommended for batch workloads that do not require high availability.
BALANCED GCE prioritizes acquisition of resources, scheduling VMs in zones where resources are available while distributing VMs as evenly as possible across allowed zones to minimize the impact of zonal failure. Recommended for highly available serving workloads.
ANY_SINGLE_ZONE GCE always selects a single zone for all the VMs, optimizing for resource quotas, available reservations and general capacity. Recommended for batch workloads that cannot tollerate distribution over multiple zones. This the default shape in Bulk Insert and Capacity Advisor APIs.

ZoneConfiguration

JSON representation 
{
  "zone": string
}
Fields
zone

string

The URL of the zone. The zone must exist in the region where the request is called. Zones must be represented as valid partial URLs, such as

zones/us-central1-a

.

Available from 2026-03-01..

InstanceFlexibilityPolicy

A flexible specification of machine types for instances to create.

JSON representation 
{
  "instanceSelections": {
    string: {
      object (InstanceSelection)
    },
    ...
  }
}
Fields
instanceSelections

map (key: string, value: object (InstanceSelection))

Specification of alternative, flexible instance subsets. One of them will be selected to create the instances based on various criteria, like: - ranks, - location policy, - current capacity, - available reservations (you can specify affinity in InstanceProperties), - SWAN/GOOSE limitations. Key is an arbitrary, unique RFC1035 string that identifies the instance selection.

Available from 2026-03-01..

InstanceSelection

Specification of machine type to use. Every position inside this message is an alternative. The count specified in the shape flexibility must not exceed the number of entries in perInstanceProperties or the capacity of the namePattern, if used.

JSON representation 
{
  "machineTypes": [
    string
  ],
  "rank": string,
  "disks": [
    {
      object (AttachedDisk)
    }
  ]
}
Fields
machineTypes[]

string

Alternative machine types to use for instances that are created from these properties. This field only accepts a machine type names, for example n2-standard-4 and not URLs or partial URLs.

Available from 2026-03-01..
rank

string (int64 format)

Rank when prioritizing the shape flexibilities. The instance selections with rank are considered first, in the ascending order of the rank. If not set, defaults to 0.

Available from 2026-03-01..
disks[]

object (AttachedDisk)

Disks to be attached to the instances created from in this selection. They override the disks specified in the instance properties.

Available from 2026-03-01..