Contact UsGet started
© 2024 Iron Hive LLC Belgrade

Compute Cloud Instance Groups API, REST: InstanceGroup methods

Written by
Improved by
Updated at September 19, 2024

A set of methods for managing InstanceGroup resources.

JSON Representation

{
  "id": "string",
  "folderId": "string",
  "createdAt": "string",
  "name": "string",
  "description": "string",
  "labels": "object",
  "instanceTemplate": {
    "description": "string",
    "labels": "object",
    "platformId": "string",
    "resourcesSpec": {
      "memory": "string",
      "cores": "string",
      "coreFraction": "string",
      "gpus": "string"
    },
    "metadata": "object",
    "bootDiskSpec": {
      "mode": "string",
      "deviceName": "string",
      "diskSpec": {
        "description": "string",
        "typeId": "string",
        "size": "string",
        "preserveAfterInstanceDelete": true,

        // `instanceTemplate.bootDiskSpec.diskSpec` includes only one of the fields `imageId`, `snapshotId`
        "imageId": "string",
        "snapshotId": "string",
        // end of the list of possible fields`instanceTemplate.bootDiskSpec.diskSpec`

      },
      "diskId": "string",
      "name": "string"
    },
    "secondaryDiskSpecs": [
      {
        "mode": "string",
        "deviceName": "string",
        "diskSpec": {
          "description": "string",
          "typeId": "string",
          "size": "string",
          "preserveAfterInstanceDelete": true,

          // `instanceTemplate.secondaryDiskSpecs[].diskSpec` includes only one of the fields `imageId`, `snapshotId`
          "imageId": "string",
          "snapshotId": "string",
          // end of the list of possible fields`instanceTemplate.secondaryDiskSpecs[].diskSpec`

        },
        "diskId": "string",
        "name": "string"
      }
    ],
    "networkInterfaceSpecs": [
      {
        "networkId": "string",
        "subnetIds": [
          "string"
        ],
        "primaryV4AddressSpec": {
          "oneToOneNatSpec": {
            "ipVersion": "string",
            "address": "string",
            "dnsRecordSpecs": [
              {
                "fqdn": "string",
                "dnsZoneId": "string",
                "ttl": "string",
                "ptr": true
              }
            ]
          },
          "dnsRecordSpecs": [
            {
              "fqdn": "string",
              "dnsZoneId": "string",
              "ttl": "string",
              "ptr": true
            }
          ],
          "address": "string"
        },
        "primaryV6AddressSpec": {
          "oneToOneNatSpec": {
            "ipVersion": "string",
            "address": "string",
            "dnsRecordSpecs": [
              {
                "fqdn": "string",
                "dnsZoneId": "string",
                "ttl": "string",
                "ptr": true
              }
            ]
          },
          "dnsRecordSpecs": [
            {
              "fqdn": "string",
              "dnsZoneId": "string",
              "ttl": "string",
              "ptr": true
            }
          ],
          "address": "string"
        },
        "securityGroupIds": [
          "string"
        ]
      }
    ],
    "schedulingPolicy": {
      "preemptible": true
    },
    "serviceAccountId": "string",
    "networkSettings": {
      "type": "string"
    },
    "name": "string",
    "hostname": "string",
    "placementPolicy": {
      "placementGroupId": "string",
      "hostAffinityRules": [
        {
          "key": "string",
          "op": "string",
          "values": [
            "string"
          ]
        }
      ]
    },
    "filesystemSpecs": [
      {
        "mode": "string",
        "deviceName": "string",
        "filesystemId": "string"
      }
    ],
    "metadataOptions": {
      "gceHttpEndpoint": "string",
      "awsV1HttpEndpoint": "string",
      "gceHttpToken": "string",
      "awsV1HttpToken": "string"
    }
  },
  "scalePolicy": {
    "testAutoScale": {
      "minZoneSize": "string",
      "maxSize": "string",
      "measurementDuration": "string",
      "warmupDuration": "string",
      "stabilizationDuration": "string",
      "initialSize": "string",
      "cpuUtilizationRule": {
        "utilizationTarget": "number"
      },
      "customRules": [
        {
          "ruleType": "string",
          "metricType": "string",
          "metricName": "string",
          "labels": "object",
          "target": "number",
          "folderId": "string",
          "service": "string"
        }
      ],
      "autoScaleType": "string"
    },

    // `scalePolicy` includes only one of the fields `fixedScale`, `autoScale`
    "fixedScale": {
      "size": "string"
    },
    "autoScale": {
      "minZoneSize": "string",
      "maxSize": "string",
      "measurementDuration": "string",
      "warmupDuration": "string",
      "stabilizationDuration": "string",
      "initialSize": "string",
      "cpuUtilizationRule": {
        "utilizationTarget": "number"
      },
      "customRules": [
        {
          "ruleType": "string",
          "metricType": "string",
          "metricName": "string",
          "labels": "object",
          "target": "number",
          "folderId": "string",
          "service": "string"
        }
      ],
      "autoScaleType": "string"
    },
    // end of the list of possible fields`scalePolicy`

  },
  "deployPolicy": {
    "maxUnavailable": "string",
    "maxDeleting": "string",
    "maxCreating": "string",
    "maxExpansion": "string",
    "startupDuration": "string",
    "strategy": "string",
    "minimalAction": "string"
  },
  "allocationPolicy": {
    "zones": [
      {
        "zoneId": "string",
        "instanceTagsPool": [
          "string"
        ]
      }
    ]
  },
  "loadBalancerState": {
    "targetGroupId": "string",
    "statusMessage": "string"
  },
  "managedInstancesState": {
    "targetSize": "string",
    "runningActualCount": "string",
    "runningOutdatedCount": "string",
    "processingCount": "string"
  },
  "loadBalancerSpec": {
    "targetGroupSpec": {
      "name": "string",
      "description": "string",
      "labels": "object"
    },
    "maxOpeningTrafficDuration": "string",
    "ignoreHealthChecks": true
  },
  "healthChecksSpec": {
    "healthCheckSpecs": [
      {
        "interval": "string",
        "timeout": "string",
        "unhealthyThreshold": "string",
        "healthyThreshold": "string",

        // `healthChecksSpec.healthCheckSpecs[]` includes only one of the fields `tcpOptions`, `httpOptions`
        "tcpOptions": {
          "port": "string"
        },
        "httpOptions": {
          "port": "string",
          "path": "string"
        },
        // end of the list of possible fields`healthChecksSpec.healthCheckSpecs[]`

      }
    ],
    "maxCheckingHealthDuration": "string"
  },
  "serviceAccountId": "string",
  "status": "string",
  "variables": [
    {
      "key": "string",
      "value": "string"
    }
  ],
  "deletionProtection": true,
  "applicationLoadBalancerSpec": {
    "targetGroupSpec": {
      "name": "string",
      "description": "string",
      "labels": "object"
    },
    "maxOpeningTrafficDuration": "string",
    "ignoreHealthChecks": true
  },
  "applicationLoadBalancerState": {
    "targetGroupId": "string",
    "statusMessage": "string"
  },
  "autoHealingPolicy": {
    "autoHealingAction": "string"
  }
}
Field Description
id string

