Method list

Retrieves the list of InstanceGroup resources in the specified folder.

HTTP request

GET https://compute.api.cloud.yandex.net/compute/v1/instanceGroups

Query parameters

Parameter Description
folderId Required. ID of the folder to list instance groups in. To get the folder ID, use a list request.
pageSize The maximum number of results per page to return. If the number of available results is larger than pageSize, the service returns a nextPageToken that can be used to get the next page of results in subsequent list requests. The maximum value is 1000.
pageToken Page token. To get the next page of results, set pageToken to the nextPageToken returned by a previous list request. The maximum string length in characters is 100.
filter A filter expression that filters resources listed in the response. Currently you can use filtering only on the InstanceGroup.name field. The maximum string length in characters is 1000.
view Defines which information about the Instance template should be returned in the server response.
  • BASIC: Doesn't include the metadata of the instance template in the server response.
  • FULL: Returns the metadata of the instance template in the server response.

Response

HTTP Code: 200 - OK

{
  "instanceGroups": [
    {
      "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",

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

          }
        },
        "secondaryDiskSpecs": [
          {
            "mode": "string",
            "deviceName": "string",
            "diskSpec": {
              "description": "string",
              "typeId": "string",
              "size": "string",

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

            }
          }
        ],
        "networkInterfaceSpecs": [
          {
            "networkId": "string",
            "subnetIds": [
              "string"
            ],
            "primaryV4AddressSpec": {
              "oneToOneNatSpec": {
                "ipVersion": "string"
              }
            },
            "primaryV6AddressSpec": {
              "oneToOneNatSpec": {
                "ipVersion": "string"
              }
            }
          }
        ],
        "schedulingPolicy": {
          "preemptible": true
        },
        "serviceAccountId": "string"
      },
      "scalePolicy": {

        // `instanceGroups[].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"
          }
        },
        // end of the list of possible fields`instanceGroups[].scalePolicy`

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

            // `instanceGroups[].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`instanceGroups[].healthChecksSpec.healthCheckSpecs[]`

          }
        ]
      },
      "serviceAccountId": "string",
      "status": "string"
    }
  ],
  "nextPageToken": "string"
}
Field Description
instanceGroups[] object

Lists instance groups for the specified folder.

instanceGroups[].
id
string

ID of the instance group.

instanceGroups[].
folderId
string

ID of the folder that the instance group belongs to.

instanceGroups[].
createdAt
string (date-time)

Creation timestamp in RFC3339 text format.

String in RFC3339 text format.

instanceGroups[].
name
string

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

instanceGroups[].
description
string

Description of the instance group.

instanceGroups[].
labels
object

Resource labels as key:value pairs.

instanceGroups[].
instanceTemplate
object

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

instanceGroups[].
instanceTemplate.
description
string

Description of the instance template.

The maximum string length in characters is 256.

instanceGroups[].
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 63. Each value must match the regular expression [-_0-9a-z].

instanceGroups[].
instanceTemplate.
platformId
string

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.

instanceGroups[].
instanceTemplate.
resourcesSpec
object

Required. Computing resources of the instance such as the amount of memory and number of cores.

instanceGroups[].
instanceTemplate.
resourcesSpec.
memory
string (int64)

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

The maximum value is 274877906944.

instanceGroups[].
instanceTemplate.
resourcesSpec.
cores
string (int64)

The number of cores available to the instance.

Value must be one of 1, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 22, 24, 26, 28, 30, 32, 34, 36, 40, 44, 48, 52, 56, 60 or 64.

instanceGroups[].
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.

instanceGroups[].
instanceTemplate.
resourcesSpec.
gpus
string (int64)

The number of GPUs available to the instance.

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

instanceGroups[].
instanceTemplate.
metadata
object

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

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.

instanceGroups[].
instanceTemplate.
bootDiskSpec
object

Required. Boot disk specification that will be attached to the instance.

instanceGroups[].
instanceTemplate.
bootDiskSpec.
mode
string

Required. Access mode to the Disk resource.

  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
instanceGroups[].
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}.

instanceGroups[].
instanceTemplate.
bootDiskSpec.
diskSpec
object

Required. Disk specification that is attached to the instance. For more information, see Disks.

instanceGroups[].
instanceTemplate.
bootDiskSpec.
diskSpec.
description
string

Description of the disk.

The maximum string length in characters is 256.

