Get started
Log in
Yandex Compute Cloud

Method create

Creates an instance group in the specified folder. This method starts an operation that can be cancelled by another operation.

HTTP request

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

Body parameters

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

        // `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`

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

          // `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`

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

    // `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",
          "target": "number"
        }
      ]
    },
    // end of the list of possible fields`scalePolicy`

  },
  "deployPolicy": {
    "maxUnavailable": "string",
    "maxDeleting": "string",
    "maxCreating": "string",
    "maxExpansion": "string",
    "startupDuration": "string"
  },
  "allocationPolicy": {
    "zones": [
      {
        "zoneId": "string"
      }
    ]
  },
  "loadBalancerSpec": {
    "targetGroupSpec": {
      "name": "string",
      "description": "string",
      "labels": "object"
    }
  },
  "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[]`

      }
    ]
  },
  "serviceAccountId": "string"
}
Field Description
folderId string

Required. ID of the folder to create an instance group in. To get the folder ID, use a list request.
name string

Name of the instance group.

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

Description of the instance group.

The maximum string length in characters is 256.
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].
instanceTemplate object

Required. Instance template that the instance group belongs to.
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 63. Each value must match the regular expression [-_0-9a-z].
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.
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 274877906944.
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.
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.

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. 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 4398046511104, inclusive.
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.
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. 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 4398046511104, inclusive.
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.
networkInterfaceSpecs[]		 object

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

Must contain exactly 1 element.
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[].
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.
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.
scalePolicy object

Required. Scaling policy of the instance group.
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

Required. Time in seconds allotted for averaging metrics.

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.
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 Yandex Monitoring.

The maximum number of elements is 1.
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. This type of metric must have the instance_id label.
  • WORKLOAD: This type means that the metric applies to instances in one availability zone. This type of metric must have the zone_id label.
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 Yandex 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[].
target		 number (double)

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

Value must be greater than 0.
deployPolicy object

Required. 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.

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

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

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.
allocationPolicy object

Required. 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.
loadBalancerSpec object

Load balancing specification.
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]{1,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].
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 32767, 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 32767, inclusive.
healthChecksSpec.
healthCheckSpecs[].
httpOptions.
path		 string

URL path to set for health checking requests.
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.

Response

HTTP Code: 200 - OK

{
  "id": "string",
  "description": "string",
  "createdAt": "string",
  "createdBy": "string",
  "modifiedAt": "string",
  "done": true,
  "metadata": "object",

  //  includes only one of the fields `error`, `response`
  "error": {
    "code": "integer",
    "message": "string",
    "details": [
      "object"
    ]
  },
  "response": "object",
  // end of the list of possible fields

}

An Operation resource. For more information, see Operation.

Field Description
id string

ID of the operation.
description string

Description of the operation. 0-256 characters long.
createdAt string (date-time)

Creation timestamp.

String in RFC3339 text format.
createdBy string

ID of the user or service account who initiated the operation.
modifiedAt string (date-time)

The time when the Operation resource was last modified.

String in RFC3339 text format.
done boolean (boolean)

If the value is false, it means the operation is still in progress. If true, the operation is completed, and either error or response is available.
metadata object

Service-specific metadata associated with the operation. It typically contains the ID of the target resource that the operation is performed on. Any method that returns a long-running operation should document the metadata type, if any.
error object
The error result of the operation in case of failure or cancellation.
includes only one of the fields error, response

The error result of the operation in case of failure or cancellation.
error.
code		 integer (int32)

Error code. An enum value of google.rpc.Code.
error.
message		 string

An error message.
error.
details[]		 object

A list of messages that carry the error details.
response object
includes only one of the fields error, response

The normal response of the operation in case of success. If the original method returns no data on success, such as Delete, the response is google.protobuf.Empty. If the original method is the standard Create/Update, the response should be the target resource of the operation. Any method that returns a long-running operation should document the response type, if any.