ID of the instance group.
folderId string

ID of the folder that the instance group belongs to.
createdAt string (date-time)

Creation timestamp in RFC3339 text format.

String in RFC3339 text format. The range of possible values is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z, i.e. from 0 to 9 digits for fractions of a second.

To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
name string

Name of the instance group. The name is unique within the folder.
description string

Description of the instance group.
labels object

Resource labels as key:value pairs.
instanceTemplate object

Instance template for creating the instance group. For more information, see Instance Templates.
instanceTemplate.
description		 string

Description of the instance template.

The maximum string length in characters is 256.
instanceTemplate.
labels		 object

Resource labels as key:value pairs.

No more than 64 per resource. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\@0-9a-z]*. The maximum string length in characters for each value is 128.
instanceTemplate.
platformId		 string

Required. ID of the hardware platform configuration for the instance. Platforms allows you to create various types of instances: with a large amount of memory, with a large number of cores, with a burstable performance. For more information, see Platforms.
instanceTemplate.
resourcesSpec		 object

Required. Computing resources of the instance such as the amount of memory and number of cores.
instanceTemplate.
resourcesSpec.
memory		 string (int64)

The amount of memory available to the instance, specified in bytes.

The maximum value is 824633720832.
instanceTemplate.
resourcesSpec.
cores		 string (int64)

The number of cores available to the instance.

Value must be one of 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32, 34, 36, 40, 44, 48, 52, 56, 60, 64, 68, 72, 76 or 80.
instanceTemplate.
resourcesSpec.
coreFraction		 string (int64)

Baseline level of CPU performance with the ability to burst performance above that baseline level. This field sets baseline performance for each core.

Value must be one of 0, 5, 20, 50 or 100.
instanceTemplate.
resourcesSpec.
gpus		 string (int64)

The number of GPUs available to the instance.

Value must be one of 0, 1, 2 or 4.
instanceTemplate.
metadata		 object

The metadata key:value pairs assigned to this instance template. This includes custom metadata and predefined keys.

Metadata values may contain one of the supported placeholders: {instance_group.id} {instance.short_id} {instance.index} {instance.index_in_zone} {instance.zone_id} InstanceGroup and Instance labels may be copied to metadata following way: {instance_group.labels.some_label_key} {instance.labels.another_label_key} These placeholders will be substituted for each created instance anywhere in the value text. In the rare case the value requires to contain this placeholder explicitly, it must be escaped with double brackets, in example {instance.index}.

For example, you may use the metadata in order to provide your public SSH key to the instance. For more information, see Metadata.

No more than 128 per resource. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_0-9a-z]*. The maximum string length in characters for each value is 262144.
instanceTemplate.
bootDiskSpec		 object

Required. Boot disk specification that will be attached to the instance.
instanceTemplate.
bootDiskSpec.
mode		 string

Required. Access mode to the Disk resource.

  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
instanceTemplate.
bootDiskSpec.
deviceName		 string

Serial number that is reflected in the /dev/disk/by-id/ tree of a Linux operating system running within the instance.

This value can be used to reference the device for mounting, resizing, and so on, from within the instance.

Value must match the regular expression |[a-z][-_0-9a-z]{0,19}.
instanceTemplate.
bootDiskSpec.
diskSpec		 object

Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
instanceTemplate.
bootDiskSpec.
diskSpec.
description		 string

Description of the disk.