instanceGroups[].
instanceTemplate.
bootDiskSpec.
diskSpec.
typeId
string

Required. ID of the disk type.

instanceGroups[].
instanceTemplate.
bootDiskSpec.
diskSpec.
size
string (int64)

Size of the disk, specified in bytes.

Acceptable values are 4194304 to 4398046511104, inclusive.

instanceGroups[].
instanceTemplate.
bootDiskSpec.
diskSpec.
imageId
string
instanceGroups[].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.

instanceGroups[].
instanceTemplate.
bootDiskSpec.
diskSpec.
snapshotId
string
instanceGroups[].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.

instanceGroups[].
instanceTemplate.
secondaryDiskSpecs[]
object

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

The maximum number of elements is 3.

instanceGroups[].
instanceTemplate.
secondaryDiskSpecs[].
mode
string

Required. Access mode to the Disk resource.

  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
instanceGroups[].
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}.

instanceGroups[].
instanceTemplate.
secondaryDiskSpecs[].
diskSpec
object

Required. Disk specification that is attached to the instance. For more information, see Disks.

instanceGroups[].
instanceTemplate.
secondaryDiskSpecs[].
diskSpec.
description
string

Description of the disk.

The maximum string length in characters is 256.

instanceGroups[].
instanceTemplate.
secondaryDiskSpecs[].
diskSpec.
typeId
string

Required. ID of the disk type.

instanceGroups[].
instanceTemplate.
secondaryDiskSpecs[].
diskSpec.
size
string (int64)

Size of the disk, specified in bytes.

Acceptable values are 4194304 to 4398046511104, inclusive.

instanceGroups[].
instanceTemplate.
secondaryDiskSpecs[].
diskSpec.
imageId
string
instanceGroups[].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.

instanceGroups[].
instanceTemplate.
secondaryDiskSpecs[].
diskSpec.
snapshotId
string
instanceGroups[].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.

instanceGroups[].
instanceTemplate.
networkInterfaceSpecs[]
object

Required. Array of network interfaces that will be attached to the instance.

Must contain exactly 1 element.

instanceGroups[].
instanceTemplate.
networkInterfaceSpecs[].
networkId
string

ID of the network.

instanceGroups[].
instanceTemplate.
networkInterfaceSpecs[].
subnetIds[]
string

IDs of the subnets.

instanceGroups[].
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec
object

Primary IPv4 address that is assigned to the instance for this network interface.

instanceGroups[].
instanceTemplate.
networkInterfaceSpecs[].
primaryV4AddressSpec.
oneToOneNatSpec
object

An external IP address configuration. If not specified, then this managed instance will have no external internet access.

instanceGroups[].
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.
instanceGroups[].
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec
object

Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.

instanceGroups[].
instanceTemplate.
networkInterfaceSpecs[].
primaryV6AddressSpec.
oneToOneNatSpec
object

An external IP address configuration. If not specified, then this managed instance will have no external internet access.

instanceGroups[].
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.
instanceGroups[].
instanceTemplate.
schedulingPolicy
object

Scheduling policy for the instance.

instanceGroups[].
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.

instanceGroups[].
instanceTemplate.
serviceAccountId
string

Service account ID for the instance.

instanceGroups[].
scalePolicy
object

Scaling policy of the instance group.

instanceGroups[].
scalePolicy.
fixedScale
object
Fixed scaling policy of the instance group.
instanceGroups[].scalePolicy includes only one of the fields fixedScale, autoScale

instanceGroups[].
scalePolicy.
fixedScale.
size
string (int64)

Number of instances in the instance group.

Acceptable values are 1 to 100, inclusive.

instanceGroups[].
scalePolicy.
autoScale
object
instanceGroups[].scalePolicy includes only one of the fields fixedScale, autoScale

instanceGroups[].
scalePolicy.
autoScale.
minZoneSize
string (int64)

Lower limit for instance count in each zone.

Acceptable values are 0 to 100, inclusive.

instanceGroups[].
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.

instanceGroups[].
scalePolicy.
autoScale.
measurementDuration
string

Required. Acceptable values are 60 seconds to 600 seconds, inclusive.

instanceGroups[].
scalePolicy.
autoScale.
warmupDuration
string

The maximum value is 600 seconds.

instanceGroups[].
scalePolicy.
autoScale.
stabilizationDuration
string

Acceptable values are 60 seconds to 1800 seconds, inclusive.