The maximum string length in characters is 256.
instanceTemplate.
bootDiskSpec.
diskSpec.
typeId		 string

Required. ID of the disk type.
instanceTemplate.
bootDiskSpec.
diskSpec.
size		 string (int64)

Size of the disk, specified in bytes.

Acceptable values are 4194304 to 28587302322176, inclusive.
instanceTemplate.
bootDiskSpec.
diskSpec.
preserveAfterInstanceDelete		 boolean (boolean)

When set to true, disk will not be deleted even after managed instance is deleted. It will be a user's responsibility to delete such disks.
instanceTemplate.
bootDiskSpec.
diskSpec.
imageId		 string
instanceTemplate.bootDiskSpec.diskSpec includes only one of the fields imageId, snapshotId

ID of the image that will be used for disk creation.

The maximum string length in characters is 50.
instanceTemplate.
bootDiskSpec.
diskSpec.
snapshotId		 string
instanceTemplate.bootDiskSpec.diskSpec includes only one of the fields imageId, snapshotId

ID of the snapshot that will be used for disk creation.

The maximum string length in characters is 50.
instanceTemplate.
bootDiskSpec.
diskId		 string

Set to use an existing disk. To set use variables.

The maximum string length in characters is 128. Value must match the regular expression [-a-zA-Z0-9._{}]*.
instanceTemplate.
bootDiskSpec.
name		 string

When set can be later used to change DiskSpec of actual disk.

The maximum string length in characters is 128.
instanceTemplate.
secondaryDiskSpecs[]		 object

Array of secondary disks that will be attached to the instance.

The maximum number of elements is 3.
instanceTemplate.
secondaryDiskSpecs[].
mode		 string

Required. Access mode to the Disk resource.

  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
instanceTemplate.
secondaryDiskSpecs[].
deviceName		 string

Serial number that is reflected in the /dev/disk/by-id/ tree of a Linux operating system running within the instance.

This value can be used to reference the device for mounting, resizing, and so on, from within the instance.

Value must match the regular expression |[a-z][-_0-9a-z]{0,19}.
instanceTemplate.
secondaryDiskSpecs[].
diskSpec		 object

Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
instanceTemplate.
secondaryDiskSpecs[].
diskSpec.
description		 string

Description of the disk.

The maximum string length in characters is 256.
instanceTemplate.
secondaryDiskSpecs[].
diskSpec.
typeId		 string

Required. ID of the disk type.
instanceTemplate.
secondaryDiskSpecs[].
diskSpec.
size		 string (int64)

Size of the disk, specified in bytes.

Acceptable values are 4194304 to 28587302322176, inclusive.
instanceTemplate.
secondaryDiskSpecs[].
diskSpec.
preserveAfterInstanceDelete		 boolean (boolean)

When set to true, disk will not be deleted even after managed instance is deleted. It will be a user's responsibility to delete such disks.
instanceTemplate.
secondaryDiskSpecs[].
diskSpec.
imageId		 string
instanceTemplate.secondaryDiskSpecs[].diskSpec includes only one of the fields imageId, snapshotId

ID of the image that will be used for disk creation.

The maximum string length in characters is 50.
instanceTemplate.
secondaryDiskSpecs[].
diskSpec.
snapshotId		 string
instanceTemplate.secondaryDiskSpecs[].diskSpec includes only one of the fields imageId, snapshotId

ID of the snapshot that will be used for disk creation.

The maximum string length in characters is 50.
instanceTemplate.
secondaryDiskSpecs[].
diskId		 string

Set to use an existing disk. To set use variables.

The maximum string length in characters is 128. Value must match the regular expression [-a-zA-Z0-9._{}]*.
instanceTemplate.
secondaryDiskSpecs[].
name		 string

When set can be later used to change DiskSpec of actual disk.

The maximum string length in characters is 128.
instanceTemplate.
networkInterfaceSpecs[]		 object

Required. Array of network interfaces that will be attached to the instance.
instanceTemplate.
networkInterfaceSpecs[].
networkId		 string

ID of the network.
instanceTemplate.
networkInterfaceSpecs[].
subnetIds[]		 string

IDs of the subnets.
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec		 object

Primary IPv4 address that is assigned to the instance for this network interface.
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
oneToOneNatSpec		 object

An external IP address configuration. If not specified, then this managed instance will have no external internet access.
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
oneToOneNatSpec.
ipVersion		 string

IP version for the public IP address.

  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
oneToOneNatSpec.
address		 string

Manual set static public IP. To set use variables. (optional)
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
oneToOneNatSpec.
dnsRecordSpecs[]		 object

External DNS configuration
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
oneToOneNatSpec.
dnsRecordSpecs[].
fqdn		 string

Required. FQDN (required)
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
oneToOneNatSpec.
dnsRecordSpecs[].
dnsZoneId		 string

DNS zone id (optional, if not set, private zone used)
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
oneToOneNatSpec.
dnsRecordSpecs[].
ttl		 string (int64)

DNS record ttl, values in 0-86400 (optional)

Acceptable values are 0 to 86400, inclusive.
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
oneToOneNatSpec.
dnsRecordSpecs[].
ptr		 boolean (boolean)

When set to true, also create PTR DNS record (optional)
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
dnsRecordSpecs[]		 object

Internal DNS configuration
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
dnsRecordSpecs[].
fqdn		 string

Required. FQDN (required)
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
dnsRecordSpecs[].
dnsZoneId		 string

DNS zone id (optional, if not set, private zone used)
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
dnsRecordSpecs[].
ttl		 string (int64)

DNS record ttl, values in 0-86400 (optional)

Acceptable values are 0 to 86400, inclusive.
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
dnsRecordSpecs[].
ptr		 boolean (boolean)

When set to true, also create PTR DNS record (optional)
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
address		 string

Optional. Manual set static internal IP. To set use variables.
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec		 object

Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
oneToOneNatSpec		 object

An external IP address configuration. If not specified, then this managed instance will have no external internet access.
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
oneToOneNatSpec.
ipVersion		 string

IP version for the public IP address.

  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
oneToOneNatSpec.
address		 string

Manual set static public IP. To set use variables. (optional)
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
oneToOneNatSpec.
dnsRecordSpecs[]		 object

External DNS configuration
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
oneToOneNatSpec.
dnsRecordSpecs[].
fqdn		 string

Required. FQDN (required)
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
oneToOneNatSpec.
dnsRecordSpecs[].
dnsZoneId		 string

DNS zone id (optional, if not set, private zone used)
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
oneToOneNatSpec.
dnsRecordSpecs[].
ttl		 string (int64)

DNS record ttl, values in 0-86400 (optional)

Acceptable values are 0 to 86400, inclusive.
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
oneToOneNatSpec.
dnsRecordSpecs[].
ptr		 boolean (boolean)

When set to true, also create PTR DNS record (optional)
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
dnsRecordSpecs[]		 object

Internal DNS configuration
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
dnsRecordSpecs[].
fqdn		 string

Required. FQDN (required)
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
dnsRecordSpecs[].
dnsZoneId		 string

DNS zone id (optional, if not set, private zone used)
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
dnsRecordSpecs[].
ttl		 string (int64)

DNS record ttl, values in 0-86400 (optional)

Acceptable values are 0 to 86400, inclusive.
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
dnsRecordSpecs[].
ptr		 boolean (boolean)

When set to true, also create PTR DNS record (optional)
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
address		 string

Optional. Manual set static internal IP. To set use variables.
instanceTemplate.
networkInterfaceSpecs[].
securityGroupIds[]		 string

IDs of security groups.
instanceTemplate.
schedulingPolicy		 object

Scheduling policy for the instance.
instanceTemplate.
schedulingPolicy.
preemptible		 boolean (boolean)

Preemptible instances are stopped at least once every 24 hours, and can be stopped at any time if their resources are needed by Compute. For more information, see Preemptible Virtual Machines.
instanceTemplate.
serviceAccountId		 string

Service account ID for the instance.
instanceTemplate.
networkSettings		 object

Network settings for the instance.
instanceTemplate.
networkSettings.
type		 string

Type of instance network.
instanceTemplate.
name		 string

Name of the instance. In order to be unique it must contain at least on of instance unique placeholders: {instance.short_id} {instance.index} combination of {instance.zone_id} and {instance.index_in_zone} Example: my-instance-{instance.index} If not set, default is used: {instance_group.id}-{instance.short_id} It may also contain another placeholders, see metadata doc for full list.

The maximum string length in characters is 128.
instanceTemplate.
hostname		 string

Host name for the instance. This field is used to generate the Instance.fqdn value. The host name must be unique within the network and region. If not specified, the host name will be equal to Instance.id of the instance and FQDN will be <id>.auto.internal. Otherwise FQDN will be <hostname>.<region_id>.internal.

In order to be unique it must contain at least on of instance unique placeholders: {instance.short_id} {instance.index} combination of {instance.zone_id} and {instance.index_in_zone} Example: my-instance-{instance.index} If not set, name value will be used It may also contain another placeholders, see metadata doc for full list.

The maximum string length in characters is 128.
instanceTemplate.
placementPolicy		 object

Placement Group
instanceTemplate.
placementPolicy.
placementGroupId		 string

Identifier of placement group
instanceTemplate.
placementPolicy.
hostAffinityRules[]		 object

List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.
instanceTemplate.
placementPolicy.
hostAffinityRules[].
key		 string

Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'
instanceTemplate.
placementPolicy.
hostAffinityRules[].
op		 string

Include or exclude action
instanceTemplate.
placementPolicy.
hostAffinityRules[].
values[]		 string

Affinity value or host ID or host group ID
instanceTemplate.
filesystemSpecs[]		 object

Array of filesystems to attach to the instance.

The filesystems must reside in the same availability zone as the instance.

To use the instance with an attached filesystem, the latter must be mounted. For details, see documentation.
instanceTemplate.
filesystemSpecs[].
mode		 string

Mode of access to the filesystem that should be attached.

  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.
instanceTemplate.
filesystemSpecs[].
deviceName		 string

Name of the device representing the filesystem on the instance.

The name should be used for referencing the filesystem from within the instance when it's being mounted, resized etc.

If not specified, a random value will be generated.

Value must match the regular expression |[a-z][-_0-9a-z]{0,19}.
instanceTemplate.
filesystemSpecs[].
filesystemId		 string

ID of the filesystem that should be attached.

The maximum string length in characters is 128. Value must match the regular expression [-a-zA-Z0-9._{}]*.
instanceTemplate.
metadataOptions		 object