instanceGroups[].
scalePolicy.
autoScale.
initialSize
string (int64)

The minimum value is 1.

instanceGroups[].
scalePolicy.
autoScale.
cpuUtilizationRule
object
instanceGroups[].
scalePolicy.
autoScale.
cpuUtilizationRule.
utilizationTarget
number (double)

Acceptable values are 10 to 100, inclusive.

instanceGroups[].
deployPolicy
object

Deployment policy of the instance group.

instanceGroups[].
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.

instanceGroups[].
deployPolicy.
maxDeleting
string (int64)

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

Acceptable values are 0 to 100, inclusive.

instanceGroups[].
deployPolicy.
maxCreating
string (int64)

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

Acceptable values are 0 to 100, inclusive.

instanceGroups[].
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.

instanceGroups[].
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.

instanceGroups[].
allocationPolicy
object

Allocation policy of the instance group by zones and regions.

instanceGroups[].
allocationPolicy.
zones[]
object

Required. List of availability zones.

The minimum number of elements is 1.

instanceGroups[].
allocationPolicy.
zones[].
zoneId
string

Required. ID of the availability zone where the instance resides.

instanceGroups[].
loadBalancerState
object

Information that indicates which entities can be related to this load balancer.

instanceGroups[].
loadBalancerState.
targetGroupId
string

ID of the target group used for load balancing.

instanceGroups[].
loadBalancerState.
statusMessage
string

Status message of the target group.

instanceGroups[].
managedInstancesState
object

States of instances for this instance group.

instanceGroups[].
managedInstancesState.
targetSize
string (int64)

Target number of instances for this instance group.

instanceGroups[].
managedInstancesState.
runningActualCount
string (int64)

The number of running instances that match the current instance template. For more information, see RUNNING_ACTUAL.

instanceGroups[].
managedInstancesState.
runningOutdatedCount
string (int64)

The number of running instances that does not match the current instance template. For more information, see RUNNING_OUTDATED.

instanceGroups[].
managedInstancesState.
processingCount
string (int64)

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

instanceGroups[].
loadBalancerSpec
object

Load balancing specification.

instanceGroups[].
loadBalancerSpec.
targetGroupSpec
object

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

instanceGroups[].
loadBalancerSpec.
targetGroupSpec.
name
string

Name of the target group.

Value must match the regular expression |[a-z][-a-z0-9]{1,61}[a-z0-9].

instanceGroups[].
loadBalancerSpec.
targetGroupSpec.
description
string

Description of the target group.

The maximum string length in characters is 256.

instanceGroups[].
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].

instanceGroups[].
healthChecksSpec
object

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

instanceGroups[].
healthChecksSpec.
healthCheckSpecs[]
object

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

The minimum number of elements is 1.

instanceGroups[].
healthChecksSpec.
healthCheckSpecs[].
interval
string

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

Acceptable values are 1 seconds to 300 seconds, inclusive.

instanceGroups[].
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.

instanceGroups[].
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.

instanceGroups[].
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.

instanceGroups[].
healthChecksSpec.
healthCheckSpecs[].
tcpOptions
object
Configuration options for a TCP health check.
instanceGroups[].healthChecksSpec.healthCheckSpecs[] includes only one of the fields tcpOptions, httpOptions

instanceGroups[].
healthChecksSpec.
healthCheckSpecs[].
tcpOptions.
port
string (int64)

Port to use for TCP health checks.

Acceptable values are 1 to 32767, inclusive.

instanceGroups[].
healthChecksSpec.
healthCheckSpecs[].
httpOptions
object
Configuration options for an HTTP health check.
instanceGroups[].healthChecksSpec.healthCheckSpecs[] includes only one of the fields tcpOptions, httpOptions

instanceGroups[].
healthChecksSpec.
healthCheckSpecs[].
httpOptions.
port
string (int64)

Port to use for HTTP health checks.

Acceptable values are 1 to 32767, inclusive.

instanceGroups[].
healthChecksSpec.
healthCheckSpecs[].
httpOptions.
path
string

URL path to set for health checking requests.

instanceGroups[].
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.

instanceGroups[].
status
string

TODO DOC-REVIEW: Status of the instance group.

TODO DOC-REVIEW:

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

This token allows you to get the next page of results for list requests. If the number of results is larger than pageSize, use nextPageToken as the value for the pageToken query parameter in the next list request. Each subsequent list request will have its own nextPageToken to continue paging through the results.