Metadata options for the instance
instanceTemplate.
metadataOptions.
gceHttpEndpoint		 string

Enabled access to GCE flavored metadata

  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
instanceTemplate.
metadataOptions.
awsV1HttpEndpoint		 string

Enabled access to AWS flavored metadata (IMDSv1)

  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
instanceTemplate.
metadataOptions.
gceHttpToken		 string

Enabled access to IAM credentials with GCE flavored metadata

  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
instanceTemplate.
metadataOptions.
awsV1HttpToken		 string

Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)

  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
scalePolicy object

Scaling policy of the instance group.
scalePolicy.
testAutoScale		 object
Test spec for automatic scaling policy of the instance group.
scalePolicy.
testAutoScale.
minZoneSize		 string (int64)

Lower limit for instance count in each zone.

Acceptable values are 0 to 100, inclusive.
scalePolicy.
testAutoScale.
maxSize		 string (int64)

Upper limit for total instance count (across all zones). 0 means maximum limit = 100.

Acceptable values are 0 to 100, inclusive.
scalePolicy.
testAutoScale.
measurementDuration		 string

Time in seconds allotted for averaging metrics. 1 minute by default.

Acceptable values are 60 seconds to 600 seconds, inclusive.
scalePolicy.
testAutoScale.
warmupDuration		 string

The warmup time of the instance in seconds. During this time, traffic is sent to the instance, but instance metrics are not collected.

The maximum value is 600 seconds.
scalePolicy.
testAutoScale.
stabilizationDuration		 string

Minimum amount of time in seconds allotted for monitoring before Instance Groups can reduce the number of instances in the group. During this time, the group size doesn't decrease, even if the new metric values indicate that it should.

Acceptable values are 60 seconds to 1800 seconds, inclusive.
scalePolicy.
testAutoScale.
initialSize		 string (int64)

Target group size.

The minimum value is 1.
scalePolicy.
testAutoScale.
cpuUtilizationRule		 object

Defines an autoscaling rule based on the average CPU utilization of the instance group.

If more than one rule is specified, e.g. CPU utilization and one or more Monitoring metrics (customRules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
scalePolicy.
testAutoScale.
cpuUtilizationRule.
utilizationTarget		 number (double)

Target CPU utilization level. Instance Groups maintains this level for each availability zone.

Acceptable values are 10 to 100, inclusive.
scalePolicy.
testAutoScale.
customRules[]		 object

Defines an autoscaling rule based on a custom metric from Monitoring.

If more than one rule is specified, e.g. CPU utilization (cpuUtilizationRule) and one or more Monitoring metrics, the size of the instance group will be equal to the maximum of sizes calculated according to each metric.

The maximum number of elements is 3.
scalePolicy.
testAutoScale.
customRules[].
ruleType		 string

Required. Custom metric rule type. This field affects which label from the custom metric should be used: zone_id or instance_id.

  • UTILIZATION: This type means that the metric applies to one instance. First, Instance Groups calculates the average metric value for each instance, then averages the values for instances in one availability zone or in whole group depends on autoscaling type. This type of metric must have the instance_id label.
  • WORKLOAD: This type means that the metric applies to instances in one availability zone or to whole group depends on autoscaling type. This type of metric must have the zone_id label if ZONAL autoscaling type is chosen.
scalePolicy.
testAutoScale.
customRules[].
metricType		 string

Required. Type of custom metric. This field affects how Instance Groups calculates the average metric value.

  • GAUGE: This type is used for metrics that show the metric value at a certain point in time, such as requests per second to the server on an instance.

    Instance Groups calculates the average metric value for the period specified in the measurementDuration field.

  • COUNTER: This type is used for metrics that monotonically increase over time, such as the total number of requests to the server on an instance.

    Instance Groups calculates the average value increase for the period specified in the measurementDuration field.
scalePolicy.
testAutoScale.
customRules[].
metricName		 string

Required. Name of custom metric in Monitoring that should be used for scaling.

Value must match the regular expression [a-zA-Z0-9./@_][ 0-9a-zA-Z./@_,:;()\[\]<>-]{0,198}.
scalePolicy.
testAutoScale.
customRules[].
labels		 object

Labels of custom metric in Monitoring that should be used for scaling.

Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$. Each value must match the regular expression [a-zA-Z0-9./@_][ 0-9a-zA-Z./@_,:;()\[\]<>-]{0,198}.
scalePolicy.
testAutoScale.
customRules[].
target		 number (double)

Target value for the custom metric. Instance Groups maintains this level for each availability zone.

Value must be greater than 0.
scalePolicy.
testAutoScale.
customRules[].
folderId		 string

Folder id of custom metric in Monitoring that should be used for scaling.

The maximum string length in characters is 50.
scalePolicy.
testAutoScale.
customRules[].
service		 string

Service of custom metric in Monitoring that should be used for scaling.

The maximum string length in characters is 200.
scalePolicy.
testAutoScale.
autoScaleType		 string

Autoscaling type.

  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.
scalePolicy.
fixedScale		 object
Manual scaling policy of the instance group.
scalePolicy includes only one of the fields fixedScale, autoScale
scalePolicy.
fixedScale.
size		 string (int64)

Number of instances in the instance group.

Acceptable values are 1 to 100, inclusive.
scalePolicy.
autoScale		 object
Automatic scaling policy of the instance group.
scalePolicy includes only one of the fields fixedScale, autoScale
scalePolicy.
autoScale.
minZoneSize		 string (int64)

Lower limit for instance count in each zone.

Acceptable values are 0 to 100, inclusive.
scalePolicy.
autoScale.
maxSize		 string (int64)

Upper limit for total instance count (across all zones). 0 means maximum limit = 100.

Acceptable values are 0 to 100, inclusive.
scalePolicy.
autoScale.
measurementDuration		 string

Time in seconds allotted for averaging metrics. 1 minute by default.

Acceptable values are 60 seconds to 600 seconds, inclusive.
scalePolicy.
autoScale.
warmupDuration		 string

The warmup time of the instance in seconds. During this time, traffic is sent to the instance, but instance metrics are not collected.

The maximum value is 600 seconds.
scalePolicy.
autoScale.
stabilizationDuration		 string

Minimum amount of time in seconds allotted for monitoring before Instance Groups can reduce the number of instances in the group. During this time, the group size doesn't decrease, even if the new metric values indicate that it should.

Acceptable values are 60 seconds to 1800 seconds, inclusive.
scalePolicy.
autoScale.
initialSize		 string (int64)

Target group size.

The minimum value is 1.
scalePolicy.
autoScale.
cpuUtilizationRule		 object

Defines an autoscaling rule based on the average CPU utilization of the instance group.

If more than one rule is specified, e.g. CPU utilization and one or more Monitoring metrics (customRules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
scalePolicy.
autoScale.
cpuUtilizationRule.
utilizationTarget		 number (double)

Target CPU utilization level. Instance Groups maintains this level for each availability zone.

Acceptable values are 10 to 100, inclusive.
scalePolicy.
autoScale.
customRules[]		 object

Defines an autoscaling rule based on a custom metric from Monitoring.

If more than one rule is specified, e.g. CPU utilization (cpuUtilizationRule) and one or more Monitoring metrics, the size of the instance group will be equal to the maximum of sizes calculated according to each metric.

The maximum number of elements is 3.
scalePolicy.
autoScale.
customRules[].
ruleType		 string

Required. Custom metric rule type. This field affects which label from the custom metric should be used: zone_id or instance_id.

  • UTILIZATION: This type means that the metric applies to one instance. First, Instance Groups calculates the average metric value for each instance, then averages the values for instances in one availability zone or in whole group depends on autoscaling type. This type of metric must have the instance_id label.
  • WORKLOAD: This type means that the metric applies to instances in one availability zone or to whole group depends on autoscaling type. This type of metric must have the zone_id label if ZONAL autoscaling type is chosen.
scalePolicy.
autoScale.
customRules[].
metricType		 string

Required. Type of custom metric. This field affects how Instance Groups calculates the average metric value.

  • GAUGE: This type is used for metrics that show the metric value at a certain point in time, such as requests per second to the server on an instance.

    Instance Groups calculates the average metric value for the period specified in the measurementDuration field.

  • COUNTER: This type is used for metrics that monotonically increase over time, such as the total number of requests to the server on an instance.

    Instance Groups calculates the average value increase for the period specified in the measurementDuration field.
scalePolicy.
autoScale.
customRules[].
metricName		 string

Required. Name of custom metric in Monitoring that should be used for scaling.

Value must match the regular expression [a-zA-Z0-9./@_][ 0-9a-zA-Z./@_,:;()\[\]<>-]{0,198}.
scalePolicy.
autoScale.
customRules[].
labels		 object

Labels of custom metric in Monitoring that should be used for scaling.

Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$. Each value must match the regular expression [a-zA-Z0-9./@_][ 0-9a-zA-Z./@_,:;()\[\]<>-]{0,198}.
scalePolicy.
autoScale.
customRules[].
target		 number (double)

Target value for the custom metric. Instance Groups maintains this level for each availability zone.

Value must be greater than 0.
scalePolicy.
autoScale.
customRules[].
folderId		 string

Folder id of custom metric in Monitoring that should be used for scaling.

The maximum string length in characters is 50.
scalePolicy.
autoScale.
customRules[].
service		 string

Service of custom metric in Monitoring that should be used for scaling.

The maximum string length in characters is 200.
scalePolicy.
autoScale.
autoScaleType		 string

Autoscaling type.

  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.
deployPolicy object

Deployment policy of the instance group.
deployPolicy.
maxUnavailable		 string (int64)

The maximum number of running instances that can be taken offline (i.e., stopped or deleted) at the same time during the update process. If maxExpansion is not specified or set to zero, maxUnavailable must be set to a non-zero value.

Acceptable values are 0 to 100, inclusive.
deployPolicy.
maxDeleting		 string (int64)

The maximum number of instances that can be deleted at the same time.

The value 0 is any number of virtual machines within the allowed values.

Acceptable values are 0 to 100, inclusive.
deployPolicy.
maxCreating		 string (int64)

The maximum number of instances that can be created at the same time.

The value 0 is any number of virtual machines within the allowed values.

Acceptable values are 0 to 100, inclusive.
deployPolicy.
maxExpansion		 string (int64)

The maximum number of instances that can be temporarily allocated above the group's target size during the update process. If maxUnavailable is not specified or set to zero, maxExpansion must be set to a non-zero value.

Acceptable values are 0 to 100, inclusive.
deployPolicy.
startupDuration		 string

Instance startup duration. Instance will be considered up and running (and start receiving traffic) only after startup_duration has elapsed and all health checks are passed. See ManagedInstanceStatus for more information.

Acceptable values are 0 seconds to 3600 seconds, inclusive.
deployPolicy.
strategy		 string

Affects the lifecycle of the instance during deployment.

  • PROACTIVE: Instance Groups can forcefully stop a running instance. This is the default.
  • OPPORTUNISTIC: Instance Groups does not stop a running instance. Instead, it will wait until the instance stops itself or becomes unhealthy.
deployPolicy.
minimalAction		 string

If instance update requires a less disruptive action than minimalAction, Instance Groups performs minimalAction to execute the update

  • LIVE_UPDATE: Updating an instance without stopping. This is the default.
  • RESTART: Updating an instance with restart: stopping and then starting the instance.
  • RECREATE: Re-creating an instance: deleting an instance and creating a new one.
allocationPolicy object

Allocation policy of the instance group by zones and regions.
allocationPolicy.
zones[]		 object

Required. List of availability zones.

The minimum number of elements is 1.
allocationPolicy.
zones[].
zoneId		 string

Required. ID of the availability zone where the instance resides.
allocationPolicy.
zones[].
instanceTagsPool[]		 string

Each instance in a zone will be associated with exactly one of a tag from a pool below. All specified tags must be unique across the whole group not only the zone. It is guaranteed that during whole deploy only tags from prefix of the specified list will be used. It is possible to use tag associated with instance in templating via {instance.tag}.

The string length in characters for each value must be 3-50.
loadBalancerState object

Status of the Network Load Balancer target group attributed to the instance group.
loadBalancerState.
targetGroupId		 string

ID of the Network Load Balancer target group attributed to the instance group.
loadBalancerState.
statusMessage		 string

Status message of the target group.
managedInstancesState object

States of instances for this instance group.
managedInstancesState.
targetSize		 string (int64)

Target number of instances for this instance group.
managedInstancesState.
runningActualCount		 string (int64)

The number of running instances that match the current instance template. For more information, see RUNNING_ACTUAL.
managedInstancesState.
runningOutdatedCount		 string (int64)

The number of running instances that does not match the current instance template. For more information, see RUNNING_OUTDATED.
managedInstancesState.
processingCount		 string (int64)

The number of instances in flight (for example, updating, starting, deleting). For more information, see ManagedInstanceStatus.
loadBalancerSpec object

Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
loadBalancerSpec.
targetGroupSpec		 object

Specification of the target group that the instance group will be added to. For more information, see Target groups and resources.
loadBalancerSpec.
targetGroupSpec.
name		 string

Name of the target group.

Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
loadBalancerSpec.
targetGroupSpec.
description		 string

Description of the target group.

The maximum string length in characters is 256.
loadBalancerSpec.
targetGroupSpec.
labels		 object

Resource labels as key:value pairs.

No more than 64 per resource. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\@0-9a-z]*. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\@0-9a-z]*.
loadBalancerSpec.
maxOpeningTrafficDuration		 string

Timeout for waiting for the VM to be checked by the load balancer. If the timeout is exceeded, the VM will be turned off based on the deployment policy. Specified in seconds.

The minimum value is 1 seconds.
loadBalancerSpec.
ignoreHealthChecks		 boolean (boolean)

Do not wait load balancer health checks.
healthChecksSpec object

Health checking specification. For more information, see Health check.
healthChecksSpec.
healthCheckSpecs[]		 object

Required. Health checking specification. For more information, see Health check.

The minimum number of elements is 1.
healthChecksSpec.
healthCheckSpecs[].
interval		 string

The interval between health checks. The default is 2 seconds.

Acceptable values are 1 seconds to 300 seconds, inclusive.
healthChecksSpec.
healthCheckSpecs[].
timeout		 string

Timeout for the managed instance to return a response for the health check. The default is 1 second.

Acceptable values are 1 seconds to 60 seconds, inclusive.
healthChecksSpec.
healthCheckSpecs[].
unhealthyThreshold		 string (int64)

The number of failed health checks for the managed instance to be considered unhealthy. The default (0) is 2.

Value must be one of 0, 2, 3, 4, 5, 6, 7, 8, 9 or 10.
healthChecksSpec.
healthCheckSpecs[].
healthyThreshold		 string (int64)

The number of successful health checks required in order for the managed instance to be considered healthy. The default (0) is 2.

Value must be one of 0, 2, 3, 4, 5, 6, 7, 8, 9 or 10.
healthChecksSpec.
healthCheckSpecs[].
tcpOptions		 object
Configuration options for a TCP health check.
healthChecksSpec.healthCheckSpecs[] includes only one of the fields tcpOptions, httpOptions
healthChecksSpec.
healthCheckSpecs[].
tcpOptions.
port		 string (int64)

Port to use for TCP health checks.

Acceptable values are 1 to 65535, inclusive.
healthChecksSpec.
healthCheckSpecs[].
httpOptions		 object
Configuration options for an HTTP health check.
healthChecksSpec.healthCheckSpecs[] includes only one of the fields tcpOptions, httpOptions
healthChecksSpec.
healthCheckSpecs[].
httpOptions.
port		 string (int64)

Port to use for HTTP health checks.

Acceptable values are 1 to 65535, inclusive.
healthChecksSpec.
healthCheckSpecs[].
httpOptions.
path		 string

URL path to set for health checking requests.
healthChecksSpec.
maxCheckingHealthDuration		 string

Timeout for waiting for the VM to become healthy. If the timeout is exceeded, the VM will be turned off based on the deployment policy. Specified in seconds.

The minimum value is 1 seconds.
serviceAccountId string

ID of the service account. The service account will be used for all API calls made by the Instance Groups component on behalf of the user (for example, creating instances, adding them to load balancer target group, etc.). For more information, see Service accounts. To get the service account ID, use a list request.
status string

Status of the instance group.

  • STARTING: Instance group is being started and will become active soon.

  • ACTIVE: Instance group is active. In this state the group manages its instances and monitors their health, creating, deleting, stopping, updating and starting instances as needed.

    To stop the instance group, call stop. To pause the processes in the instance group, i.e. scaling, checking instances' health, auto-healing and updating them, without stopping the instances, call pauseProcesses.

  • STOPPING: Instance group is being stopped. Group's instances stop receiving traffic from the load balancer (if any) and are then stopped.

  • STOPPED: Instance group is stopped. In this state the group cannot be updated and does not react to any changes made to its instances. To start the instance group, call start.

  • DELETING: Instance group is being deleted.

  • PAUSED: Instance group is paused. In this state all the processes regarding the group management, i.e. scaling, checking instances' health, auto-healing and updating them, are paused. The instances that were running prior to pausing the group, however, may still be running.

    To resume the processes in the instance group, call resumeProcesses. The group status will change to ACTIVE.
variables[] object
variables[].
key		 string

The string length in characters must be 1-128. Value must match the regular expression [a-zA-Z0-9._-]*.
variables[].
value		 string

The maximum string length in characters is 128.
deletionProtection boolean (boolean)

Flag prohibiting deletion of the instance group.

Allowed values:
- false: The instance group can be deleted.
- true: The instance group cannot be deleted.

The default is false.
applicationLoadBalancerSpec object

Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
applicationLoadBalancerSpec.
targetGroupSpec		 object

Required. Basic properties of the Application Load Balancer target group attributed to the instance group.
applicationLoadBalancerSpec.
targetGroupSpec.
name		 string

Name of the target group.
applicationLoadBalancerSpec.
targetGroupSpec.
description		 string

Description of the target group.
applicationLoadBalancerSpec.
targetGroupSpec.
labels		 object

Resource labels as key:value pairs.
applicationLoadBalancerSpec.
maxOpeningTrafficDuration		 string

Timeout for waiting for the VM to be checked by the load balancer. If the timeout is exceeded, the VM will be turned off based on the deployment policy. Specified in seconds.

The minimum value is 1 seconds.
applicationLoadBalancerSpec.
ignoreHealthChecks		 boolean (boolean)

Do not wait load balancer health checks.
applicationLoadBalancerState object

Status of the Application Load Balancer target group attributed to the instance group.

Returned if there is a working load balancer that the target group is connected to.
applicationLoadBalancerState.
targetGroupId		 string

ID of the Application Load Balancer target group attributed to the instance group.
applicationLoadBalancerState.
statusMessage		 string

Status message of the target group.
autoHealingPolicy object

AutoHealingPolicy policy of the instance group.
autoHealingPolicy.
autoHealingAction		 string

Instance Groups performs autoHealingAction when instance becomes unhealthy.

  • RESTART: Re-starting an instance with restart: stopping and then starting the instance.
  • RECREATE: Re-creating an instance: deleting an instance and creating a new one.
  • NONE: No action

Methods

Method Description
create Creates an instance group in the specified folder. This method starts an operation that can be cancelled by another operation.
createFromYaml Creates an instance group in the specified folder from a YAML file. This method starts an operation that can be cancelled by another operation.
delete Deletes the specified instance group.
get Returns the specified InstanceGroup resource.
list Retrieves the list of InstanceGroup resources in the specified folder.
listAccessBindings Lists existing access bindings for the specified instance group.
listInstances Lists instances for the specified instance group.
listLogRecords Lists logs for the specified instance group.
listOperations Lists operations for the specified instance group.
pauseProcesses Pauses all processes regarding management of the specified instance group, i.e. scaling, checking instances' health, auto-healing and updating them. Running instances are not stopped.
resumeProcesses Resumes all processes regarding management of the specified instance group, i.e. scaling, checking instances' health, auto-healing and updating them.
rollingRecreate Performs rolling recreate of specified instances for the specified instance group. Rolling recreate does recreate of instance VMs respecting all group policies.
rollingRestart Performs rolling restart of specified instances for the specified instance group. Rolling restart does restart of instances respecting all group policies.
setAccessBindings Sets access bindings for the specified instance group.
start Starts the specified instance group.
stop Stops the specified instance group.
update Updates the specified instance group. This method starts an operation that can be cancelled by another operation.
updateAccessBindings Updates access bindings for the specified instance group.
updateFromYaml Updates the specified instance group from a YAML file. This method starts an operation that can be cancelled by another operation.
Previous
get
Next
create