Contact UsGet started
© 2024 Iron Hive LLC Belgrade

Compute Cloud API, gRPC: InstanceGroupService

Written by
Updated at September 4, 2024

A set of methods for managing InstanceGroup resources.

Call Description
Get Returns the specified InstanceGroup resource.
List Retrieves the list of InstanceGroup resources in the specified folder.
Create Creates an instance group in the specified folder.
CreateFromYaml Creates an instance group in the specified folder from a YAML file.
Update Updates the specified instance group.
UpdateFromYaml Updates the specified instance group from a YAML file.
Stop Stops the specified instance group.
RollingRestart Performs rolling restart of specified instances for the specified instance group.
RollingRecreate Performs rolling recreate of specified instances for the specified instance group.
Start Starts the specified instance group.
Delete Deletes the specified instance group.
ListInstances Lists instances for the specified instance group.
DeleteInstances Delete instances from the instance group.
StopInstances Stop instances from the instance group.
ListOperations Lists operations for the specified instance group.
ListLogRecords Lists logs for the specified instance group.
ListAccessBindings Lists existing access bindings for the specified instance group.
SetAccessBindings Sets access bindings for the specified instance group.
UpdateAccessBindings Updates access bindings for the specified instance group.
ResumeProcesses Resumes all processes regarding management of the specified instance group, i.e.
PauseProcesses Pauses all processes regarding management of the specified instance group, i.e.

Calls InstanceGroupService

Get

Returns the specified InstanceGroup resource.
To get the list of available InstanceGroup resources, make a List request.

rpc Get (GetInstanceGroupRequest) returns (InstanceGroup)

GetInstanceGroupRequest

Field Description
instance_group_id string
Required. ID of the InstanceGroup resource to return. To get the instance group ID, use a InstanceGroupService.List request. The maximum string length in characters is 50.
view enum InstanceGroupView
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.

InstanceGroup

Field Description
id string
ID of the instance group.
folder_id string
ID of the folder that the instance group belongs to.
created_at google.protobuf.Timestamp
Creation timestamp in RFC3339 text format.
name string
Name of the instance group. The name is unique within the folder.
description string
Description of the instance group.
labels map<string,string>
Resource labels as key:value pairs.
instance_template InstanceTemplate
Instance template for creating the instance group. For more information, see Instance Templates.
scale_policy ScalePolicy
Scaling policy of the instance group.
deploy_policy DeployPolicy
Deployment policy of the instance group.
allocation_policy AllocationPolicy
Allocation policy of the instance group by zones and regions.
load_balancer_state LoadBalancerState
Status of the Network Load Balancer target group attributed to the instance group.
managed_instances_state ManagedInstancesState
States of instances for this instance group.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
status enum Status
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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.ResumeProcesses. The group status will change to ACTIVE.
variables[] Variable
deletion_protection bool
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.
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
application_load_balancer_state ApplicationLoadBalancerState
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.
auto_healing_policy AutoHealingPolicy
AutoHealingPolicy policy of the instance group.

InstanceTemplate

Field Description
description string
Description of the instance template. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 128. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
platform_id 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.
resources_spec ResourcesSpec
Required. Computing resources of the instance such as the amount of memory and number of cores.
metadata map<string,string>
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 maximum string length in characters for each value is 262144. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_0-9a-z]*.
boot_disk_spec AttachedDiskSpec
Required. Boot disk specification that will be attached to the instance.
secondary_disk_specs[] AttachedDiskSpec
Array of secondary disks that will be attached to the instance. The maximum number of elements is 3.
network_interface_specs[] NetworkInterfaceSpec
Required. Array of network interfaces that will be attached to the instance.
scheduling_policy SchedulingPolicy
Scheduling policy for the instance.
service_account_id string
Service account ID for the instance.
network_settings NetworkSettings
Network settings for the instance.
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.
hostname string
Host name for the instance. This field is used to generate the yandex.cloud.compute.v1.Instance.fqdn value. The host name must be unique within the network and region. If not specified, the host name will be equal to yandex.cloud.compute.v1.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.
placement_policy PlacementPolicy
Placement Group
filesystem_specs[] AttachedFilesystemSpec
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.
metadata_options MetadataOptions
Metadata options for the instance

ResourcesSpec

Field Description
memory int64
The amount of memory available to the instance, specified in bytes. The maximum value is 824633720832.
cores int64
The number of cores available to the instance. Value must be equal to 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,80.
core_fraction 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 equal to 0,5,20,50,100.
gpus int64
The number of GPUs available to the instance. Value must be equal to 0,1,2,4.

AttachedDiskSpec

Field Description
mode enum Mode
Required. Access mode to the Disk resource.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
device_name 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}.
disk_spec DiskSpec
Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
disk_id 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._{}]*.
name string
When set can be later used to change DiskSpec of actual disk. The maximum string length in characters is 128.

DiskSpec

Field Description
description string
Description of the disk. The maximum string length in characters is 256.
type_id string
Required. ID of the disk type.
size int64
Size of the disk, specified in bytes. Acceptable values are 4194304 to 28587302322176, inclusive.
source_oneof oneof: image_id or snapshot_id
  image_id string
ID of the image that will be used for disk creation. The maximum string length in characters is 50.
  snapshot_id string
ID of the snapshot that will be used for disk creation. The maximum string length in characters is 50.
preserve_after_instance_delete bool
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.

NetworkInterfaceSpec

Field Description
network_id string
ID of the network.
subnet_ids[] string
IDs of the subnets.
primary_v4_address_spec PrimaryAddressSpec
Primary IPv4 address that is assigned to the instance for this network interface.
primary_v6_address_spec PrimaryAddressSpec
Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.
security_group_ids[] string
IDs of security groups.

PrimaryAddressSpec

Field Description
one_to_one_nat_spec OneToOneNatSpec
An external IP address configuration. If not specified, then this managed instance will have no external internet access.
dns_record_specs[] DnsRecordSpec
Internal DNS configuration
address string
Optional. Manual set static internal IP. To set use variables.

OneToOneNatSpec

Field Description
ip_version enum IpVersion
IP version for the public IP address.
  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
address string
Manual set static public IP. To set use variables. (optional)
dns_record_specs[] DnsRecordSpec
External DNS configuration

DnsRecordSpec

Field Description
fqdn string
Required. FQDN (required)
dns_zone_id string
DNS zone id (optional, if not set, private zone used)
ttl int64
DNS record ttl, values in 0-86400 (optional) Acceptable values are 0 to 86400, inclusive.
ptr bool
When set to true, also create PTR DNS record (optional)

SchedulingPolicy

Field Description
preemptible bool
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.

NetworkSettings

Field Description
type enum Type
Type of instance network.

PlacementPolicy

Field Description
placement_group_id string
Identifier of placement group
host_affinity_rules[] HostAffinityRule
List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

HostAffinityRule

Field Description
key string
Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'
op enum Operator
Include or exclude action
values[] string
Affinity value or host ID or host group ID

AttachedFilesystemSpec

Field Description
mode enum Mode
Mode of access to the filesystem that should be attached.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.
device_name 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}.
filesystem_id 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._{}]*.

MetadataOptions

Field Description
gce_http_endpoint enum MetadataOption
Enabled access to GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_endpoint enum MetadataOption
Enabled access to AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
gce_http_token enum MetadataOption
Enabled access to IAM credentials with GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_token enum MetadataOption
Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

ScalePolicy

Field Description
scale_type oneof: fixed_scale or auto_scale
  fixed_scale FixedScale
Manual scaling policy of the instance group.
  auto_scale AutoScale
Automatic scaling policy of the instance group.
test_auto_scale AutoScale
Test spec for automatic scaling policy of the instance group.

AutoScale

Field Description
min_zone_size int64
Lower limit for instance count in each zone. Acceptable values are 0 to 100, inclusive.
max_size int64
Upper limit for total instance count (across all zones). 0 means maximum limit = 100. Acceptable values are 0 to 100, inclusive.
measurement_duration google.protobuf.Duration
Time in seconds allotted for averaging metrics. 1 minute by default. Acceptable values are 1m to 10m, inclusive.
warmup_duration google.protobuf.Duration
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 10m.
stabilization_duration google.protobuf.Duration
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 1m to 30m, inclusive.
initial_size int64
Target group size. The minimum value is 1.
cpu_utilization_rule CpuUtilizationRule
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 (custom_rules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
custom_rules[] CustomRule
Defines an autoscaling rule based on a custom metric from Monitoring.
If more than one rule is specified, e.g. CPU utilization (cpu_utilization_rule) 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.
auto_scale_type enum AutoScaleType
Autoscaling type.
  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.

CpuUtilizationRule

Field Description
utilization_target double
Target CPU utilization level. Instance Groups maintains this level for each availability zone. Acceptable values are 10 to 100, inclusive.

CustomRule

Field Description
rule_type enum RuleType
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.
metric_type enum MetricType
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 AutoScale.measurement_duration 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 AutoScale.measurement_duration field.
metric_name 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}.
labels map<string,string>
Labels of custom metric in Monitoring that should be used for scaling. Each value must match the regular expression [a-zA-Z0-9./@_][0-9a-zA-Z./@_,:;()\\[\\]<>-]{0,198}. Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$.
target double
Target value for the custom metric. Instance Groups maintains this level for each availability zone. Value must be greater than 0.
folder_id string
Folder id of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 50.
service string
Service of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 200.

FixedScale

Field Description
size int64
Number of instances in the instance group. Acceptable values are 1 to 100, inclusive.

DeployPolicy

Field Description
max_unavailable 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 max_expansion is not specified or set to zero, max_unavailable must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
max_deleting 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.
max_creating 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.
max_expansion int64
The maximum number of instances that can be temporarily allocated above the group's target size during the update process. If max_unavailable is not specified or set to zero, max_expansion must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
startup_duration google.protobuf.Duration
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 yandex.cloud.compute.v1.instancegroup.ManagedInstance.Status for more information. Acceptable values are 0m to 1h, inclusive.
strategy enum Strategy
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.
minimal_action enum MinimalAction
If instance update requires a less disruptive action than minimal_action, Instance Groups performs minimal_action 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

Field Description
zones[] Zone
List of availability zones. The minimum number of elements is 1.

Zone

Field Description
zone_id string
Required. ID of the availability zone where the instance resides.
instance_tags_pool[] 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

Field Description
target_group_id string
ID of the Network Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

ManagedInstancesState

Field Description
target_size int64
Target number of instances for this instance group.
running_actual_count int64
The number of running instances that match the current instance template. For more information, see ManagedInstance.Status.RUNNING_ACTUAL.
running_outdated_count int64
The number of running instances that does not match the current instance template. For more information, see ManagedInstance.Status.RUNNING_OUTDATED.
processing_count int64
The number of instances in flight (for example, updating, starting, deleting). For more information, see ManagedInstance.Status.

Statuses

Field Description
creating int64
Instance is being created.
starting int64
Instance is being started.
opening int64
Instance is being opened to receive traffic.
warming int64
Instance is being warmed.
running int64
Instance is running normally.
closing int64
Instance is being closed to traffic.
stopping int64
Instance is being stopped.
updating int64
Instance is being updated.
deleting int64
Instance is being deleted.
failed int64
Instance failed and needs to be recreated.

LoadBalancerSpec

Field Description
target_group_spec TargetGroupSpec
Specification of the target group that the instance group will be added to. For more information, see Target groups and resources.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

TargetGroupSpec

Field Description
name string
Name of the target group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the target group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.

HealthChecksSpec

Field Description
health_check_specs[] HealthCheckSpec
Health checking specification. For more information, see Health check. The minimum number of elements is 1.
max_checking_health_duration google.protobuf.Duration
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 1s.

HealthCheckSpec

Field Description
interval google.protobuf.Duration
The interval between health checks. The default is 2 seconds. Acceptable values are 1s to 300s, inclusive.
timeout google.protobuf.Duration
Timeout for the managed instance to return a response for the health check. The default is 1 second. Acceptable values are 1s to 60s, inclusive.
unhealthy_threshold int64
The number of failed health checks for the managed instance to be considered unhealthy. The default (0) is 2. Value must be equal to 0,2,3,4,5,6,7,8,9,10.
healthy_threshold 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 equal to 0,2,3,4,5,6,7,8,9,10.
health_check_options oneof: tcp_options or http_options
  tcp_options TcpOptions
Configuration options for a TCP health check.
  http_options HttpOptions
Configuration options for an HTTP health check.

TcpOptions

Field Description
port int64
Port to use for TCP health checks. Acceptable values are 1 to 65535, inclusive.

HttpOptions

Field Description
port int64
Port to use for HTTP health checks. Acceptable values are 1 to 65535, inclusive.
path string
URL path to set for health checking requests.

Variable

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

ApplicationLoadBalancerSpec

Field Description
target_group_spec ApplicationTargetGroupSpec
Required. Basic properties of the Application Load Balancer target group attributed to the instance group.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

ApplicationTargetGroupSpec

Field Description
name string
Name of the target group.
description string
Description of the target group.
labels map<string,string>
Resource labels as key:value pairs.

ApplicationLoadBalancerState

Field Description
target_group_id string
ID of the Application Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

AutoHealingPolicy

Field Description
auto_healing_action enum AutoHealingAction
Instance Groups performs auto_healing_action 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

List

Retrieves the list of InstanceGroup resources in the specified folder.

rpc List (ListInstanceGroupsRequest) returns (ListInstanceGroupsResponse)

ListInstanceGroupsRequest

Field Description
folder_id string
Required. ID of the folder to list instance groups in. To get the folder ID, use a yandex.cloud.resourcemanager.v1.FolderService.List request.
page_size int64
The maximum number of results per page to return. If the number of available results is larger than page_size, the service returns a ListInstanceGroupsResponse.next_page_token that can be used to get the next page of results in subsequent list requests. The maximum value is 1000.
page_token string
Page token. To get the next page of results, set page_token to the ListInstanceGroupsResponse.next_page_token returned by a previous list request. The maximum string length in characters is 1000.
filter string
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 enum InstanceGroupView
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.

ListInstanceGroupsResponse

Field Description
instance_groups[] InstanceGroup
Lists instance groups for the specified folder.
next_page_token string
This token allows you to get the next page of results for list requests. If the number of results is larger than ListInstanceGroupsRequest.page_size, use next_page_token as the value for the ListInstanceGroupsRequest.page_token query parameter in the next list request. Each subsequent list request will have its own next_page_token to continue paging through the results.

InstanceGroup

Field Description
id string
ID of the instance group.
folder_id string
ID of the folder that the instance group belongs to.
created_at google.protobuf.Timestamp
Creation timestamp in RFC3339 text format.
name string
Name of the instance group. The name is unique within the folder.
description string
Description of the instance group.
labels map<string,string>
Resource labels as key:value pairs.
instance_template InstanceTemplate
Instance template for creating the instance group. For more information, see Instance Templates.
scale_policy ScalePolicy
Scaling policy of the instance group.
deploy_policy DeployPolicy
Deployment policy of the instance group.
allocation_policy AllocationPolicy
Allocation policy of the instance group by zones and regions.
load_balancer_state LoadBalancerState
Status of the Network Load Balancer target group attributed to the instance group.
managed_instances_state ManagedInstancesState
States of instances for this instance group.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
status enum Status
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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.ResumeProcesses. The group status will change to ACTIVE.
variables[] Variable
deletion_protection bool
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.
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
application_load_balancer_state ApplicationLoadBalancerState
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.
auto_healing_policy AutoHealingPolicy
AutoHealingPolicy policy of the instance group.

InstanceTemplate

Field Description
description string
Description of the instance template. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 128. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
platform_id 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.
resources_spec ResourcesSpec
Required. Computing resources of the instance such as the amount of memory and number of cores.
metadata map<string,string>
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 maximum string length in characters for each value is 262144. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_0-9a-z]*.
boot_disk_spec AttachedDiskSpec
Required. Boot disk specification that will be attached to the instance.
secondary_disk_specs[] AttachedDiskSpec
Array of secondary disks that will be attached to the instance. The maximum number of elements is 3.
network_interface_specs[] NetworkInterfaceSpec
Required. Array of network interfaces that will be attached to the instance.
scheduling_policy SchedulingPolicy
Scheduling policy for the instance.
service_account_id string
Service account ID for the instance.
network_settings NetworkSettings
Network settings for the instance.
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.
hostname string
Host name for the instance. This field is used to generate the yandex.cloud.compute.v1.Instance.fqdn value. The host name must be unique within the network and region. If not specified, the host name will be equal to yandex.cloud.compute.v1.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.
placement_policy PlacementPolicy
Placement Group
filesystem_specs[] AttachedFilesystemSpec
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.
metadata_options MetadataOptions
Metadata options for the instance

ResourcesSpec

Field Description
memory int64
The amount of memory available to the instance, specified in bytes. The maximum value is 824633720832.
cores int64
The number of cores available to the instance. Value must be equal to 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,80.
core_fraction 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 equal to 0,5,20,50,100.
gpus int64
The number of GPUs available to the instance. Value must be equal to 0,1,2,4.

AttachedDiskSpec

Field Description
mode enum Mode
Required. Access mode to the Disk resource.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
device_name 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}.
disk_spec DiskSpec
Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
disk_id 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._{}]*.
name string
When set can be later used to change DiskSpec of actual disk. The maximum string length in characters is 128.

DiskSpec

Field Description
description string
Description of the disk. The maximum string length in characters is 256.
type_id string
Required. ID of the disk type.
size int64
Size of the disk, specified in bytes. Acceptable values are 4194304 to 28587302322176, inclusive.
source_oneof oneof: image_id or snapshot_id
  image_id string
ID of the image that will be used for disk creation. The maximum string length in characters is 50.
  snapshot_id string
ID of the snapshot that will be used for disk creation. The maximum string length in characters is 50.
preserve_after_instance_delete bool
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.

NetworkInterfaceSpec

Field Description
network_id string
ID of the network.
subnet_ids[] string
IDs of the subnets.
primary_v4_address_spec PrimaryAddressSpec
Primary IPv4 address that is assigned to the instance for this network interface.
primary_v6_address_spec PrimaryAddressSpec
Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.
security_group_ids[] string
IDs of security groups.

PrimaryAddressSpec

Field Description
one_to_one_nat_spec OneToOneNatSpec
An external IP address configuration. If not specified, then this managed instance will have no external internet access.
dns_record_specs[] DnsRecordSpec
Internal DNS configuration
address string
Optional. Manual set static internal IP. To set use variables.

OneToOneNatSpec

Field Description
ip_version enum IpVersion
IP version for the public IP address.
  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
address string
Manual set static public IP. To set use variables. (optional)
dns_record_specs[] DnsRecordSpec
External DNS configuration

DnsRecordSpec

Field Description
fqdn string
Required. FQDN (required)
dns_zone_id string
DNS zone id (optional, if not set, private zone used)
ttl int64
DNS record ttl, values in 0-86400 (optional) Acceptable values are 0 to 86400, inclusive.
ptr bool
When set to true, also create PTR DNS record (optional)

SchedulingPolicy

Field Description
preemptible bool
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.

NetworkSettings

Field Description
type enum Type
Type of instance network.

PlacementPolicy

Field Description
placement_group_id string
Identifier of placement group
host_affinity_rules[] HostAffinityRule
List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

HostAffinityRule

Field Description
key string
Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'
op enum Operator
Include or exclude action
values[] string
Affinity value or host ID or host group ID

AttachedFilesystemSpec

Field Description
mode enum Mode
Mode of access to the filesystem that should be attached.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.
device_name 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}.
filesystem_id 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._{}]*.

MetadataOptions

Field Description
gce_http_endpoint enum MetadataOption
Enabled access to GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_endpoint enum MetadataOption
Enabled access to AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
gce_http_token enum MetadataOption
Enabled access to IAM credentials with GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_token enum MetadataOption
Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

ScalePolicy

Field Description
scale_type oneof: fixed_scale or auto_scale
  fixed_scale FixedScale
Manual scaling policy of the instance group.
  auto_scale AutoScale
Automatic scaling policy of the instance group.
test_auto_scale AutoScale
Test spec for automatic scaling policy of the instance group.

AutoScale

Field Description
min_zone_size int64
Lower limit for instance count in each zone. Acceptable values are 0 to 100, inclusive.
max_size int64
Upper limit for total instance count (across all zones). 0 means maximum limit = 100. Acceptable values are 0 to 100, inclusive.
measurement_duration google.protobuf.Duration
Time in seconds allotted for averaging metrics. 1 minute by default. Acceptable values are 1m to 10m, inclusive.
warmup_duration google.protobuf.Duration
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 10m.
stabilization_duration google.protobuf.Duration
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 1m to 30m, inclusive.
initial_size int64
Target group size. The minimum value is 1.
cpu_utilization_rule CpuUtilizationRule
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 (custom_rules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
custom_rules[] CustomRule
Defines an autoscaling rule based on a custom metric from Monitoring.
If more than one rule is specified, e.g. CPU utilization (cpu_utilization_rule) 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.
auto_scale_type enum AutoScaleType
Autoscaling type.
  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.

CpuUtilizationRule

Field Description
utilization_target double
Target CPU utilization level. Instance Groups maintains this level for each availability zone. Acceptable values are 10 to 100, inclusive.

CustomRule

Field Description
rule_type enum RuleType
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.
metric_type enum MetricType
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 AutoScale.measurement_duration 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 AutoScale.measurement_duration field.
metric_name 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}.
labels map<string,string>
Labels of custom metric in Monitoring that should be used for scaling. Each value must match the regular expression [a-zA-Z0-9./@_][0-9a-zA-Z./@_,:;()\\[\\]<>-]{0,198}. Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$.
target double
Target value for the custom metric. Instance Groups maintains this level for each availability zone. Value must be greater than 0.
folder_id string
Folder id of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 50.
service string
Service of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 200.

FixedScale

Field Description
size int64
Number of instances in the instance group. Acceptable values are 1 to 100, inclusive.

DeployPolicy

Field Description
max_unavailable 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 max_expansion is not specified or set to zero, max_unavailable must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
max_deleting 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.
max_creating 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.
max_expansion int64
The maximum number of instances that can be temporarily allocated above the group's target size during the update process. If max_unavailable is not specified or set to zero, max_expansion must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
startup_duration google.protobuf.Duration
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 yandex.cloud.compute.v1.instancegroup.ManagedInstance.Status for more information. Acceptable values are 0m to 1h, inclusive.
strategy enum Strategy
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.
minimal_action enum MinimalAction
If instance update requires a less disruptive action than minimal_action, Instance Groups performs minimal_action 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

Field Description
zones[] Zone
List of availability zones. The minimum number of elements is 1.

Zone

Field Description
zone_id string
Required. ID of the availability zone where the instance resides.
instance_tags_pool[] 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

Field Description
target_group_id string
ID of the Network Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

ManagedInstancesState

Field Description
target_size int64
Target number of instances for this instance group.
running_actual_count int64
The number of running instances that match the current instance template. For more information, see ManagedInstance.Status.RUNNING_ACTUAL.
running_outdated_count int64
The number of running instances that does not match the current instance template. For more information, see ManagedInstance.Status.RUNNING_OUTDATED.
processing_count int64
The number of instances in flight (for example, updating, starting, deleting). For more information, see ManagedInstance.Status.

Statuses

Field Description
creating int64
Instance is being created.
starting int64
Instance is being started.
opening int64
Instance is being opened to receive traffic.
warming int64
Instance is being warmed.
running int64
Instance is running normally.
closing int64
Instance is being closed to traffic.
stopping int64
Instance is being stopped.
updating int64
Instance is being updated.
deleting int64
Instance is being deleted.
failed int64
Instance failed and needs to be recreated.

LoadBalancerSpec

Field Description
target_group_spec TargetGroupSpec
Specification of the target group that the instance group will be added to. For more information, see Target groups and resources.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

TargetGroupSpec

Field Description
name string
Name of the target group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the target group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.

HealthChecksSpec

Field Description
health_check_specs[] HealthCheckSpec
Health checking specification. For more information, see Health check. The minimum number of elements is 1.
max_checking_health_duration google.protobuf.Duration
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 1s.

HealthCheckSpec

Field Description
interval google.protobuf.Duration
The interval between health checks. The default is 2 seconds. Acceptable values are 1s to 300s, inclusive.
timeout google.protobuf.Duration
Timeout for the managed instance to return a response for the health check. The default is 1 second. Acceptable values are 1s to 60s, inclusive.
unhealthy_threshold int64
The number of failed health checks for the managed instance to be considered unhealthy. The default (0) is 2. Value must be equal to 0,2,3,4,5,6,7,8,9,10.
healthy_threshold 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 equal to 0,2,3,4,5,6,7,8,9,10.
health_check_options oneof: tcp_options or http_options
  tcp_options TcpOptions
Configuration options for a TCP health check.
  http_options HttpOptions
Configuration options for an HTTP health check.

TcpOptions

Field Description
port int64
Port to use for TCP health checks. Acceptable values are 1 to 65535, inclusive.

HttpOptions

Field Description
port int64
Port to use for HTTP health checks. Acceptable values are 1 to 65535, inclusive.
path string
URL path to set for health checking requests.

Variable

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

ApplicationLoadBalancerSpec

Field Description
target_group_spec ApplicationTargetGroupSpec
Required. Basic properties of the Application Load Balancer target group attributed to the instance group.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

ApplicationTargetGroupSpec

Field Description
name string
Name of the target group.
description string
Description of the target group.
labels map<string,string>
Resource labels as key:value pairs.

ApplicationLoadBalancerState

Field Description
target_group_id string
ID of the Application Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

AutoHealingPolicy

Field Description
auto_healing_action enum AutoHealingAction
Instance Groups performs auto_healing_action 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

Create

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

rpc Create (CreateInstanceGroupRequest) returns (operation.Operation)

Metadata and response of Operation:

    Operation.metadata:CreateInstanceGroupMetadata

    Operation.response:InstanceGroup

CreateInstanceGroupRequest

Field Description
folder_id string
Required. ID of the folder to create an instance group in. To get the folder ID, use a yandex.cloud.resourcemanager.v1.FolderService.List request.
name string
Name of the instance group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the instance group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
instance_template InstanceTemplate
Required. Instance template that the instance group belongs to.
scale_policy ScalePolicy
Required. Scaling policy of the instance group.
deploy_policy DeployPolicy
Required. Deployment policy of the instance group.
allocation_policy AllocationPolicy
Required. Allocation policy of the instance group by zones and regions.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
If specified, a Network Load Balancer target group containing all instances from the instance group will be created and attributed to the instance group.
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
variables[] Variable
deletion_protection bool
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.
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
If specified, an Application Load Balancer target group containing all instances from the instance group will be created and attributed to the instance group.

InstanceTemplate

Field Description
description string
Description of the instance template. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 128. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
platform_id 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.
resources_spec ResourcesSpec
Required. Computing resources of the instance such as the amount of memory and number of cores.
metadata map<string,string>
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 maximum string length in characters for each value is 262144. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_0-9a-z]*.
boot_disk_spec AttachedDiskSpec
Required. Boot disk specification that will be attached to the instance.
secondary_disk_specs[] AttachedDiskSpec
Array of secondary disks that will be attached to the instance. The maximum number of elements is 3.
network_interface_specs[] NetworkInterfaceSpec
Required. Array of network interfaces that will be attached to the instance.
scheduling_policy SchedulingPolicy
Scheduling policy for the instance.
service_account_id string
Service account ID for the instance.
network_settings NetworkSettings
Network settings for the instance.
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.
hostname string
Host name for the instance. This field is used to generate the yandex.cloud.compute.v1.Instance.fqdn value. The host name must be unique within the network and region. If not specified, the host name will be equal to yandex.cloud.compute.v1.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.
placement_policy PlacementPolicy
Placement Group
filesystem_specs[] AttachedFilesystemSpec
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.
metadata_options MetadataOptions
Metadata options for the instance

ResourcesSpec

Field Description
memory int64
The amount of memory available to the instance, specified in bytes. The maximum value is 824633720832.
cores int64
The number of cores available to the instance. Value must be equal to 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,80.
core_fraction 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 equal to 0,5,20,50,100.
gpus int64
The number of GPUs available to the instance. Value must be equal to 0,1,2,4.

AttachedDiskSpec

Field Description
mode enum Mode
Required. Access mode to the Disk resource.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
device_name 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}.
disk_spec DiskSpec
Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
disk_id 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._{}]*.
name string
When set can be later used to change DiskSpec of actual disk. The maximum string length in characters is 128.

DiskSpec

Field Description
description string
Description of the disk. The maximum string length in characters is 256.
type_id string
Required. ID of the disk type.
size int64
Size of the disk, specified in bytes. Acceptable values are 4194304 to 28587302322176, inclusive.
source_oneof oneof: image_id or snapshot_id
  image_id string
ID of the image that will be used for disk creation. The maximum string length in characters is 50.
  snapshot_id string
ID of the snapshot that will be used for disk creation. The maximum string length in characters is 50.
preserve_after_instance_delete bool
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.

NetworkInterfaceSpec

Field Description
network_id string
ID of the network.
subnet_ids[] string
IDs of the subnets.
primary_v4_address_spec PrimaryAddressSpec
Primary IPv4 address that is assigned to the instance for this network interface.
primary_v6_address_spec PrimaryAddressSpec
Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.
security_group_ids[] string
IDs of security groups.

PrimaryAddressSpec

Field Description
one_to_one_nat_spec OneToOneNatSpec
An external IP address configuration. If not specified, then this managed instance will have no external internet access.
dns_record_specs[] DnsRecordSpec
Internal DNS configuration
address string
Optional. Manual set static internal IP. To set use variables.

OneToOneNatSpec

Field Description
ip_version enum IpVersion
IP version for the public IP address.
  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
address string
Manual set static public IP. To set use variables. (optional)
dns_record_specs[] DnsRecordSpec
External DNS configuration

DnsRecordSpec

Field Description
fqdn string
Required. FQDN (required)
dns_zone_id string
DNS zone id (optional, if not set, private zone used)
ttl int64
DNS record ttl, values in 0-86400 (optional) Acceptable values are 0 to 86400, inclusive.
ptr bool
When set to true, also create PTR DNS record (optional)

SchedulingPolicy

Field Description
preemptible bool
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.

NetworkSettings

Field Description
type enum Type
Type of instance network.

PlacementPolicy

Field Description
placement_group_id string
Identifier of placement group
host_affinity_rules[] HostAffinityRule
List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

HostAffinityRule

Field Description
key string
Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'
op enum Operator
Include or exclude action
values[] string
Affinity value or host ID or host group ID

AttachedFilesystemSpec

Field Description
mode enum Mode
Mode of access to the filesystem that should be attached.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.
device_name 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}.
filesystem_id 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._{}]*.

MetadataOptions

Field Description
gce_http_endpoint enum MetadataOption
Enabled access to GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_endpoint enum MetadataOption
Enabled access to AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
gce_http_token enum MetadataOption
Enabled access to IAM credentials with GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_token enum MetadataOption
Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

ScalePolicy

Field Description
scale_type oneof: fixed_scale or auto_scale
  fixed_scale FixedScale
Manual scaling policy of the instance group.
  auto_scale AutoScale
Automatic scaling policy of the instance group.
test_auto_scale AutoScale
Test spec for automatic scaling policy of the instance group.

AutoScale

Field Description
min_zone_size int64
Lower limit for instance count in each zone. Acceptable values are 0 to 100, inclusive.
max_size int64
Upper limit for total instance count (across all zones). 0 means maximum limit = 100. Acceptable values are 0 to 100, inclusive.
measurement_duration google.protobuf.Duration
Time in seconds allotted for averaging metrics. 1 minute by default. Acceptable values are 1m to 10m, inclusive.
warmup_duration google.protobuf.Duration
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 10m.
stabilization_duration google.protobuf.Duration
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 1m to 30m, inclusive.
initial_size int64
Target group size. The minimum value is 1.
cpu_utilization_rule CpuUtilizationRule
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 (custom_rules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
custom_rules[] CustomRule
Defines an autoscaling rule based on a custom metric from Monitoring.
If more than one rule is specified, e.g. CPU utilization (cpu_utilization_rule) 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.
auto_scale_type enum AutoScaleType
Autoscaling type.
  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.

CpuUtilizationRule

Field Description
utilization_target double
Target CPU utilization level. Instance Groups maintains this level for each availability zone. Acceptable values are 10 to 100, inclusive.

CustomRule

Field Description
rule_type enum RuleType
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.
metric_type enum MetricType
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 AutoScale.measurement_duration 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 AutoScale.measurement_duration field.
metric_name 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}.
labels map<string,string>
Labels of custom metric in Monitoring that should be used for scaling. Each value must match the regular expression [a-zA-Z0-9./@_][0-9a-zA-Z./@_,:;()\\[\\]<>-]{0,198}. Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$.
target double
Target value for the custom metric. Instance Groups maintains this level for each availability zone. Value must be greater than 0.
folder_id string
Folder id of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 50.
service string
Service of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 200.

FixedScale

Field Description
size int64
Number of instances in the instance group. Acceptable values are 1 to 100, inclusive.

DeployPolicy

Field Description
max_unavailable 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 max_expansion is not specified or set to zero, max_unavailable must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
max_deleting 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.
max_creating 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.
max_expansion int64
The maximum number of instances that can be temporarily allocated above the group's target size during the update process. If max_unavailable is not specified or set to zero, max_expansion must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
startup_duration google.protobuf.Duration
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 yandex.cloud.compute.v1.instancegroup.ManagedInstance.Status for more information. Acceptable values are 0m to 1h, inclusive.
strategy enum Strategy
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.
minimal_action enum MinimalAction
If instance update requires a less disruptive action than minimal_action, Instance Groups performs minimal_action 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

Field Description
zones[] Zone
List of availability zones. The minimum number of elements is 1.

Zone

Field Description
zone_id string
Required. ID of the availability zone where the instance resides.
instance_tags_pool[] 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.

LoadBalancerSpec

Field Description
target_group_spec TargetGroupSpec
Specification of the target group that the instance group will be added to. For more information, see Target groups and resources.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

TargetGroupSpec

Field Description
name string
Name of the target group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the target group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.

HealthChecksSpec

Field Description
health_check_specs[] HealthCheckSpec
Health checking specification. For more information, see Health check. The minimum number of elements is 1.
max_checking_health_duration google.protobuf.Duration
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 1s.

HealthCheckSpec

Field Description
interval google.protobuf.Duration
The interval between health checks. The default is 2 seconds. Acceptable values are 1s to 300s, inclusive.
timeout google.protobuf.Duration
Timeout for the managed instance to return a response for the health check. The default is 1 second. Acceptable values are 1s to 60s, inclusive.
unhealthy_threshold int64
The number of failed health checks for the managed instance to be considered unhealthy. The default (0) is 2. Value must be equal to 0,2,3,4,5,6,7,8,9,10.
healthy_threshold 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 equal to 0,2,3,4,5,6,7,8,9,10.
health_check_options oneof: tcp_options or http_options
  tcp_options TcpOptions
Configuration options for a TCP health check.
  http_options HttpOptions
Configuration options for an HTTP health check.

TcpOptions

Field Description
port int64
Port to use for TCP health checks. Acceptable values are 1 to 65535, inclusive.

HttpOptions

Field Description
port int64
Port to use for HTTP health checks. Acceptable values are 1 to 65535, inclusive.
path string
URL path to set for health checking requests.

Variable

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

ApplicationLoadBalancerSpec

Field Description
target_group_spec ApplicationTargetGroupSpec
Required. Basic properties of the Application Load Balancer target group attributed to the instance group.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

ApplicationTargetGroupSpec

Field Description
name string
Name of the target group.
description string
Description of the target group.
labels map<string,string>
Resource labels as key:value pairs.

Operation

Field Description
id string
ID of the operation.
description string
Description of the operation. 0-256 characters long.
created_at google.protobuf.Timestamp
Creation timestamp.
created_by string
ID of the user or service account who initiated the operation.
modified_at google.protobuf.Timestamp
The time when the Operation resource was last modified.
done bool
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 google.protobuf.Any<CreateInstanceGroupMetadata>
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.
result oneof: error or response
The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true, exactly one of error or response is set.
  error google.rpc.Status
The error result of the operation in case of failure or cancellation.
  response google.protobuf.Any<InstanceGroup>
if operation finished successfully.

CreateInstanceGroupMetadata

Field Description
instance_group_id string
ID of the instance group that is being created. The maximum string length in characters is 50.

InstanceGroup

Field Description
id string
ID of the instance group.
folder_id string
ID of the folder that the instance group belongs to.
created_at google.protobuf.Timestamp
Creation timestamp in RFC3339 text format.
name string
Name of the instance group. The name is unique within the folder.
description string
Description of the instance group.
labels map<string,string>
Resource labels as key:value pairs.
instance_template InstanceTemplate
Instance template for creating the instance group. For more information, see Instance Templates.
scale_policy ScalePolicy
Scaling policy of the instance group.
deploy_policy DeployPolicy
Deployment policy of the instance group.
allocation_policy AllocationPolicy
Allocation policy of the instance group by zones and regions.
load_balancer_state LoadBalancerState
Status of the Network Load Balancer target group attributed to the instance group.
managed_instances_state ManagedInstancesState
States of instances for this instance group.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
status enum Status
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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.ResumeProcesses. The group status will change to ACTIVE.
variables[] Variable
deletion_protection bool
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.
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
application_load_balancer_state ApplicationLoadBalancerState
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.
auto_healing_policy AutoHealingPolicy
AutoHealingPolicy policy of the instance group.

LoadBalancerState

Field Description
target_group_id string
ID of the Network Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

ManagedInstancesState

Field Description
target_size int64
Target number of instances for this instance group.
running_actual_count int64
The number of running instances that match the current instance template. For more information, see ManagedInstance.Status.RUNNING_ACTUAL.
running_outdated_count int64
The number of running instances that does not match the current instance template. For more information, see ManagedInstance.Status.RUNNING_OUTDATED.
processing_count int64
The number of instances in flight (for example, updating, starting, deleting). For more information, see ManagedInstance.Status.

Statuses

Field Description
creating int64
Instance is being created.
starting int64
Instance is being started.
opening int64
Instance is being opened to receive traffic.
warming int64
Instance is being warmed.
running int64
Instance is running normally.
closing int64
Instance is being closed to traffic.
stopping int64
Instance is being stopped.
updating int64
Instance is being updated.
deleting int64
Instance is being deleted.
failed int64
Instance failed and needs to be recreated.

ApplicationLoadBalancerState

Field Description
target_group_id string
ID of the Application Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

AutoHealingPolicy

Field Description
auto_healing_action enum AutoHealingAction
Instance Groups performs auto_healing_action 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

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.

rpc CreateFromYaml (CreateInstanceGroupFromYamlRequest) returns (operation.Operation)

Metadata and response of Operation:

    Operation.metadata:CreateInstanceGroupMetadata

    Operation.response:InstanceGroup

CreateInstanceGroupFromYamlRequest

Field Description
folder_id string
Required. ID of the folder to create an instance group in. To get the folder ID, use a yandex.cloud.resourcemanager.v1.FolderService.List request.
instance_group_yaml string
Required. InstanceGroupService.Create request in YAML format. The maximum string length in characters is 1048576.

Operation

Field Description
id string
ID of the operation.
description string
Description of the operation. 0-256 characters long.
created_at google.protobuf.Timestamp
Creation timestamp.
created_by string
ID of the user or service account who initiated the operation.
modified_at google.protobuf.Timestamp
The time when the Operation resource was last modified.
done bool
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 google.protobuf.Any<CreateInstanceGroupMetadata>
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.
result oneof: error or response
The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true, exactly one of error or response is set.
  error google.rpc.Status
The error result of the operation in case of failure or cancellation.
  response google.protobuf.Any<InstanceGroup>
if operation finished successfully.

CreateInstanceGroupMetadata

Field Description
instance_group_id string
ID of the instance group that is being created. The maximum string length in characters is 50.

InstanceGroup

Field Description
id string
ID of the instance group.
folder_id string
ID of the folder that the instance group belongs to.
created_at google.protobuf.Timestamp
Creation timestamp in RFC3339 text format.
name string
Name of the instance group. The name is unique within the folder.
description string
Description of the instance group.
labels map<string,string>
Resource labels as key:value pairs.
instance_template InstanceTemplate
Instance template for creating the instance group. For more information, see Instance Templates.
scale_policy ScalePolicy
Scaling policy of the instance group.
deploy_policy DeployPolicy
Deployment policy of the instance group.
allocation_policy AllocationPolicy
Allocation policy of the instance group by zones and regions.
load_balancer_state LoadBalancerState
Status of the Network Load Balancer target group attributed to the instance group.
managed_instances_state ManagedInstancesState
States of instances for this instance group.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
status enum Status
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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.ResumeProcesses. The group status will change to ACTIVE.
variables[] Variable
deletion_protection bool
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.
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
application_load_balancer_state ApplicationLoadBalancerState
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.
auto_healing_policy AutoHealingPolicy
AutoHealingPolicy policy of the instance group.

InstanceTemplate

Field Description
description string
Description of the instance template. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 128. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
platform_id 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.
resources_spec ResourcesSpec
Required. Computing resources of the instance such as the amount of memory and number of cores.
metadata map<string,string>
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 maximum string length in characters for each value is 262144. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_0-9a-z]*.
boot_disk_spec AttachedDiskSpec
Required. Boot disk specification that will be attached to the instance.
secondary_disk_specs[] AttachedDiskSpec
Array of secondary disks that will be attached to the instance. The maximum number of elements is 3.
network_interface_specs[] NetworkInterfaceSpec
Required. Array of network interfaces that will be attached to the instance.
scheduling_policy SchedulingPolicy
Scheduling policy for the instance.
service_account_id string
Service account ID for the instance.
network_settings NetworkSettings
Network settings for the instance.
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.
hostname string
Host name for the instance. This field is used to generate the yandex.cloud.compute.v1.Instance.fqdn value. The host name must be unique within the network and region. If not specified, the host name will be equal to yandex.cloud.compute.v1.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.
placement_policy PlacementPolicy
Placement Group
filesystem_specs[] AttachedFilesystemSpec
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.
metadata_options MetadataOptions
Metadata options for the instance

ResourcesSpec

Field Description
memory int64
The amount of memory available to the instance, specified in bytes. The maximum value is 824633720832.
cores int64
The number of cores available to the instance. Value must be equal to 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,80.
core_fraction 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 equal to 0,5,20,50,100.
gpus int64
The number of GPUs available to the instance. Value must be equal to 0,1,2,4.

AttachedDiskSpec

Field Description
mode enum Mode
Required. Access mode to the Disk resource.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
device_name 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}.
disk_spec DiskSpec
Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
disk_id 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._{}]*.
name string
When set can be later used to change DiskSpec of actual disk. The maximum string length in characters is 128.

DiskSpec

Field Description
description string
Description of the disk. The maximum string length in characters is 256.
type_id string
Required. ID of the disk type.
size int64
Size of the disk, specified in bytes. Acceptable values are 4194304 to 28587302322176, inclusive.
source_oneof oneof: image_id or snapshot_id
  image_id string
ID of the image that will be used for disk creation. The maximum string length in characters is 50.
  snapshot_id string
ID of the snapshot that will be used for disk creation. The maximum string length in characters is 50.
preserve_after_instance_delete bool
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.

NetworkInterfaceSpec

Field Description
network_id string
ID of the network.
subnet_ids[] string
IDs of the subnets.
primary_v4_address_spec PrimaryAddressSpec
Primary IPv4 address that is assigned to the instance for this network interface.
primary_v6_address_spec PrimaryAddressSpec
Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.
security_group_ids[] string
IDs of security groups.

PrimaryAddressSpec

Field Description
one_to_one_nat_spec OneToOneNatSpec
An external IP address configuration. If not specified, then this managed instance will have no external internet access.
dns_record_specs[] DnsRecordSpec
Internal DNS configuration
address string
Optional. Manual set static internal IP. To set use variables.

OneToOneNatSpec

Field Description
ip_version enum IpVersion
IP version for the public IP address.
  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
address string
Manual set static public IP. To set use variables. (optional)
dns_record_specs[] DnsRecordSpec
External DNS configuration

DnsRecordSpec

Field Description
fqdn string
Required. FQDN (required)
dns_zone_id string
DNS zone id (optional, if not set, private zone used)
ttl int64
DNS record ttl, values in 0-86400 (optional) Acceptable values are 0 to 86400, inclusive.
ptr bool
When set to true, also create PTR DNS record (optional)

SchedulingPolicy

Field Description
preemptible bool
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.

NetworkSettings

Field Description
type enum Type
Type of instance network.

PlacementPolicy

Field Description
placement_group_id string
Identifier of placement group
host_affinity_rules[] HostAffinityRule
List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

HostAffinityRule

Field Description
key string
Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'
op enum Operator
Include or exclude action
values[] string
Affinity value or host ID or host group ID

AttachedFilesystemSpec

Field Description
mode enum Mode
Mode of access to the filesystem that should be attached.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.
device_name 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}.
filesystem_id 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._{}]*.

MetadataOptions

Field Description
gce_http_endpoint enum MetadataOption
Enabled access to GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_endpoint enum MetadataOption
Enabled access to AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
gce_http_token enum MetadataOption
Enabled access to IAM credentials with GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_token enum MetadataOption
Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

ScalePolicy

Field Description
scale_type oneof: fixed_scale or auto_scale
  fixed_scale FixedScale
Manual scaling policy of the instance group.
  auto_scale AutoScale
Automatic scaling policy of the instance group.
test_auto_scale AutoScale
Test spec for automatic scaling policy of the instance group.

AutoScale

Field Description
min_zone_size int64
Lower limit for instance count in each zone. Acceptable values are 0 to 100, inclusive.
max_size int64
Upper limit for total instance count (across all zones). 0 means maximum limit = 100. Acceptable values are 0 to 100, inclusive.
measurement_duration google.protobuf.Duration
Time in seconds allotted for averaging metrics. 1 minute by default. Acceptable values are 1m to 10m, inclusive.
warmup_duration google.protobuf.Duration
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 10m.
stabilization_duration google.protobuf.Duration
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 1m to 30m, inclusive.
initial_size int64
Target group size. The minimum value is 1.
cpu_utilization_rule CpuUtilizationRule
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 (custom_rules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
custom_rules[] CustomRule
Defines an autoscaling rule based on a custom metric from Monitoring.
If more than one rule is specified, e.g. CPU utilization (cpu_utilization_rule) 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.
auto_scale_type enum AutoScaleType
Autoscaling type.
  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.

CpuUtilizationRule

Field Description
utilization_target double
Target CPU utilization level. Instance Groups maintains this level for each availability zone. Acceptable values are 10 to 100, inclusive.

CustomRule

Field Description
rule_type enum RuleType
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.
metric_type enum MetricType
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 AutoScale.measurement_duration 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 AutoScale.measurement_duration field.
metric_name 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}.
labels map<string,string>
Labels of custom metric in Monitoring that should be used for scaling. Each value must match the regular expression [a-zA-Z0-9./@_][0-9a-zA-Z./@_,:;()\\[\\]<>-]{0,198}. Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$.
target double
Target value for the custom metric. Instance Groups maintains this level for each availability zone. Value must be greater than 0.
folder_id string
Folder id of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 50.
service string
Service of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 200.

FixedScale

Field Description
size int64
Number of instances in the instance group. Acceptable values are 1 to 100, inclusive.

DeployPolicy

Field Description
max_unavailable 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 max_expansion is not specified or set to zero, max_unavailable must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
max_deleting 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.
max_creating 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.
max_expansion int64
The maximum number of instances that can be temporarily allocated above the group's target size during the update process. If max_unavailable is not specified or set to zero, max_expansion must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
startup_duration google.protobuf.Duration
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 yandex.cloud.compute.v1.instancegroup.ManagedInstance.Status for more information. Acceptable values are 0m to 1h, inclusive.
strategy enum Strategy
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.
minimal_action enum MinimalAction
If instance update requires a less disruptive action than minimal_action, Instance Groups performs minimal_action 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

Field Description
zones[] Zone
List of availability zones. The minimum number of elements is 1.

Zone

Field Description
zone_id string
Required. ID of the availability zone where the instance resides.
instance_tags_pool[] 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

Field Description
target_group_id string
ID of the Network Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

ManagedInstancesState

Field Description
target_size int64
Target number of instances for this instance group.
running_actual_count int64
The number of running instances that match the current instance template. For more information, see ManagedInstance.Status.RUNNING_ACTUAL.
running_outdated_count int64
The number of running instances that does not match the current instance template. For more information, see ManagedInstance.Status.RUNNING_OUTDATED.
processing_count int64
The number of instances in flight (for example, updating, starting, deleting). For more information, see ManagedInstance.Status.

Statuses

Field Description
creating int64
Instance is being created.
starting int64
Instance is being started.
opening int64
Instance is being opened to receive traffic.
warming int64
Instance is being warmed.
running int64
Instance is running normally.
closing int64
Instance is being closed to traffic.
stopping int64
Instance is being stopped.
updating int64
Instance is being updated.
deleting int64
Instance is being deleted.
failed int64
Instance failed and needs to be recreated.

LoadBalancerSpec

Field Description
target_group_spec TargetGroupSpec
Specification of the target group that the instance group will be added to. For more information, see Target groups and resources.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

TargetGroupSpec

Field Description
name string
Name of the target group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the target group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.

HealthChecksSpec

Field Description
health_check_specs[] HealthCheckSpec
Health checking specification. For more information, see Health check. The minimum number of elements is 1.
max_checking_health_duration google.protobuf.Duration
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 1s.

HealthCheckSpec

Field Description
interval google.protobuf.Duration
The interval between health checks. The default is 2 seconds. Acceptable values are 1s to 300s, inclusive.
timeout google.protobuf.Duration
Timeout for the managed instance to return a response for the health check. The default is 1 second. Acceptable values are 1s to 60s, inclusive.
unhealthy_threshold int64
The number of failed health checks for the managed instance to be considered unhealthy. The default (0) is 2. Value must be equal to 0,2,3,4,5,6,7,8,9,10.
healthy_threshold 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 equal to 0,2,3,4,5,6,7,8,9,10.
health_check_options oneof: tcp_options or http_options
  tcp_options TcpOptions
Configuration options for a TCP health check.
  http_options HttpOptions
Configuration options for an HTTP health check.

TcpOptions

Field Description
port int64
Port to use for TCP health checks. Acceptable values are 1 to 65535, inclusive.

HttpOptions

Field Description
port int64
Port to use for HTTP health checks. Acceptable values are 1 to 65535, inclusive.
path string
URL path to set for health checking requests.

Variable

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

ApplicationLoadBalancerSpec

Field Description
target_group_spec ApplicationTargetGroupSpec
Required. Basic properties of the Application Load Balancer target group attributed to the instance group.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

ApplicationTargetGroupSpec

Field Description
name string
Name of the target group.
description string
Description of the target group.
labels map<string,string>
Resource labels as key:value pairs.

ApplicationLoadBalancerState

Field Description
target_group_id string
ID of the Application Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

AutoHealingPolicy

Field Description
auto_healing_action enum AutoHealingAction
Instance Groups performs auto_healing_action 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

Update

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

rpc Update (UpdateInstanceGroupRequest) returns (operation.Operation)

Metadata and response of Operation:

    Operation.metadata:UpdateInstanceGroupMetadata

    Operation.response:InstanceGroup

UpdateInstanceGroupRequest

Field Description
instance_group_id string
Required. ID of the instance group to update. To get the instance group ID, use a InstanceGroupService.List request. The maximum string length in characters is 50.
update_mask google.protobuf.FieldMask
Field mask that specifies which fields of the InstanceGroup resource are going to be updated.
name string
Name of the instance group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the instance group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs.
The existing set of labels is completely replaced by the provided set. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
instance_template InstanceTemplate
Required. Instance template that the instance group belongs to.
scale_policy ScalePolicy
Required. Scaling policy of the instance group.
deploy_policy DeployPolicy
Required. Deployment policy of the instance group.
allocation_policy AllocationPolicy
Required. Allocation policy of the instance group by zones and regions.
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
variables[] Variable
deletion_protection bool
Flag that inhibits deletion of the instance group
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).

InstanceTemplate

Field Description
description string
Description of the instance template. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 128. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
platform_id 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.
resources_spec ResourcesSpec
Required. Computing resources of the instance such as the amount of memory and number of cores.
metadata map<string,string>
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 maximum string length in characters for each value is 262144. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_0-9a-z]*.
boot_disk_spec AttachedDiskSpec
Required. Boot disk specification that will be attached to the instance.
secondary_disk_specs[] AttachedDiskSpec
Array of secondary disks that will be attached to the instance. The maximum number of elements is 3.
network_interface_specs[] NetworkInterfaceSpec
Required. Array of network interfaces that will be attached to the instance.
scheduling_policy SchedulingPolicy
Scheduling policy for the instance.
service_account_id string
Service account ID for the instance.
network_settings NetworkSettings
Network settings for the instance.
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.
hostname string
Host name for the instance. This field is used to generate the yandex.cloud.compute.v1.Instance.fqdn value. The host name must be unique within the network and region. If not specified, the host name will be equal to yandex.cloud.compute.v1.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.
placement_policy PlacementPolicy
Placement Group
filesystem_specs[] AttachedFilesystemSpec
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.
metadata_options MetadataOptions
Metadata options for the instance

ResourcesSpec

Field Description
memory int64
The amount of memory available to the instance, specified in bytes. The maximum value is 824633720832.
cores int64
The number of cores available to the instance. Value must be equal to 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,80.
core_fraction 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 equal to 0,5,20,50,100.
gpus int64
The number of GPUs available to the instance. Value must be equal to 0,1,2,4.

AttachedDiskSpec

Field Description
mode enum Mode
Required. Access mode to the Disk resource.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
device_name 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}.
disk_spec DiskSpec
Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
disk_id 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._{}]*.
name string
When set can be later used to change DiskSpec of actual disk. The maximum string length in characters is 128.

DiskSpec

Field Description
description string
Description of the disk. The maximum string length in characters is 256.
type_id string
Required. ID of the disk type.
size int64
Size of the disk, specified in bytes. Acceptable values are 4194304 to 28587302322176, inclusive.
source_oneof oneof: image_id or snapshot_id
  image_id string
ID of the image that will be used for disk creation. The maximum string length in characters is 50.
  snapshot_id string
ID of the snapshot that will be used for disk creation. The maximum string length in characters is 50.
preserve_after_instance_delete bool
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.

NetworkInterfaceSpec

Field Description
network_id string
ID of the network.
subnet_ids[] string
IDs of the subnets.
primary_v4_address_spec PrimaryAddressSpec
Primary IPv4 address that is assigned to the instance for this network interface.
primary_v6_address_spec PrimaryAddressSpec
Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.
security_group_ids[] string
IDs of security groups.

PrimaryAddressSpec

Field Description
one_to_one_nat_spec OneToOneNatSpec
An external IP address configuration. If not specified, then this managed instance will have no external internet access.
dns_record_specs[] DnsRecordSpec
Internal DNS configuration
address string
Optional. Manual set static internal IP. To set use variables.

OneToOneNatSpec

Field Description
ip_version enum IpVersion
IP version for the public IP address.
  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
address string
Manual set static public IP. To set use variables. (optional)
dns_record_specs[] DnsRecordSpec
External DNS configuration

DnsRecordSpec

Field Description
fqdn string
Required. FQDN (required)
dns_zone_id string
DNS zone id (optional, if not set, private zone used)
ttl int64
DNS record ttl, values in 0-86400 (optional) Acceptable values are 0 to 86400, inclusive.
ptr bool
When set to true, also create PTR DNS record (optional)

SchedulingPolicy

Field Description
preemptible bool
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.

NetworkSettings

Field Description
type enum Type
Type of instance network.

PlacementPolicy

Field Description
placement_group_id string
Identifier of placement group
host_affinity_rules[] HostAffinityRule
List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

HostAffinityRule

Field Description
key string
Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'
op enum Operator
Include or exclude action
values[] string
Affinity value or host ID or host group ID

AttachedFilesystemSpec

Field Description
mode enum Mode
Mode of access to the filesystem that should be attached.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.
device_name 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}.
filesystem_id 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._{}]*.

MetadataOptions

Field Description
gce_http_endpoint enum MetadataOption
Enabled access to GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_endpoint enum MetadataOption
Enabled access to AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
gce_http_token enum MetadataOption
Enabled access to IAM credentials with GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_token enum MetadataOption
Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

ScalePolicy

Field Description
scale_type oneof: fixed_scale or auto_scale
  fixed_scale FixedScale
Manual scaling policy of the instance group.
  auto_scale AutoScale
Automatic scaling policy of the instance group.
test_auto_scale AutoScale
Test spec for automatic scaling policy of the instance group.

AutoScale

Field Description
min_zone_size int64
Lower limit for instance count in each zone. Acceptable values are 0 to 100, inclusive.
max_size int64
Upper limit for total instance count (across all zones). 0 means maximum limit = 100. Acceptable values are 0 to 100, inclusive.
measurement_duration google.protobuf.Duration
Time in seconds allotted for averaging metrics. 1 minute by default. Acceptable values are 1m to 10m, inclusive.
warmup_duration google.protobuf.Duration
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 10m.
stabilization_duration google.protobuf.Duration
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 1m to 30m, inclusive.
initial_size int64
Target group size. The minimum value is 1.
cpu_utilization_rule CpuUtilizationRule
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 (custom_rules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
custom_rules[] CustomRule
Defines an autoscaling rule based on a custom metric from Monitoring.
If more than one rule is specified, e.g. CPU utilization (cpu_utilization_rule) 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.
auto_scale_type enum AutoScaleType
Autoscaling type.
  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.

CpuUtilizationRule

Field Description
utilization_target double
Target CPU utilization level. Instance Groups maintains this level for each availability zone. Acceptable values are 10 to 100, inclusive.

CustomRule

Field Description
rule_type enum RuleType
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.
metric_type enum MetricType
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 AutoScale.measurement_duration 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 AutoScale.measurement_duration field.
metric_name 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}.
labels map<string,string>
Labels of custom metric in Monitoring that should be used for scaling. Each value must match the regular expression [a-zA-Z0-9./@_][0-9a-zA-Z./@_,:;()\\[\\]<>-]{0,198}. Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$.
target double
Target value for the custom metric. Instance Groups maintains this level for each availability zone. Value must be greater than 0.
folder_id string
Folder id of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 50.
service string
Service of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 200.

FixedScale

Field Description
size int64
Number of instances in the instance group. Acceptable values are 1 to 100, inclusive.

DeployPolicy

Field Description
max_unavailable 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 max_expansion is not specified or set to zero, max_unavailable must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
max_deleting 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.
max_creating 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.
max_expansion int64
The maximum number of instances that can be temporarily allocated above the group's target size during the update process. If max_unavailable is not specified or set to zero, max_expansion must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
startup_duration google.protobuf.Duration
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 yandex.cloud.compute.v1.instancegroup.ManagedInstance.Status for more information. Acceptable values are 0m to 1h, inclusive.
strategy enum Strategy
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.
minimal_action enum MinimalAction
If instance update requires a less disruptive action than minimal_action, Instance Groups performs minimal_action 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

Field Description
zones[] Zone
List of availability zones. The minimum number of elements is 1.

Zone

Field Description
zone_id string
Required. ID of the availability zone where the instance resides.
instance_tags_pool[] 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.

HealthChecksSpec

Field Description
health_check_specs[] HealthCheckSpec
Health checking specification. For more information, see Health check. The minimum number of elements is 1.
max_checking_health_duration google.protobuf.Duration
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 1s.

HealthCheckSpec

Field Description
interval google.protobuf.Duration
The interval between health checks. The default is 2 seconds. Acceptable values are 1s to 300s, inclusive.
timeout google.protobuf.Duration
Timeout for the managed instance to return a response for the health check. The default is 1 second. Acceptable values are 1s to 60s, inclusive.
unhealthy_threshold int64
The number of failed health checks for the managed instance to be considered unhealthy. The default (0) is 2. Value must be equal to 0,2,3,4,5,6,7,8,9,10.
healthy_threshold 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 equal to 0,2,3,4,5,6,7,8,9,10.
health_check_options oneof: tcp_options or http_options
  tcp_options TcpOptions
Configuration options for a TCP health check.
  http_options HttpOptions
Configuration options for an HTTP health check.

TcpOptions

Field Description
port int64
Port to use for TCP health checks. Acceptable values are 1 to 65535, inclusive.

HttpOptions

Field Description
port int64
Port to use for HTTP health checks. Acceptable values are 1 to 65535, inclusive.
path string
URL path to set for health checking requests.

LoadBalancerSpec

Field Description
target_group_spec TargetGroupSpec
Specification of the target group that the instance group will be added to. For more information, see Target groups and resources.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

TargetGroupSpec

Field Description
name string
Name of the target group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the target group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.

Variable

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

ApplicationLoadBalancerSpec

Field Description
target_group_spec ApplicationTargetGroupSpec
Required. Basic properties of the Application Load Balancer target group attributed to the instance group.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

ApplicationTargetGroupSpec

Field Description
name string
Name of the target group.
description string
Description of the target group.
labels map<string,string>
Resource labels as key:value pairs.

Operation

Field Description
id string
ID of the operation.
description string
Description of the operation. 0-256 characters long.
created_at google.protobuf.Timestamp
Creation timestamp.
created_by string
ID of the user or service account who initiated the operation.
modified_at google.protobuf.Timestamp
The time when the Operation resource was last modified.
done bool
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 google.protobuf.Any<UpdateInstanceGroupMetadata>
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.
result oneof: error or response
The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true, exactly one of error or response is set.
  error google.rpc.Status
The error result of the operation in case of failure or cancellation.
  response google.protobuf.Any<InstanceGroup>
if operation finished successfully.

UpdateInstanceGroupMetadata

Field Description
instance_group_id string
ID of the InstanceGroup resource that is being updated. To get the instance group ID, use a InstanceGroupService.List request.

InstanceGroup

Field Description
id string
ID of the instance group.
folder_id string
ID of the folder that the instance group belongs to.
created_at google.protobuf.Timestamp
Creation timestamp in RFC3339 text format.
name string
Name of the instance group. The name is unique within the folder.
description string
Description of the instance group.
labels map<string,string>
Resource labels as key:value pairs.
instance_template InstanceTemplate
Instance template for creating the instance group. For more information, see Instance Templates.
scale_policy ScalePolicy
Scaling policy of the instance group.
deploy_policy DeployPolicy
Deployment policy of the instance group.
allocation_policy AllocationPolicy
Allocation policy of the instance group by zones and regions.
load_balancer_state LoadBalancerState
Status of the Network Load Balancer target group attributed to the instance group.
managed_instances_state ManagedInstancesState
States of instances for this instance group.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
status enum Status
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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.ResumeProcesses. The group status will change to ACTIVE.
variables[] Variable
deletion_protection bool
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.
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
application_load_balancer_state ApplicationLoadBalancerState
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.
auto_healing_policy AutoHealingPolicy
AutoHealingPolicy policy of the instance group.

LoadBalancerState

Field Description
target_group_id string
ID of the Network Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

ManagedInstancesState

Field Description
target_size int64
Target number of instances for this instance group.
running_actual_count int64
The number of running instances that match the current instance template. For more information, see ManagedInstance.Status.RUNNING_ACTUAL.
running_outdated_count int64
The number of running instances that does not match the current instance template. For more information, see ManagedInstance.Status.RUNNING_OUTDATED.
processing_count int64
The number of instances in flight (for example, updating, starting, deleting). For more information, see ManagedInstance.Status.

Statuses

Field Description
creating int64
Instance is being created.
starting int64
Instance is being started.
opening int64
Instance is being opened to receive traffic.
warming int64
Instance is being warmed.
running int64
Instance is running normally.
closing int64
Instance is being closed to traffic.
stopping int64
Instance is being stopped.
updating int64
Instance is being updated.
deleting int64
Instance is being deleted.
failed int64
Instance failed and needs to be recreated.

ApplicationLoadBalancerState

Field Description
target_group_id string
ID of the Application Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

AutoHealingPolicy

Field Description
auto_healing_action enum AutoHealingAction
Instance Groups performs auto_healing_action 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

UpdateFromYaml

Updates the specified instance group from a YAML file. This method starts an operation that can be cancelled by another operation.

rpc UpdateFromYaml (UpdateInstanceGroupFromYamlRequest) returns (operation.Operation)

Metadata and response of Operation:

    Operation.metadata:UpdateInstanceGroupMetadata

    Operation.response:InstanceGroup

UpdateInstanceGroupFromYamlRequest

Field Description
instance_group_id string
Required. ID of the instance group to update. To get the instance group ID, use a InstanceGroupService.List request. The maximum string length in characters is 50.
instance_group_yaml string
Required. InstanceGroupService.Update request in YAML format. The maximum string length in characters is 1048576.

Operation

Field Description
id string
ID of the operation.
description string
Description of the operation. 0-256 characters long.
created_at google.protobuf.Timestamp
Creation timestamp.
created_by string
ID of the user or service account who initiated the operation.
modified_at google.protobuf.Timestamp
The time when the Operation resource was last modified.
done bool
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 google.protobuf.Any<UpdateInstanceGroupMetadata>
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.
result oneof: error or response
The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true, exactly one of error or response is set.
  error google.rpc.Status
The error result of the operation in case of failure or cancellation.
  response google.protobuf.Any<InstanceGroup>
if operation finished successfully.

UpdateInstanceGroupMetadata

Field Description
instance_group_id string
ID of the InstanceGroup resource that is being updated. To get the instance group ID, use a InstanceGroupService.List request.

InstanceGroup

Field Description
id string
ID of the instance group.
folder_id string
ID of the folder that the instance group belongs to.
created_at google.protobuf.Timestamp
Creation timestamp in RFC3339 text format.
name string
Name of the instance group. The name is unique within the folder.
description string
Description of the instance group.
labels map<string,string>
Resource labels as key:value pairs.
instance_template InstanceTemplate
Instance template for creating the instance group. For more information, see Instance Templates.
scale_policy ScalePolicy
Scaling policy of the instance group.
deploy_policy DeployPolicy
Deployment policy of the instance group.
allocation_policy AllocationPolicy
Allocation policy of the instance group by zones and regions.
load_balancer_state LoadBalancerState
Status of the Network Load Balancer target group attributed to the instance group.
managed_instances_state ManagedInstancesState
States of instances for this instance group.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
status enum Status
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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.ResumeProcesses. The group status will change to ACTIVE.
variables[] Variable
deletion_protection bool
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.
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
application_load_balancer_state ApplicationLoadBalancerState
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.
auto_healing_policy AutoHealingPolicy
AutoHealingPolicy policy of the instance group.

InstanceTemplate

Field Description
description string
Description of the instance template. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 128. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
platform_id 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.
resources_spec ResourcesSpec
Required. Computing resources of the instance such as the amount of memory and number of cores.
metadata map<string,string>
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 maximum string length in characters for each value is 262144. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_0-9a-z]*.
boot_disk_spec AttachedDiskSpec
Required. Boot disk specification that will be attached to the instance.
secondary_disk_specs[] AttachedDiskSpec
Array of secondary disks that will be attached to the instance. The maximum number of elements is 3.
network_interface_specs[] NetworkInterfaceSpec
Required. Array of network interfaces that will be attached to the instance.
scheduling_policy SchedulingPolicy
Scheduling policy for the instance.
service_account_id string
Service account ID for the instance.
network_settings NetworkSettings
Network settings for the instance.
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.
hostname string
Host name for the instance. This field is used to generate the yandex.cloud.compute.v1.Instance.fqdn value. The host name must be unique within the network and region. If not specified, the host name will be equal to yandex.cloud.compute.v1.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.
placement_policy PlacementPolicy
Placement Group
filesystem_specs[] AttachedFilesystemSpec
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.
metadata_options MetadataOptions
Metadata options for the instance

ResourcesSpec

Field Description
memory int64
The amount of memory available to the instance, specified in bytes. The maximum value is 824633720832.
cores int64
The number of cores available to the instance. Value must be equal to 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,80.
core_fraction 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 equal to 0,5,20,50,100.
gpus int64
The number of GPUs available to the instance. Value must be equal to 0,1,2,4.

AttachedDiskSpec

Field Description
mode enum Mode
Required. Access mode to the Disk resource.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
device_name 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}.
disk_spec DiskSpec
Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
disk_id 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._{}]*.
name string
When set can be later used to change DiskSpec of actual disk. The maximum string length in characters is 128.

DiskSpec

Field Description
description string
Description of the disk. The maximum string length in characters is 256.
type_id string
Required. ID of the disk type.
size int64
Size of the disk, specified in bytes. Acceptable values are 4194304 to 28587302322176, inclusive.
source_oneof oneof: image_id or snapshot_id
  image_id string
ID of the image that will be used for disk creation. The maximum string length in characters is 50.
  snapshot_id string
ID of the snapshot that will be used for disk creation. The maximum string length in characters is 50.
preserve_after_instance_delete bool
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.

NetworkInterfaceSpec

Field Description
network_id string
ID of the network.
subnet_ids[] string
IDs of the subnets.
primary_v4_address_spec PrimaryAddressSpec
Primary IPv4 address that is assigned to the instance for this network interface.
primary_v6_address_spec PrimaryAddressSpec
Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.
security_group_ids[] string
IDs of security groups.

PrimaryAddressSpec

Field Description
one_to_one_nat_spec OneToOneNatSpec
An external IP address configuration. If not specified, then this managed instance will have no external internet access.
dns_record_specs[] DnsRecordSpec
Internal DNS configuration
address string
Optional. Manual set static internal IP. To set use variables.

OneToOneNatSpec

Field Description
ip_version enum IpVersion
IP version for the public IP address.
  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
address string
Manual set static public IP. To set use variables. (optional)
dns_record_specs[] DnsRecordSpec
External DNS configuration

DnsRecordSpec

Field Description
fqdn string
Required. FQDN (required)
dns_zone_id string
DNS zone id (optional, if not set, private zone used)
ttl int64
DNS record ttl, values in 0-86400 (optional) Acceptable values are 0 to 86400, inclusive.
ptr bool
When set to true, also create PTR DNS record (optional)

SchedulingPolicy

Field Description
preemptible bool
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.

NetworkSettings

Field Description
type enum Type
Type of instance network.

PlacementPolicy

Field Description
placement_group_id string
Identifier of placement group
host_affinity_rules[] HostAffinityRule
List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

HostAffinityRule

Field Description
key string
Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'
op enum Operator
Include or exclude action
values[] string
Affinity value or host ID or host group ID

AttachedFilesystemSpec

Field Description
mode enum Mode
Mode of access to the filesystem that should be attached.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.
device_name 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}.
filesystem_id 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._{}]*.

MetadataOptions

Field Description
gce_http_endpoint enum MetadataOption
Enabled access to GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_endpoint enum MetadataOption
Enabled access to AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
gce_http_token enum MetadataOption
Enabled access to IAM credentials with GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_token enum MetadataOption
Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

ScalePolicy

Field Description
scale_type oneof: fixed_scale or auto_scale
  fixed_scale FixedScale
Manual scaling policy of the instance group.
  auto_scale AutoScale
Automatic scaling policy of the instance group.
test_auto_scale AutoScale
Test spec for automatic scaling policy of the instance group.

AutoScale

Field Description
min_zone_size int64
Lower limit for instance count in each zone. Acceptable values are 0 to 100, inclusive.
max_size int64
Upper limit for total instance count (across all zones). 0 means maximum limit = 100. Acceptable values are 0 to 100, inclusive.
measurement_duration google.protobuf.Duration
Time in seconds allotted for averaging metrics. 1 minute by default. Acceptable values are 1m to 10m, inclusive.
warmup_duration google.protobuf.Duration
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 10m.
stabilization_duration google.protobuf.Duration
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 1m to 30m, inclusive.
initial_size int64
Target group size. The minimum value is 1.
cpu_utilization_rule CpuUtilizationRule
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 (custom_rules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
custom_rules[] CustomRule
Defines an autoscaling rule based on a custom metric from Monitoring.
If more than one rule is specified, e.g. CPU utilization (cpu_utilization_rule) 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.
auto_scale_type enum AutoScaleType
Autoscaling type.
  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.

CpuUtilizationRule

Field Description
utilization_target double
Target CPU utilization level. Instance Groups maintains this level for each availability zone. Acceptable values are 10 to 100, inclusive.

CustomRule

Field Description
rule_type enum RuleType
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.
metric_type enum MetricType
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 AutoScale.measurement_duration 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 AutoScale.measurement_duration field.
metric_name 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}.
labels map<string,string>
Labels of custom metric in Monitoring that should be used for scaling. Each value must match the regular expression [a-zA-Z0-9./@_][0-9a-zA-Z./@_,:;()\\[\\]<>-]{0,198}. Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$.
target double
Target value for the custom metric. Instance Groups maintains this level for each availability zone. Value must be greater than 0.
folder_id string
Folder id of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 50.
service string
Service of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 200.

FixedScale

Field Description
size int64
Number of instances in the instance group. Acceptable values are 1 to 100, inclusive.

DeployPolicy

Field Description
max_unavailable 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 max_expansion is not specified or set to zero, max_unavailable must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
max_deleting 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.
max_creating 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.
max_expansion int64
The maximum number of instances that can be temporarily allocated above the group's target size during the update process. If max_unavailable is not specified or set to zero, max_expansion must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
startup_duration google.protobuf.Duration
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 yandex.cloud.compute.v1.instancegroup.ManagedInstance.Status for more information. Acceptable values are 0m to 1h, inclusive.
strategy enum Strategy
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.
minimal_action enum MinimalAction
If instance update requires a less disruptive action than minimal_action, Instance Groups performs minimal_action 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

Field Description
zones[] Zone
List of availability zones. The minimum number of elements is 1.

Zone

Field Description
zone_id string
Required. ID of the availability zone where the instance resides.
instance_tags_pool[] 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

Field Description
target_group_id string
ID of the Network Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

ManagedInstancesState

Field Description
target_size int64
Target number of instances for this instance group.
running_actual_count int64
The number of running instances that match the current instance template. For more information, see ManagedInstance.Status.RUNNING_ACTUAL.
running_outdated_count int64
The number of running instances that does not match the current instance template. For more information, see ManagedInstance.Status.RUNNING_OUTDATED.
processing_count int64
The number of instances in flight (for example, updating, starting, deleting). For more information, see ManagedInstance.Status.

Statuses

Field Description
creating int64
Instance is being created.
starting int64
Instance is being started.
opening int64
Instance is being opened to receive traffic.
warming int64
Instance is being warmed.
running int64
Instance is running normally.
closing int64
Instance is being closed to traffic.
stopping int64
Instance is being stopped.
updating int64
Instance is being updated.
deleting int64
Instance is being deleted.
failed int64
Instance failed and needs to be recreated.

LoadBalancerSpec

Field Description
target_group_spec TargetGroupSpec
Specification of the target group that the instance group will be added to. For more information, see Target groups and resources.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

TargetGroupSpec

Field Description
name string
Name of the target group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the target group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.

HealthChecksSpec

Field Description
health_check_specs[] HealthCheckSpec
Health checking specification. For more information, see Health check. The minimum number of elements is 1.
max_checking_health_duration google.protobuf.Duration
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 1s.

HealthCheckSpec

Field Description
interval google.protobuf.Duration
The interval between health checks. The default is 2 seconds. Acceptable values are 1s to 300s, inclusive.
timeout google.protobuf.Duration
Timeout for the managed instance to return a response for the health check. The default is 1 second. Acceptable values are 1s to 60s, inclusive.
unhealthy_threshold int64
The number of failed health checks for the managed instance to be considered unhealthy. The default (0) is 2. Value must be equal to 0,2,3,4,5,6,7,8,9,10.
healthy_threshold 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 equal to 0,2,3,4,5,6,7,8,9,10.
health_check_options oneof: tcp_options or http_options
  tcp_options TcpOptions
Configuration options for a TCP health check.
  http_options HttpOptions
Configuration options for an HTTP health check.

TcpOptions

Field Description
port int64
Port to use for TCP health checks. Acceptable values are 1 to 65535, inclusive.

HttpOptions

Field Description
port int64
Port to use for HTTP health checks. Acceptable values are 1 to 65535, inclusive.
path string
URL path to set for health checking requests.

Variable

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

ApplicationLoadBalancerSpec

Field Description
target_group_spec ApplicationTargetGroupSpec
Required. Basic properties of the Application Load Balancer target group attributed to the instance group.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

ApplicationTargetGroupSpec

Field Description
name string
Name of the target group.
description string
Description of the target group.
labels map<string,string>
Resource labels as key:value pairs.

ApplicationLoadBalancerState

Field Description
target_group_id string
ID of the Application Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

AutoHealingPolicy

Field Description
auto_healing_action enum AutoHealingAction
Instance Groups performs auto_healing_action 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

Stop

Stops the specified instance group.

rpc Stop (StopInstanceGroupRequest) returns (operation.Operation)

Metadata and response of Operation:

    Operation.metadata:StopInstanceGroupMetadata

    Operation.response:InstanceGroup

StopInstanceGroupRequest

Field Description
instance_group_id string
Required. ID of the instance group to stop. To get the instance group ID, use a InstanceGroupService.List request. The maximum string length in characters is 50.

Operation

Field Description
id string
ID of the operation.
description string
Description of the operation. 0-256 characters long.
created_at google.protobuf.Timestamp
Creation timestamp.
created_by string
ID of the user or service account who initiated the operation.
modified_at google.protobuf.Timestamp
The time when the Operation resource was last modified.
done bool
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 google.protobuf.Any<StopInstanceGroupMetadata>
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.
result oneof: error or response
The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true, exactly one of error or response is set.
  error google.rpc.Status
The error result of the operation in case of failure or cancellation.
  response google.protobuf.Any<InstanceGroup>
if operation finished successfully.

StopInstanceGroupMetadata

Field Description
instance_group_id string
ID of the InstanceGroup resource that is being stopped.

InstanceGroup

Field Description
id string
ID of the instance group.
folder_id string
ID of the folder that the instance group belongs to.
created_at google.protobuf.Timestamp
Creation timestamp in RFC3339 text format.
name string
Name of the instance group. The name is unique within the folder.
description string
Description of the instance group.
labels map<string,string>
Resource labels as key:value pairs.
instance_template InstanceTemplate
Instance template for creating the instance group. For more information, see Instance Templates.
scale_policy ScalePolicy
Scaling policy of the instance group.
deploy_policy DeployPolicy
Deployment policy of the instance group.
allocation_policy AllocationPolicy
Allocation policy of the instance group by zones and regions.
load_balancer_state LoadBalancerState
Status of the Network Load Balancer target group attributed to the instance group.
managed_instances_state ManagedInstancesState
States of instances for this instance group.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
status enum Status
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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.ResumeProcesses. The group status will change to ACTIVE.
variables[] Variable
deletion_protection bool
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.
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
application_load_balancer_state ApplicationLoadBalancerState
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.
auto_healing_policy AutoHealingPolicy
AutoHealingPolicy policy of the instance group.

InstanceTemplate

Field Description
description string
Description of the instance template. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 128. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
platform_id 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.
resources_spec ResourcesSpec
Required. Computing resources of the instance such as the amount of memory and number of cores.
metadata map<string,string>
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 maximum string length in characters for each value is 262144. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_0-9a-z]*.
boot_disk_spec AttachedDiskSpec
Required. Boot disk specification that will be attached to the instance.
secondary_disk_specs[] AttachedDiskSpec
Array of secondary disks that will be attached to the instance. The maximum number of elements is 3.
network_interface_specs[] NetworkInterfaceSpec
Required. Array of network interfaces that will be attached to the instance.
scheduling_policy SchedulingPolicy
Scheduling policy for the instance.
service_account_id string
Service account ID for the instance.
network_settings NetworkSettings
Network settings for the instance.
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.
hostname string
Host name for the instance. This field is used to generate the yandex.cloud.compute.v1.Instance.fqdn value. The host name must be unique within the network and region. If not specified, the host name will be equal to yandex.cloud.compute.v1.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.
placement_policy PlacementPolicy
Placement Group
filesystem_specs[] AttachedFilesystemSpec
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.
metadata_options MetadataOptions
Metadata options for the instance

ResourcesSpec

Field Description
memory int64
The amount of memory available to the instance, specified in bytes. The maximum value is 824633720832.
cores int64
The number of cores available to the instance. Value must be equal to 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,80.
core_fraction 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 equal to 0,5,20,50,100.
gpus int64
The number of GPUs available to the instance. Value must be equal to 0,1,2,4.

AttachedDiskSpec

Field Description
mode enum Mode
Required. Access mode to the Disk resource.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
device_name 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}.
disk_spec DiskSpec
Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
disk_id 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._{}]*.
name string
When set can be later used to change DiskSpec of actual disk. The maximum string length in characters is 128.

DiskSpec

Field Description
description string
Description of the disk. The maximum string length in characters is 256.
type_id string
Required. ID of the disk type.
size int64
Size of the disk, specified in bytes. Acceptable values are 4194304 to 28587302322176, inclusive.
source_oneof oneof: image_id or snapshot_id
  image_id string
ID of the image that will be used for disk creation. The maximum string length in characters is 50.
  snapshot_id string
ID of the snapshot that will be used for disk creation. The maximum string length in characters is 50.
preserve_after_instance_delete bool
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.

NetworkInterfaceSpec

Field Description
network_id string
ID of the network.
subnet_ids[] string
IDs of the subnets.
primary_v4_address_spec PrimaryAddressSpec
Primary IPv4 address that is assigned to the instance for this network interface.
primary_v6_address_spec PrimaryAddressSpec
Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.
security_group_ids[] string
IDs of security groups.

PrimaryAddressSpec

Field Description
one_to_one_nat_spec OneToOneNatSpec
An external IP address configuration. If not specified, then this managed instance will have no external internet access.
dns_record_specs[] DnsRecordSpec
Internal DNS configuration
address string
Optional. Manual set static internal IP. To set use variables.

OneToOneNatSpec

Field Description
ip_version enum IpVersion
IP version for the public IP address.
  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
address string
Manual set static public IP. To set use variables. (optional)
dns_record_specs[] DnsRecordSpec
External DNS configuration

DnsRecordSpec

Field Description
fqdn string
Required. FQDN (required)
dns_zone_id string
DNS zone id (optional, if not set, private zone used)
ttl int64
DNS record ttl, values in 0-86400 (optional) Acceptable values are 0 to 86400, inclusive.
ptr bool
When set to true, also create PTR DNS record (optional)

SchedulingPolicy

Field Description
preemptible bool
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.

NetworkSettings

Field Description
type enum Type
Type of instance network.

PlacementPolicy

Field Description
placement_group_id string
Identifier of placement group
host_affinity_rules[] HostAffinityRule
List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

HostAffinityRule

Field Description
key string
Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'
op enum Operator
Include or exclude action
values[] string
Affinity value or host ID or host group ID

AttachedFilesystemSpec

Field Description
mode enum Mode
Mode of access to the filesystem that should be attached.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.
device_name 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}.
filesystem_id 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._{}]*.

MetadataOptions

Field Description
gce_http_endpoint enum MetadataOption
Enabled access to GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_endpoint enum MetadataOption
Enabled access to AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
gce_http_token enum MetadataOption
Enabled access to IAM credentials with GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_token enum MetadataOption
Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

ScalePolicy

Field Description
scale_type oneof: fixed_scale or auto_scale
  fixed_scale FixedScale
Manual scaling policy of the instance group.
  auto_scale AutoScale
Automatic scaling policy of the instance group.
test_auto_scale AutoScale
Test spec for automatic scaling policy of the instance group.

AutoScale

Field Description
min_zone_size int64
Lower limit for instance count in each zone. Acceptable values are 0 to 100, inclusive.
max_size int64
Upper limit for total instance count (across all zones). 0 means maximum limit = 100. Acceptable values are 0 to 100, inclusive.
measurement_duration google.protobuf.Duration
Time in seconds allotted for averaging metrics. 1 minute by default. Acceptable values are 1m to 10m, inclusive.
warmup_duration google.protobuf.Duration
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 10m.
stabilization_duration google.protobuf.Duration
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 1m to 30m, inclusive.
initial_size int64
Target group size. The minimum value is 1.
cpu_utilization_rule CpuUtilizationRule
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 (custom_rules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
custom_rules[] CustomRule
Defines an autoscaling rule based on a custom metric from Monitoring.
If more than one rule is specified, e.g. CPU utilization (cpu_utilization_rule) 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.
auto_scale_type enum AutoScaleType
Autoscaling type.
  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.

CpuUtilizationRule

Field Description
utilization_target double
Target CPU utilization level. Instance Groups maintains this level for each availability zone. Acceptable values are 10 to 100, inclusive.

CustomRule

Field Description
rule_type enum RuleType
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.
metric_type enum MetricType
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 AutoScale.measurement_duration 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 AutoScale.measurement_duration field.
metric_name 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}.
labels map<string,string>
Labels of custom metric in Monitoring that should be used for scaling. Each value must match the regular expression [a-zA-Z0-9./@_][0-9a-zA-Z./@_,:;()\\[\\]<>-]{0,198}. Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$.
target double
Target value for the custom metric. Instance Groups maintains this level for each availability zone. Value must be greater than 0.
folder_id string
Folder id of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 50.
service string
Service of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 200.

FixedScale

Field Description
size int64
Number of instances in the instance group. Acceptable values are 1 to 100, inclusive.

DeployPolicy

Field Description
max_unavailable 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 max_expansion is not specified or set to zero, max_unavailable must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
max_deleting 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.
max_creating 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.
max_expansion int64
The maximum number of instances that can be temporarily allocated above the group's target size during the update process. If max_unavailable is not specified or set to zero, max_expansion must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
startup_duration google.protobuf.Duration
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 yandex.cloud.compute.v1.instancegroup.ManagedInstance.Status for more information. Acceptable values are 0m to 1h, inclusive.
strategy enum Strategy
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.
minimal_action enum MinimalAction
If instance update requires a less disruptive action than minimal_action, Instance Groups performs minimal_action 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

Field Description
zones[] Zone
List of availability zones. The minimum number of elements is 1.

Zone

Field Description
zone_id string
Required. ID of the availability zone where the instance resides.
instance_tags_pool[] 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

Field Description
target_group_id string
ID of the Network Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

ManagedInstancesState

Field Description
target_size int64
Target number of instances for this instance group.
running_actual_count int64
The number of running instances that match the current instance template. For more information, see ManagedInstance.Status.RUNNING_ACTUAL.
running_outdated_count int64
The number of running instances that does not match the current instance template. For more information, see ManagedInstance.Status.RUNNING_OUTDATED.
processing_count int64
The number of instances in flight (for example, updating, starting, deleting). For more information, see ManagedInstance.Status.

Statuses

Field Description
creating int64
Instance is being created.
starting int64
Instance is being started.
opening int64
Instance is being opened to receive traffic.
warming int64
Instance is being warmed.
running int64
Instance is running normally.
closing int64
Instance is being closed to traffic.
stopping int64
Instance is being stopped.
updating int64
Instance is being updated.
deleting int64
Instance is being deleted.
failed int64
Instance failed and needs to be recreated.

LoadBalancerSpec

Field Description
target_group_spec TargetGroupSpec
Specification of the target group that the instance group will be added to. For more information, see Target groups and resources.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

TargetGroupSpec

Field Description
name string
Name of the target group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the target group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.

HealthChecksSpec

Field Description
health_check_specs[] HealthCheckSpec
Health checking specification. For more information, see Health check. The minimum number of elements is 1.
max_checking_health_duration google.protobuf.Duration
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 1s.

HealthCheckSpec

Field Description
interval google.protobuf.Duration
The interval between health checks. The default is 2 seconds. Acceptable values are 1s to 300s, inclusive.
timeout google.protobuf.Duration
Timeout for the managed instance to return a response for the health check. The default is 1 second. Acceptable values are 1s to 60s, inclusive.
unhealthy_threshold int64
The number of failed health checks for the managed instance to be considered unhealthy. The default (0) is 2. Value must be equal to 0,2,3,4,5,6,7,8,9,10.
healthy_threshold 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 equal to 0,2,3,4,5,6,7,8,9,10.
health_check_options oneof: tcp_options or http_options
  tcp_options TcpOptions
Configuration options for a TCP health check.
  http_options HttpOptions
Configuration options for an HTTP health check.

TcpOptions

Field Description
port int64
Port to use for TCP health checks. Acceptable values are 1 to 65535, inclusive.

HttpOptions

Field Description
port int64
Port to use for HTTP health checks. Acceptable values are 1 to 65535, inclusive.
path string
URL path to set for health checking requests.

Variable

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

ApplicationLoadBalancerSpec

Field Description
target_group_spec ApplicationTargetGroupSpec
Required. Basic properties of the Application Load Balancer target group attributed to the instance group.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

ApplicationTargetGroupSpec

Field Description
name string
Name of the target group.
description string
Description of the target group.
labels map<string,string>
Resource labels as key:value pairs.

ApplicationLoadBalancerState

Field Description
target_group_id string
ID of the Application Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

AutoHealingPolicy

Field Description
auto_healing_action enum AutoHealingAction
Instance Groups performs auto_healing_action 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

RollingRestart

Performs rolling restart of specified instances for the specified instance group. Rolling restart does restart of instances respecting all group policies.

rpc RollingRestart (RollingRestartRequest) returns (operation.Operation)

Metadata and response of Operation:

    Operation.metadata:RollingRestartMetadata

    Operation.response:InstanceGroup

RollingRestartRequest

Field Description
instance_group_id string
Required. ID of the instance group to restart instances in. To get the instance group ID, use a InstanceGroupService.List request. The maximum string length in characters is 50.
managed_instance_ids[] string
IDs of managed instances in the group to restart To get instance IDs, use a InstanceGroupService.ListInstances request.

Operation

Field Description
id string
ID of the operation.
description string
Description of the operation. 0-256 characters long.
created_at google.protobuf.Timestamp
Creation timestamp.
created_by string
ID of the user or service account who initiated the operation.
modified_at google.protobuf.Timestamp
The time when the Operation resource was last modified.
done bool
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 google.protobuf.Any<RollingRestartMetadata>
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.
result oneof: error or response
The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true, exactly one of error or response is set.
  error google.rpc.Status
The error result of the operation in case of failure or cancellation.
  response google.protobuf.Any<InstanceGroup>
if operation finished successfully.

RollingRestartMetadata

Field Description
instance_group_id string
ID of the InstanceGroup resource that is being rolling restarted.

InstanceGroup

Field Description
id string
ID of the instance group.
folder_id string
ID of the folder that the instance group belongs to.
created_at google.protobuf.Timestamp
Creation timestamp in RFC3339 text format.
name string
Name of the instance group. The name is unique within the folder.
description string
Description of the instance group.
labels map<string,string>
Resource labels as key:value pairs.
instance_template InstanceTemplate
Instance template for creating the instance group. For more information, see Instance Templates.
scale_policy ScalePolicy
Scaling policy of the instance group.
deploy_policy DeployPolicy
Deployment policy of the instance group.
allocation_policy AllocationPolicy
Allocation policy of the instance group by zones and regions.
load_balancer_state LoadBalancerState
Status of the Network Load Balancer target group attributed to the instance group.
managed_instances_state ManagedInstancesState
States of instances for this instance group.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
status enum Status
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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.ResumeProcesses. The group status will change to ACTIVE.
variables[] Variable
deletion_protection bool
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.
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
application_load_balancer_state ApplicationLoadBalancerState
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.
auto_healing_policy AutoHealingPolicy
AutoHealingPolicy policy of the instance group.

InstanceTemplate

Field Description
description string
Description of the instance template. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 128. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
platform_id 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.
resources_spec ResourcesSpec
Required. Computing resources of the instance such as the amount of memory and number of cores.
metadata map<string,string>
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 maximum string length in characters for each value is 262144. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_0-9a-z]*.
boot_disk_spec AttachedDiskSpec
Required. Boot disk specification that will be attached to the instance.
secondary_disk_specs[] AttachedDiskSpec
Array of secondary disks that will be attached to the instance. The maximum number of elements is 3.
network_interface_specs[] NetworkInterfaceSpec
Required. Array of network interfaces that will be attached to the instance.
scheduling_policy SchedulingPolicy
Scheduling policy for the instance.
service_account_id string
Service account ID for the instance.
network_settings NetworkSettings
Network settings for the instance.
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.
hostname string
Host name for the instance. This field is used to generate the yandex.cloud.compute.v1.Instance.fqdn value. The host name must be unique within the network and region. If not specified, the host name will be equal to yandex.cloud.compute.v1.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.
placement_policy PlacementPolicy
Placement Group
filesystem_specs[] AttachedFilesystemSpec
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.
metadata_options MetadataOptions
Metadata options for the instance

ResourcesSpec

Field Description
memory int64
The amount of memory available to the instance, specified in bytes. The maximum value is 824633720832.
cores int64
The number of cores available to the instance. Value must be equal to 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,80.
core_fraction 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 equal to 0,5,20,50,100.
gpus int64
The number of GPUs available to the instance. Value must be equal to 0,1,2,4.

AttachedDiskSpec

Field Description
mode enum Mode
Required. Access mode to the Disk resource.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
device_name 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}.
disk_spec DiskSpec
Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
disk_id 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._{}]*.
name string
When set can be later used to change DiskSpec of actual disk. The maximum string length in characters is 128.

DiskSpec

Field Description
description string
Description of the disk. The maximum string length in characters is 256.
type_id string
Required. ID of the disk type.
size int64
Size of the disk, specified in bytes. Acceptable values are 4194304 to 28587302322176, inclusive.
source_oneof oneof: image_id or snapshot_id
  image_id string
ID of the image that will be used for disk creation. The maximum string length in characters is 50.
  snapshot_id string
ID of the snapshot that will be used for disk creation. The maximum string length in characters is 50.
preserve_after_instance_delete bool
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.

NetworkInterfaceSpec

Field Description
network_id string
ID of the network.
subnet_ids[] string
IDs of the subnets.
primary_v4_address_spec PrimaryAddressSpec
Primary IPv4 address that is assigned to the instance for this network interface.
primary_v6_address_spec PrimaryAddressSpec
Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.
security_group_ids[] string
IDs of security groups.

PrimaryAddressSpec

Field Description
one_to_one_nat_spec OneToOneNatSpec
An external IP address configuration. If not specified, then this managed instance will have no external internet access.
dns_record_specs[] DnsRecordSpec
Internal DNS configuration
address string
Optional. Manual set static internal IP. To set use variables.

OneToOneNatSpec

Field Description
ip_version enum IpVersion
IP version for the public IP address.
  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
address string
Manual set static public IP. To set use variables. (optional)
dns_record_specs[] DnsRecordSpec
External DNS configuration

DnsRecordSpec

Field Description
fqdn string
Required. FQDN (required)
dns_zone_id string
DNS zone id (optional, if not set, private zone used)
ttl int64
DNS record ttl, values in 0-86400 (optional) Acceptable values are 0 to 86400, inclusive.
ptr bool
When set to true, also create PTR DNS record (optional)

SchedulingPolicy

Field Description
preemptible bool
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.

NetworkSettings

Field Description
type enum Type
Type of instance network.

PlacementPolicy

Field Description
placement_group_id string
Identifier of placement group
host_affinity_rules[] HostAffinityRule
List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

HostAffinityRule

Field Description
key string
Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'
op enum Operator
Include or exclude action
values[] string
Affinity value or host ID or host group ID

AttachedFilesystemSpec

Field Description
mode enum Mode
Mode of access to the filesystem that should be attached.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.
device_name 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}.
filesystem_id 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._{}]*.

MetadataOptions

Field Description
gce_http_endpoint enum MetadataOption
Enabled access to GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_endpoint enum MetadataOption
Enabled access to AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
gce_http_token enum MetadataOption
Enabled access to IAM credentials with GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_token enum MetadataOption
Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

ScalePolicy

Field Description
scale_type oneof: fixed_scale or auto_scale
  fixed_scale FixedScale
Manual scaling policy of the instance group.
  auto_scale AutoScale
Automatic scaling policy of the instance group.
test_auto_scale AutoScale
Test spec for automatic scaling policy of the instance group.

AutoScale

Field Description
min_zone_size int64
Lower limit for instance count in each zone. Acceptable values are 0 to 100, inclusive.
max_size int64
Upper limit for total instance count (across all zones). 0 means maximum limit = 100. Acceptable values are 0 to 100, inclusive.
measurement_duration google.protobuf.Duration
Time in seconds allotted for averaging metrics. 1 minute by default. Acceptable values are 1m to 10m, inclusive.
warmup_duration google.protobuf.Duration
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 10m.
stabilization_duration google.protobuf.Duration
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 1m to 30m, inclusive.
initial_size int64
Target group size. The minimum value is 1.
cpu_utilization_rule CpuUtilizationRule
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 (custom_rules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
custom_rules[] CustomRule
Defines an autoscaling rule based on a custom metric from Monitoring.
If more than one rule is specified, e.g. CPU utilization (cpu_utilization_rule) 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.
auto_scale_type enum AutoScaleType
Autoscaling type.
  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.

CpuUtilizationRule

Field Description
utilization_target double
Target CPU utilization level. Instance Groups maintains this level for each availability zone. Acceptable values are 10 to 100, inclusive.

CustomRule

Field Description
rule_type enum RuleType
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.
metric_type enum MetricType
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 AutoScale.measurement_duration 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 AutoScale.measurement_duration field.
metric_name 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}.
labels map<string,string>
Labels of custom metric in Monitoring that should be used for scaling. Each value must match the regular expression [a-zA-Z0-9./@_][0-9a-zA-Z./@_,:;()\\[\\]<>-]{0,198}. Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$.
target double
Target value for the custom metric. Instance Groups maintains this level for each availability zone. Value must be greater than 0.
folder_id string
Folder id of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 50.
service string
Service of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 200.

FixedScale

Field Description
size int64
Number of instances in the instance group. Acceptable values are 1 to 100, inclusive.

DeployPolicy

Field Description
max_unavailable 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 max_expansion is not specified or set to zero, max_unavailable must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
max_deleting 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.
max_creating 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.
max_expansion int64
The maximum number of instances that can be temporarily allocated above the group's target size during the update process. If max_unavailable is not specified or set to zero, max_expansion must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
startup_duration google.protobuf.Duration
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 yandex.cloud.compute.v1.instancegroup.ManagedInstance.Status for more information. Acceptable values are 0m to 1h, inclusive.
strategy enum Strategy
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.
minimal_action enum MinimalAction
If instance update requires a less disruptive action than minimal_action, Instance Groups performs minimal_action 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

Field Description
zones[] Zone
List of availability zones. The minimum number of elements is 1.

Zone

Field Description
zone_id string
Required. ID of the availability zone where the instance resides.
instance_tags_pool[] 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

Field Description
target_group_id string
ID of the Network Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

ManagedInstancesState

Field Description
target_size int64
Target number of instances for this instance group.
running_actual_count int64
The number of running instances that match the current instance template. For more information, see ManagedInstance.Status.RUNNING_ACTUAL.
running_outdated_count int64
The number of running instances that does not match the current instance template. For more information, see ManagedInstance.Status.RUNNING_OUTDATED.
processing_count int64
The number of instances in flight (for example, updating, starting, deleting). For more information, see ManagedInstance.Status.

Statuses

Field Description
creating int64
Instance is being created.
starting int64
Instance is being started.
opening int64
Instance is being opened to receive traffic.
warming int64
Instance is being warmed.
running int64
Instance is running normally.
closing int64
Instance is being closed to traffic.
stopping int64
Instance is being stopped.
updating int64
Instance is being updated.
deleting int64
Instance is being deleted.
failed int64
Instance failed and needs to be recreated.

LoadBalancerSpec

Field Description
target_group_spec TargetGroupSpec
Specification of the target group that the instance group will be added to. For more information, see Target groups and resources.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

TargetGroupSpec

Field Description
name string
Name of the target group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the target group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.

HealthChecksSpec

Field Description
health_check_specs[] HealthCheckSpec
Health checking specification. For more information, see Health check. The minimum number of elements is 1.
max_checking_health_duration google.protobuf.Duration
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 1s.

HealthCheckSpec

Field Description
interval google.protobuf.Duration
The interval between health checks. The default is 2 seconds. Acceptable values are 1s to 300s, inclusive.
timeout google.protobuf.Duration
Timeout for the managed instance to return a response for the health check. The default is 1 second. Acceptable values are 1s to 60s, inclusive.
unhealthy_threshold int64
The number of failed health checks for the managed instance to be considered unhealthy. The default (0) is 2. Value must be equal to 0,2,3,4,5,6,7,8,9,10.
healthy_threshold 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 equal to 0,2,3,4,5,6,7,8,9,10.
health_check_options oneof: tcp_options or http_options
  tcp_options TcpOptions
Configuration options for a TCP health check.
  http_options HttpOptions
Configuration options for an HTTP health check.

TcpOptions

Field Description
port int64
Port to use for TCP health checks. Acceptable values are 1 to 65535, inclusive.

HttpOptions

Field Description
port int64
Port to use for HTTP health checks. Acceptable values are 1 to 65535, inclusive.
path string
URL path to set for health checking requests.

Variable

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

ApplicationLoadBalancerSpec

Field Description
target_group_spec ApplicationTargetGroupSpec
Required. Basic properties of the Application Load Balancer target group attributed to the instance group.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

ApplicationTargetGroupSpec

Field Description
name string
Name of the target group.
description string
Description of the target group.
labels map<string,string>
Resource labels as key:value pairs.

ApplicationLoadBalancerState

Field Description
target_group_id string
ID of the Application Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

AutoHealingPolicy

Field Description
auto_healing_action enum AutoHealingAction
Instance Groups performs auto_healing_action 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

RollingRecreate

Performs rolling recreate of specified instances for the specified instance group. Rolling recreate does recreate of instance VMs respecting all group policies.

rpc RollingRecreate (RollingRecreateRequest) returns (operation.Operation)

Metadata and response of Operation:

    Operation.metadata:RollingRecreateMetadata

    Operation.response:InstanceGroup

RollingRecreateRequest

Field Description
instance_group_id string
Required. ID of the instance group to recreate instances in. To get the instance group ID, use a InstanceGroupService.List request. The maximum string length in characters is 50.
managed_instance_ids[] string
IDs of managed instances in the group to recreate To get instance IDs, use a InstanceGroupService.ListInstances request.

Operation

Field Description
id string
ID of the operation.
description string
Description of the operation. 0-256 characters long.
created_at google.protobuf.Timestamp
Creation timestamp.
created_by string
ID of the user or service account who initiated the operation.
modified_at google.protobuf.Timestamp
The time when the Operation resource was last modified.
done bool
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 google.protobuf.Any<RollingRecreateMetadata>
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.
result oneof: error or response
The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true, exactly one of error or response is set.
  error google.rpc.Status
The error result of the operation in case of failure or cancellation.
  response google.protobuf.Any<InstanceGroup>
if operation finished successfully.

RollingRecreateMetadata

Field Description
instance_group_id string
ID of the InstanceGroup resource that is being rolling recreated.

InstanceGroup

Field Description
id string
ID of the instance group.
folder_id string
ID of the folder that the instance group belongs to.
created_at google.protobuf.Timestamp
Creation timestamp in RFC3339 text format.
name string
Name of the instance group. The name is unique within the folder.
description string
Description of the instance group.
labels map<string,string>
Resource labels as key:value pairs.
instance_template InstanceTemplate
Instance template for creating the instance group. For more information, see Instance Templates.
scale_policy ScalePolicy
Scaling policy of the instance group.
deploy_policy DeployPolicy
Deployment policy of the instance group.
allocation_policy AllocationPolicy
Allocation policy of the instance group by zones and regions.
load_balancer_state LoadBalancerState
Status of the Network Load Balancer target group attributed to the instance group.
managed_instances_state ManagedInstancesState
States of instances for this instance group.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
status enum Status
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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.ResumeProcesses. The group status will change to ACTIVE.
variables[] Variable
deletion_protection bool
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.
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
application_load_balancer_state ApplicationLoadBalancerState
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.
auto_healing_policy AutoHealingPolicy
AutoHealingPolicy policy of the instance group.

InstanceTemplate

Field Description
description string
Description of the instance template. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 128. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
platform_id 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.
resources_spec ResourcesSpec
Required. Computing resources of the instance such as the amount of memory and number of cores.
metadata map<string,string>
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 maximum string length in characters for each value is 262144. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_0-9a-z]*.
boot_disk_spec AttachedDiskSpec
Required. Boot disk specification that will be attached to the instance.
secondary_disk_specs[] AttachedDiskSpec
Array of secondary disks that will be attached to the instance. The maximum number of elements is 3.
network_interface_specs[] NetworkInterfaceSpec
Required. Array of network interfaces that will be attached to the instance.
scheduling_policy SchedulingPolicy
Scheduling policy for the instance.
service_account_id string
Service account ID for the instance.
network_settings NetworkSettings
Network settings for the instance.
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.
hostname string
Host name for the instance. This field is used to generate the yandex.cloud.compute.v1.Instance.fqdn value. The host name must be unique within the network and region. If not specified, the host name will be equal to yandex.cloud.compute.v1.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.
placement_policy PlacementPolicy
Placement Group
filesystem_specs[] AttachedFilesystemSpec
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.
metadata_options MetadataOptions
Metadata options for the instance

ResourcesSpec

Field Description
memory int64
The amount of memory available to the instance, specified in bytes. The maximum value is 824633720832.
cores int64
The number of cores available to the instance. Value must be equal to 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,80.
core_fraction 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 equal to 0,5,20,50,100.
gpus int64
The number of GPUs available to the instance. Value must be equal to 0,1,2,4.

AttachedDiskSpec

Field Description
mode enum Mode
Required. Access mode to the Disk resource.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
device_name 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}.
disk_spec DiskSpec
Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
disk_id 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._{}]*.
name string
When set can be later used to change DiskSpec of actual disk. The maximum string length in characters is 128.

DiskSpec

Field Description
description string
Description of the disk. The maximum string length in characters is 256.
type_id string
Required. ID of the disk type.
size int64
Size of the disk, specified in bytes. Acceptable values are 4194304 to 28587302322176, inclusive.
source_oneof oneof: image_id or snapshot_id
  image_id string
ID of the image that will be used for disk creation. The maximum string length in characters is 50.
  snapshot_id string
ID of the snapshot that will be used for disk creation. The maximum string length in characters is 50.
preserve_after_instance_delete bool
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.

NetworkInterfaceSpec

Field Description
network_id string
ID of the network.
subnet_ids[] string
IDs of the subnets.
primary_v4_address_spec PrimaryAddressSpec
Primary IPv4 address that is assigned to the instance for this network interface.
primary_v6_address_spec PrimaryAddressSpec
Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.
security_group_ids[] string
IDs of security groups.

PrimaryAddressSpec

Field Description
one_to_one_nat_spec OneToOneNatSpec
An external IP address configuration. If not specified, then this managed instance will have no external internet access.
dns_record_specs[] DnsRecordSpec
Internal DNS configuration
address string
Optional. Manual set static internal IP. To set use variables.

OneToOneNatSpec

Field Description
ip_version enum IpVersion
IP version for the public IP address.
  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
address string
Manual set static public IP. To set use variables. (optional)
dns_record_specs[] DnsRecordSpec
External DNS configuration

DnsRecordSpec

Field Description
fqdn string
Required. FQDN (required)
dns_zone_id string
DNS zone id (optional, if not set, private zone used)
ttl int64
DNS record ttl, values in 0-86400 (optional) Acceptable values are 0 to 86400, inclusive.
ptr bool
When set to true, also create PTR DNS record (optional)

SchedulingPolicy

Field Description
preemptible bool
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.

NetworkSettings

Field Description
type enum Type
Type of instance network.

PlacementPolicy

Field Description
placement_group_id string
Identifier of placement group
host_affinity_rules[] HostAffinityRule
List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

HostAffinityRule

Field Description
key string
Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'
op enum Operator
Include or exclude action
values[] string
Affinity value or host ID or host group ID

AttachedFilesystemSpec

Field Description
mode enum Mode
Mode of access to the filesystem that should be attached.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.
device_name 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}.
filesystem_id 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._{}]*.

MetadataOptions

Field Description
gce_http_endpoint enum MetadataOption
Enabled access to GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_endpoint enum MetadataOption
Enabled access to AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
gce_http_token enum MetadataOption
Enabled access to IAM credentials with GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_token enum MetadataOption
Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

ScalePolicy

Field Description
scale_type oneof: fixed_scale or auto_scale
  fixed_scale FixedScale
Manual scaling policy of the instance group.
  auto_scale AutoScale
Automatic scaling policy of the instance group.
test_auto_scale AutoScale
Test spec for automatic scaling policy of the instance group.

AutoScale

Field Description
min_zone_size int64
Lower limit for instance count in each zone. Acceptable values are 0 to 100, inclusive.
max_size int64
Upper limit for total instance count (across all zones). 0 means maximum limit = 100. Acceptable values are 0 to 100, inclusive.
measurement_duration google.protobuf.Duration
Time in seconds allotted for averaging metrics. 1 minute by default. Acceptable values are 1m to 10m, inclusive.
warmup_duration google.protobuf.Duration
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 10m.
stabilization_duration google.protobuf.Duration
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 1m to 30m, inclusive.
initial_size int64
Target group size. The minimum value is 1.
cpu_utilization_rule CpuUtilizationRule
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 (custom_rules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
custom_rules[] CustomRule
Defines an autoscaling rule based on a custom metric from Monitoring.
If more than one rule is specified, e.g. CPU utilization (cpu_utilization_rule) 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.
auto_scale_type enum AutoScaleType
Autoscaling type.
  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.

CpuUtilizationRule

Field Description
utilization_target double
Target CPU utilization level. Instance Groups maintains this level for each availability zone. Acceptable values are 10 to 100, inclusive.

CustomRule

Field Description
rule_type enum RuleType
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.
metric_type enum MetricType
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 AutoScale.measurement_duration 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 AutoScale.measurement_duration field.
metric_name 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}.
labels map<string,string>
Labels of custom metric in Monitoring that should be used for scaling. Each value must match the regular expression [a-zA-Z0-9./@_][0-9a-zA-Z./@_,:;()\\[\\]<>-]{0,198}. Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$.
target double
Target value for the custom metric. Instance Groups maintains this level for each availability zone. Value must be greater than 0.
folder_id string
Folder id of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 50.
service string
Service of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 200.

FixedScale

Field Description
size int64
Number of instances in the instance group. Acceptable values are 1 to 100, inclusive.

DeployPolicy

Field Description
max_unavailable 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 max_expansion is not specified or set to zero, max_unavailable must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
max_deleting 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.
max_creating 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.
max_expansion int64
The maximum number of instances that can be temporarily allocated above the group's target size during the update process. If max_unavailable is not specified or set to zero, max_expansion must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
startup_duration google.protobuf.Duration
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 yandex.cloud.compute.v1.instancegroup.ManagedInstance.Status for more information. Acceptable values are 0m to 1h, inclusive.
strategy enum Strategy
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.
minimal_action enum MinimalAction
If instance update requires a less disruptive action than minimal_action, Instance Groups performs minimal_action 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

Field Description
zones[] Zone
List of availability zones. The minimum number of elements is 1.

Zone

Field Description
zone_id string
Required. ID of the availability zone where the instance resides.
instance_tags_pool[] 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

Field Description
target_group_id string
ID of the Network Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

ManagedInstancesState

Field Description
target_size int64
Target number of instances for this instance group.
running_actual_count int64
The number of running instances that match the current instance template. For more information, see ManagedInstance.Status.RUNNING_ACTUAL.
running_outdated_count int64
The number of running instances that does not match the current instance template. For more information, see ManagedInstance.Status.RUNNING_OUTDATED.
processing_count int64
The number of instances in flight (for example, updating, starting, deleting). For more information, see ManagedInstance.Status.

Statuses

Field Description
creating int64
Instance is being created.
starting int64
Instance is being started.
opening int64
Instance is being opened to receive traffic.
warming int64
Instance is being warmed.
running int64
Instance is running normally.
closing int64
Instance is being closed to traffic.
stopping int64
Instance is being stopped.
updating int64
Instance is being updated.
deleting int64
Instance is being deleted.
failed int64
Instance failed and needs to be recreated.

LoadBalancerSpec

Field Description
target_group_spec TargetGroupSpec
Specification of the target group that the instance group will be added to. For more information, see Target groups and resources.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

TargetGroupSpec

Field Description
name string
Name of the target group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the target group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.

HealthChecksSpec

Field Description
health_check_specs[] HealthCheckSpec
Health checking specification. For more information, see Health check. The minimum number of elements is 1.
max_checking_health_duration google.protobuf.Duration
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 1s.

HealthCheckSpec

Field Description
interval google.protobuf.Duration
The interval between health checks. The default is 2 seconds. Acceptable values are 1s to 300s, inclusive.
timeout google.protobuf.Duration
Timeout for the managed instance to return a response for the health check. The default is 1 second. Acceptable values are 1s to 60s, inclusive.
unhealthy_threshold int64
The number of failed health checks for the managed instance to be considered unhealthy. The default (0) is 2. Value must be equal to 0,2,3,4,5,6,7,8,9,10.
healthy_threshold 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 equal to 0,2,3,4,5,6,7,8,9,10.
health_check_options oneof: tcp_options or http_options
  tcp_options TcpOptions
Configuration options for a TCP health check.
  http_options HttpOptions
Configuration options for an HTTP health check.

TcpOptions

Field Description
port int64
Port to use for TCP health checks. Acceptable values are 1 to 65535, inclusive.

HttpOptions

Field Description
port int64
Port to use for HTTP health checks. Acceptable values are 1 to 65535, inclusive.
path string
URL path to set for health checking requests.

Variable

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

ApplicationLoadBalancerSpec

Field Description
target_group_spec ApplicationTargetGroupSpec
Required. Basic properties of the Application Load Balancer target group attributed to the instance group.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

ApplicationTargetGroupSpec

Field Description
name string
Name of the target group.
description string
Description of the target group.
labels map<string,string>
Resource labels as key:value pairs.

ApplicationLoadBalancerState

Field Description
target_group_id string
ID of the Application Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

AutoHealingPolicy

Field Description
auto_healing_action enum AutoHealingAction
Instance Groups performs auto_healing_action 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

Start

Starts the specified instance group.

rpc Start (StartInstanceGroupRequest) returns (operation.Operation)

Metadata and response of Operation:

    Operation.metadata:StartInstanceGroupMetadata

    Operation.response:InstanceGroup

StartInstanceGroupRequest

Field Description
instance_group_id string
Required. ID of the instance group to start. To get the instance group ID, use a InstanceGroupService.List request. The maximum string length in characters is 50.

Operation

Field Description
id string
ID of the operation.
description string
Description of the operation. 0-256 characters long.
created_at google.protobuf.Timestamp
Creation timestamp.
created_by string
ID of the user or service account who initiated the operation.
modified_at google.protobuf.Timestamp
The time when the Operation resource was last modified.
done bool
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 google.protobuf.Any<StartInstanceGroupMetadata>
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.
result oneof: error or response
The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true, exactly one of error or response is set.
  error google.rpc.Status
The error result of the operation in case of failure or cancellation.
  response google.protobuf.Any<InstanceGroup>
if operation finished successfully.

StartInstanceGroupMetadata

Field Description
instance_group_id string
ID of the InstanceGroup resource that is being started.

InstanceGroup

Field Description
id string
ID of the instance group.
folder_id string
ID of the folder that the instance group belongs to.
created_at google.protobuf.Timestamp
Creation timestamp in RFC3339 text format.
name string
Name of the instance group. The name is unique within the folder.
description string
Description of the instance group.
labels map<string,string>
Resource labels as key:value pairs.
instance_template InstanceTemplate
Instance template for creating the instance group. For more information, see Instance Templates.
scale_policy ScalePolicy
Scaling policy of the instance group.
deploy_policy DeployPolicy
Deployment policy of the instance group.
allocation_policy AllocationPolicy
Allocation policy of the instance group by zones and regions.
load_balancer_state LoadBalancerState
Status of the Network Load Balancer target group attributed to the instance group.
managed_instances_state ManagedInstancesState
States of instances for this instance group.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
status enum Status
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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.ResumeProcesses. The group status will change to ACTIVE.
variables[] Variable
deletion_protection bool
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.
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
application_load_balancer_state ApplicationLoadBalancerState
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.
auto_healing_policy AutoHealingPolicy
AutoHealingPolicy policy of the instance group.

InstanceTemplate

Field Description
description string
Description of the instance template. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 128. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
platform_id 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.
resources_spec ResourcesSpec
Required. Computing resources of the instance such as the amount of memory and number of cores.
metadata map<string,string>
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 maximum string length in characters for each value is 262144. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_0-9a-z]*.
boot_disk_spec AttachedDiskSpec
Required. Boot disk specification that will be attached to the instance.
secondary_disk_specs[] AttachedDiskSpec
Array of secondary disks that will be attached to the instance. The maximum number of elements is 3.
network_interface_specs[] NetworkInterfaceSpec
Required. Array of network interfaces that will be attached to the instance.
scheduling_policy SchedulingPolicy
Scheduling policy for the instance.
service_account_id string
Service account ID for the instance.
network_settings NetworkSettings
Network settings for the instance.
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.
hostname string
Host name for the instance. This field is used to generate the yandex.cloud.compute.v1.Instance.fqdn value. The host name must be unique within the network and region. If not specified, the host name will be equal to yandex.cloud.compute.v1.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.
placement_policy PlacementPolicy
Placement Group
filesystem_specs[] AttachedFilesystemSpec
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.
metadata_options MetadataOptions
Metadata options for the instance

ResourcesSpec

Field Description
memory int64
The amount of memory available to the instance, specified in bytes. The maximum value is 824633720832.
cores int64
The number of cores available to the instance. Value must be equal to 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,80.
core_fraction 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 equal to 0,5,20,50,100.
gpus int64
The number of GPUs available to the instance. Value must be equal to 0,1,2,4.

AttachedDiskSpec

Field Description
mode enum Mode
Required. Access mode to the Disk resource.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
device_name 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}.
disk_spec DiskSpec
Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
disk_id 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._{}]*.
name string
When set can be later used to change DiskSpec of actual disk. The maximum string length in characters is 128.

DiskSpec

Field Description
description string
Description of the disk. The maximum string length in characters is 256.
type_id string
Required. ID of the disk type.
size int64
Size of the disk, specified in bytes. Acceptable values are 4194304 to 28587302322176, inclusive.
source_oneof oneof: image_id or snapshot_id
  image_id string
ID of the image that will be used for disk creation. The maximum string length in characters is 50.
  snapshot_id string
ID of the snapshot that will be used for disk creation. The maximum string length in characters is 50.
preserve_after_instance_delete bool
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.

NetworkInterfaceSpec

Field Description
network_id string
ID of the network.
subnet_ids[] string
IDs of the subnets.
primary_v4_address_spec PrimaryAddressSpec
Primary IPv4 address that is assigned to the instance for this network interface.
primary_v6_address_spec PrimaryAddressSpec
Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.
security_group_ids[] string
IDs of security groups.

PrimaryAddressSpec

Field Description
one_to_one_nat_spec OneToOneNatSpec
An external IP address configuration. If not specified, then this managed instance will have no external internet access.
dns_record_specs[] DnsRecordSpec
Internal DNS configuration
address string
Optional. Manual set static internal IP. To set use variables.

OneToOneNatSpec

Field Description
ip_version enum IpVersion
IP version for the public IP address.
  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
address string
Manual set static public IP. To set use variables. (optional)
dns_record_specs[] DnsRecordSpec
External DNS configuration

DnsRecordSpec

Field Description
fqdn string
Required. FQDN (required)
dns_zone_id string
DNS zone id (optional, if not set, private zone used)
ttl int64
DNS record ttl, values in 0-86400 (optional) Acceptable values are 0 to 86400, inclusive.
ptr bool
When set to true, also create PTR DNS record (optional)

SchedulingPolicy

Field Description
preemptible bool
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.

NetworkSettings

Field Description
type enum Type
Type of instance network.

PlacementPolicy

Field Description
placement_group_id string
Identifier of placement group
host_affinity_rules[] HostAffinityRule
List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

HostAffinityRule

Field Description
key string
Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'
op enum Operator
Include or exclude action
values[] string
Affinity value or host ID or host group ID

AttachedFilesystemSpec

Field Description
mode enum Mode
Mode of access to the filesystem that should be attached.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.
device_name 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}.
filesystem_id 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._{}]*.

MetadataOptions

Field Description
gce_http_endpoint enum MetadataOption
Enabled access to GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_endpoint enum MetadataOption
Enabled access to AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
gce_http_token enum MetadataOption
Enabled access to IAM credentials with GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_token enum MetadataOption
Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

ScalePolicy

Field Description
scale_type oneof: fixed_scale or auto_scale
  fixed_scale FixedScale
Manual scaling policy of the instance group.
  auto_scale AutoScale
Automatic scaling policy of the instance group.
test_auto_scale AutoScale
Test spec for automatic scaling policy of the instance group.

AutoScale

Field Description
min_zone_size int64
Lower limit for instance count in each zone. Acceptable values are 0 to 100, inclusive.
max_size int64
Upper limit for total instance count (across all zones). 0 means maximum limit = 100. Acceptable values are 0 to 100, inclusive.
measurement_duration google.protobuf.Duration
Time in seconds allotted for averaging metrics. 1 minute by default. Acceptable values are 1m to 10m, inclusive.
warmup_duration google.protobuf.Duration
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 10m.
stabilization_duration google.protobuf.Duration
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 1m to 30m, inclusive.
initial_size int64
Target group size. The minimum value is 1.
cpu_utilization_rule CpuUtilizationRule
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 (custom_rules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
custom_rules[] CustomRule
Defines an autoscaling rule based on a custom metric from Monitoring.
If more than one rule is specified, e.g. CPU utilization (cpu_utilization_rule) 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.
auto_scale_type enum AutoScaleType
Autoscaling type.
  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.

CpuUtilizationRule

Field Description
utilization_target double
Target CPU utilization level. Instance Groups maintains this level for each availability zone. Acceptable values are 10 to 100, inclusive.

CustomRule

Field Description
rule_type enum RuleType
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.
metric_type enum MetricType
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 AutoScale.measurement_duration 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 AutoScale.measurement_duration field.
metric_name 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}.
labels map<string,string>
Labels of custom metric in Monitoring that should be used for scaling. Each value must match the regular expression [a-zA-Z0-9./@_][0-9a-zA-Z./@_,:;()\\[\\]<>-]{0,198}. Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$.
target double
Target value for the custom metric. Instance Groups maintains this level for each availability zone. Value must be greater than 0.
folder_id string
Folder id of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 50.
service string
Service of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 200.

FixedScale

Field Description
size int64
Number of instances in the instance group. Acceptable values are 1 to 100, inclusive.

DeployPolicy

Field Description
max_unavailable 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 max_expansion is not specified or set to zero, max_unavailable must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
max_deleting 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.
max_creating 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.
max_expansion int64
The maximum number of instances that can be temporarily allocated above the group's target size during the update process. If max_unavailable is not specified or set to zero, max_expansion must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
startup_duration google.protobuf.Duration
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 yandex.cloud.compute.v1.instancegroup.ManagedInstance.Status for more information. Acceptable values are 0m to 1h, inclusive.
strategy enum Strategy
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.
minimal_action enum MinimalAction
If instance update requires a less disruptive action than minimal_action, Instance Groups performs minimal_action 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

Field Description
zones[] Zone
List of availability zones. The minimum number of elements is 1.

Zone

Field Description
zone_id string
Required. ID of the availability zone where the instance resides.
instance_tags_pool[] 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

Field Description
target_group_id string
ID of the Network Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

ManagedInstancesState

Field Description
target_size int64
Target number of instances for this instance group.
running_actual_count int64
The number of running instances that match the current instance template. For more information, see ManagedInstance.Status.RUNNING_ACTUAL.
running_outdated_count int64
The number of running instances that does not match the current instance template. For more information, see ManagedInstance.Status.RUNNING_OUTDATED.
processing_count int64
The number of instances in flight (for example, updating, starting, deleting). For more information, see ManagedInstance.Status.

Statuses

Field Description
creating int64
Instance is being created.
starting int64
Instance is being started.
opening int64
Instance is being opened to receive traffic.
warming int64
Instance is being warmed.
running int64
Instance is running normally.
closing int64
Instance is being closed to traffic.
stopping int64
Instance is being stopped.
updating int64
Instance is being updated.
deleting int64
Instance is being deleted.
failed int64
Instance failed and needs to be recreated.

LoadBalancerSpec

Field Description
target_group_spec TargetGroupSpec
Specification of the target group that the instance group will be added to. For more information, see Target groups and resources.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

TargetGroupSpec

Field Description
name string
Name of the target group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the target group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.

HealthChecksSpec

Field Description
health_check_specs[] HealthCheckSpec
Health checking specification. For more information, see Health check. The minimum number of elements is 1.
max_checking_health_duration google.protobuf.Duration
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 1s.

HealthCheckSpec

Field Description
interval google.protobuf.Duration
The interval between health checks. The default is 2 seconds. Acceptable values are 1s to 300s, inclusive.
timeout google.protobuf.Duration
Timeout for the managed instance to return a response for the health check. The default is 1 second. Acceptable values are 1s to 60s, inclusive.
unhealthy_threshold int64
The number of failed health checks for the managed instance to be considered unhealthy. The default (0) is 2. Value must be equal to 0,2,3,4,5,6,7,8,9,10.
healthy_threshold 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 equal to 0,2,3,4,5,6,7,8,9,10.
health_check_options oneof: tcp_options or http_options
  tcp_options TcpOptions
Configuration options for a TCP health check.
  http_options HttpOptions
Configuration options for an HTTP health check.

TcpOptions

Field Description
port int64
Port to use for TCP health checks. Acceptable values are 1 to 65535, inclusive.

HttpOptions

Field Description
port int64
Port to use for HTTP health checks. Acceptable values are 1 to 65535, inclusive.
path string
URL path to set for health checking requests.

Variable

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

ApplicationLoadBalancerSpec

Field Description
target_group_spec ApplicationTargetGroupSpec
Required. Basic properties of the Application Load Balancer target group attributed to the instance group.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

ApplicationTargetGroupSpec

Field Description
name string
Name of the target group.
description string
Description of the target group.
labels map<string,string>
Resource labels as key:value pairs.

ApplicationLoadBalancerState

Field Description
target_group_id string
ID of the Application Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

AutoHealingPolicy

Field Description
auto_healing_action enum AutoHealingAction
Instance Groups performs auto_healing_action 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

Delete

Deletes the specified instance group.

rpc Delete (DeleteInstanceGroupRequest) returns (operation.Operation)

Metadata and response of Operation:

    Operation.metadata:DeleteInstanceGroupMetadata

    Operation.response:google.protobuf.Empty

DeleteInstanceGroupRequest

Field Description
instance_group_id string
Required. ID of the instance group to delete. To get the instance group ID, use a InstanceGroupService.List request. The maximum string length in characters is 50.

Operation

Field Description
id string
ID of the operation.
description string
Description of the operation. 0-256 characters long.
created_at google.protobuf.Timestamp
Creation timestamp.
created_by string
ID of the user or service account who initiated the operation.
modified_at google.protobuf.Timestamp
The time when the Operation resource was last modified.
done bool
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 google.protobuf.Any<DeleteInstanceGroupMetadata>
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.
result oneof: error or response
The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true, exactly one of error or response is set.
  error google.rpc.Status
The error result of the operation in case of failure or cancellation.
  response google.protobuf.Any<google.protobuf.Empty>
if operation finished successfully.

DeleteInstanceGroupMetadata

Field Description
instance_group_id string
ID of the instance group that is being deleted. To get the instance group ID, use a InstanceGroupService.List request.

ListInstances

Lists instances for the specified instance group.

rpc ListInstances (ListInstanceGroupInstancesRequest) returns (ListInstanceGroupInstancesResponse)

ListInstanceGroupInstancesRequest

Field Description
instance_group_id string
Required. ID of the InstanceGroup resource to list instances for. To get the instance group ID, use a InstanceGroupService.List request. The maximum string length in characters is 50.
page_size int64
The maximum number of results per page to return. If the number of available results is larger than page_size, the service returns a ListInstanceGroupInstancesResponse.next_page_token that can be used to get the next page of results in subsequent list requests. The maximum value is 1000.
page_token string
Page token. To get the next page of results, set page_token to the ListInstanceGroupInstancesResponse.next_page_token returned by a previous list request. The maximum string length in characters is 1000.
filter string
A filter expression that filters resources listed in the response. Currently you can use filtering only on the ManagedInstance.name field. The maximum string length in characters is 1000.

ListInstanceGroupInstancesResponse

Field Description
instances[] ManagedInstance
Lists instances for the specified instance group.
next_page_token string
This token allows you to get the next page of results for list requests. If the number of results is more than ListInstanceGroupInstancesRequest.page_size, use next_page_token as the value for the ListInstanceGroupInstancesRequest.page_token query parameter in the next list request. Each subsequent list request will have its own next_page_token to continue paging through the results.

ManagedInstance

Field Description
id string
ID of the managed instance.
status enum Status
Status of the managed instance.
  • CREATING_INSTANCE: Instance is being created.
  • UPDATING_INSTANCE: Instance is being updated.
  • DELETING_INSTANCE: Instance is being deleted.
  • STARTING_INSTANCE: Instance is being started.
  • STOPPING_INSTANCE: Instance is being stopped.
  • AWAITING_STARTUP_DURATION: Instance has been created successfully, but startup duration has not elapsed yet.
  • CHECKING_HEALTH: Instance has been created successfully and startup duration has elapsed, but health checks have not passed yet and the managed instance is not ready to receive traffic.
  • OPENING_TRAFFIC: Instance Groups is initiating health checks and routing traffic to the instances.
  • AWAITING_WARMUP_DURATION: Instance is now receiving traffic, but warmup duration has not elapsed yet.
  • CLOSING_TRAFFIC: Instance Groups has initiated the process of stopping routing traffic to the instances.
  • RUNNING_ACTUAL: Instance is running normally and its attributes match the current InstanceTemplate.
  • RUNNING_OUTDATED: Instance is running normally, but its attributes do not match the current InstanceTemplate. It will be updated, recreated or deleted shortly.
  • STOPPED: Instance was stopped.
  • DELETED: Instance was deleted.
  • PREPARING_RESOURCES: Instance Groups is preparing dependent resources.
instance_id string
ID of the instance.
fqdn string
Fully Qualified Domain Name.
name string
The name of the managed instance.
status_message string
Status message for the managed instance.
zone_id string
ID of the availability zone where the instance resides.
network_interfaces[] NetworkInterface
Array of network interfaces that are attached to the managed instance.
status_changed_at google.protobuf.Timestamp
The timestamp in RFC3339 text format when the status of the managed instance was last changed.
instance_tag string
Managed instance tag.

NetworkInterface

Field Description
index string
The index of the network interface, generated by the server, 0,1,2... etc.
mac_address string
MAC address that is assigned to the network interface.
subnet_id string
ID of the subnet.
primary_v4_address PrimaryAddress
Primary IPv4 address that is assigned to the instance for this network interface.
primary_v6_address PrimaryAddress
Primary IPv6 address that is assigned to the instance for this network interface. IPv6 is not available yet.

PrimaryAddress

Field Description
address string
An IPv4 internal network address that is assigned to the managed instance for this network interface. If not specified by the user, an unused internal IP is assigned by the system.
one_to_one_nat OneToOneNat
One-to-one NAT configuration. If missing, NAT has not been set up.
dns_records[] DnsRecord
Internal DNS configuration.

OneToOneNat

Field Description
address string
An IPv4 external network address that is assigned to the managed instance for this network interface.
ip_version enum IpVersion
External IP address version.
  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
dns_records[] DnsRecord
External DNS configuration.

DnsRecord

Field Description
fqdn string
Required. Name of the A/AAAA record as specified when creating the instance. Note that if `fqdn' has no trailing '.', it is specified relative to the zone (@see dns_zone_id).
dns_zone_id string
DNS zone id (optional, if not set, some private zone is used).
ttl int64
DNS record ttl (optional, if 0, a reasonable default is used). Acceptable values are 0 to 86400, inclusive.
ptr bool
When true, indicates there is a corresponding auto-created PTR DNS record.

DeleteInstances

Delete instances from the instance group.

rpc DeleteInstances (DeleteInstancesRequest) returns (operation.Operation)

Metadata and response of Operation:

    Operation.metadata:DeleteInstancesMetadata

    Operation.response:InstanceGroup

DeleteInstancesRequest

Field Description
instance_group_id string
Required. ID of the instance group that the instances are being deleted from. To get the ID of the instance group, use the InstanceGroupService.List request. The maximum string length in characters is 50.
managed_instance_ids[] string
IDs of the instances to delete. Instances will be deleted along with all dependent resources. Only IDs from the ManagedInstance.id field are allowed, not ManagedInstance.instance_id. The minimum number of elements is 1. The maximum string length in characters for each value is 50.
create_another bool
If set to true, the target size of instance group will not be reduced and a new instance will be created instead of the deleted one. By default, the target size of instance group will be reduced by the specified number of instance IDs.

Operation

Field Description
id string
ID of the operation.
description string
Description of the operation. 0-256 characters long.
created_at google.protobuf.Timestamp
Creation timestamp.
created_by string
ID of the user or service account who initiated the operation.
modified_at google.protobuf.Timestamp
The time when the Operation resource was last modified.
done bool
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 google.protobuf.Any<DeleteInstancesMetadata>
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.
result oneof: error or response
The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true, exactly one of error or response is set.
  error google.rpc.Status
The error result of the operation in case of failure or cancellation.
  response google.protobuf.Any<InstanceGroup>
if operation finished successfully.

DeleteInstancesMetadata

Field Description
instance_group_id string
ID of the instance group that the instances are being deleted from.

InstanceGroup

Field Description
id string
ID of the instance group.
folder_id string
ID of the folder that the instance group belongs to.
created_at google.protobuf.Timestamp
Creation timestamp in RFC3339 text format.
name string
Name of the instance group. The name is unique within the folder.
description string
Description of the instance group.
labels map<string,string>
Resource labels as key:value pairs.
instance_template InstanceTemplate
Instance template for creating the instance group. For more information, see Instance Templates.
scale_policy ScalePolicy
Scaling policy of the instance group.
deploy_policy DeployPolicy
Deployment policy of the instance group.
allocation_policy AllocationPolicy
Allocation policy of the instance group by zones and regions.
load_balancer_state LoadBalancerState
Status of the Network Load Balancer target group attributed to the instance group.
managed_instances_state ManagedInstancesState
States of instances for this instance group.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
status enum Status
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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.ResumeProcesses. The group status will change to ACTIVE.
variables[] Variable
deletion_protection bool
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.
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
application_load_balancer_state ApplicationLoadBalancerState
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.
auto_healing_policy AutoHealingPolicy
AutoHealingPolicy policy of the instance group.

InstanceTemplate

Field Description
description string
Description of the instance template. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 128. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
platform_id 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.
resources_spec ResourcesSpec
Required. Computing resources of the instance such as the amount of memory and number of cores.
metadata map<string,string>
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 maximum string length in characters for each value is 262144. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_0-9a-z]*.
boot_disk_spec AttachedDiskSpec
Required. Boot disk specification that will be attached to the instance.
secondary_disk_specs[] AttachedDiskSpec
Array of secondary disks that will be attached to the instance. The maximum number of elements is 3.
network_interface_specs[] NetworkInterfaceSpec
Required. Array of network interfaces that will be attached to the instance.
scheduling_policy SchedulingPolicy
Scheduling policy for the instance.
service_account_id string
Service account ID for the instance.
network_settings NetworkSettings
Network settings for the instance.
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.
hostname string
Host name for the instance. This field is used to generate the yandex.cloud.compute.v1.Instance.fqdn value. The host name must be unique within the network and region. If not specified, the host name will be equal to yandex.cloud.compute.v1.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.
placement_policy PlacementPolicy
Placement Group
filesystem_specs[] AttachedFilesystemSpec
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.
metadata_options MetadataOptions
Metadata options for the instance

ResourcesSpec

Field Description
memory int64
The amount of memory available to the instance, specified in bytes. The maximum value is 824633720832.
cores int64
The number of cores available to the instance. Value must be equal to 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,80.
core_fraction 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 equal to 0,5,20,50,100.
gpus int64
The number of GPUs available to the instance. Value must be equal to 0,1,2,4.

AttachedDiskSpec

Field Description
mode enum Mode
Required. Access mode to the Disk resource.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
device_name 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}.
disk_spec DiskSpec
Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
disk_id 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._{}]*.
name string
When set can be later used to change DiskSpec of actual disk. The maximum string length in characters is 128.

DiskSpec

Field Description
description string
Description of the disk. The maximum string length in characters is 256.
type_id string
Required. ID of the disk type.
size int64
Size of the disk, specified in bytes. Acceptable values are 4194304 to 28587302322176, inclusive.
source_oneof oneof: image_id or snapshot_id
  image_id string
ID of the image that will be used for disk creation. The maximum string length in characters is 50.
  snapshot_id string
ID of the snapshot that will be used for disk creation. The maximum string length in characters is 50.
preserve_after_instance_delete bool
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.

NetworkInterfaceSpec

Field Description
network_id string
ID of the network.
subnet_ids[] string
IDs of the subnets.
primary_v4_address_spec PrimaryAddressSpec
Primary IPv4 address that is assigned to the instance for this network interface.
primary_v6_address_spec PrimaryAddressSpec
Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.
security_group_ids[] string
IDs of security groups.

PrimaryAddressSpec

Field Description
one_to_one_nat_spec OneToOneNatSpec
An external IP address configuration. If not specified, then this managed instance will have no external internet access.
dns_record_specs[] DnsRecordSpec
Internal DNS configuration
address string
Optional. Manual set static internal IP. To set use variables.

OneToOneNatSpec

Field Description
ip_version enum IpVersion
IP version for the public IP address.
  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
address string
Manual set static public IP. To set use variables. (optional)
dns_record_specs[] DnsRecordSpec
External DNS configuration

DnsRecordSpec

Field Description
fqdn string
Required. FQDN (required)
dns_zone_id string
DNS zone id (optional, if not set, private zone used)
ttl int64
DNS record ttl, values in 0-86400 (optional) Acceptable values are 0 to 86400, inclusive.
ptr bool
When set to true, also create PTR DNS record (optional)

SchedulingPolicy

Field Description
preemptible bool
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.

NetworkSettings

Field Description
type enum Type
Type of instance network.

PlacementPolicy

Field Description
placement_group_id string
Identifier of placement group
host_affinity_rules[] HostAffinityRule
List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

HostAffinityRule

Field Description
key string
Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'
op enum Operator
Include or exclude action
values[] string
Affinity value or host ID or host group ID

AttachedFilesystemSpec

Field Description
mode enum Mode
Mode of access to the filesystem that should be attached.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.
device_name 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}.
filesystem_id 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._{}]*.

MetadataOptions

Field Description
gce_http_endpoint enum MetadataOption
Enabled access to GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_endpoint enum MetadataOption
Enabled access to AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
gce_http_token enum MetadataOption
Enabled access to IAM credentials with GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_token enum MetadataOption
Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

ScalePolicy

Field Description
scale_type oneof: fixed_scale or auto_scale
  fixed_scale FixedScale
Manual scaling policy of the instance group.
  auto_scale AutoScale
Automatic scaling policy of the instance group.
test_auto_scale AutoScale
Test spec for automatic scaling policy of the instance group.

AutoScale

Field Description
min_zone_size int64
Lower limit for instance count in each zone. Acceptable values are 0 to 100, inclusive.
max_size int64
Upper limit for total instance count (across all zones). 0 means maximum limit = 100. Acceptable values are 0 to 100, inclusive.
measurement_duration google.protobuf.Duration
Time in seconds allotted for averaging metrics. 1 minute by default. Acceptable values are 1m to 10m, inclusive.
warmup_duration google.protobuf.Duration
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 10m.
stabilization_duration google.protobuf.Duration
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 1m to 30m, inclusive.
initial_size int64
Target group size. The minimum value is 1.
cpu_utilization_rule CpuUtilizationRule
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 (custom_rules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
custom_rules[] CustomRule
Defines an autoscaling rule based on a custom metric from Monitoring.
If more than one rule is specified, e.g. CPU utilization (cpu_utilization_rule) 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.
auto_scale_type enum AutoScaleType
Autoscaling type.
  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.

CpuUtilizationRule

Field Description
utilization_target double
Target CPU utilization level. Instance Groups maintains this level for each availability zone. Acceptable values are 10 to 100, inclusive.

CustomRule

Field Description
rule_type enum RuleType
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.
metric_type enum MetricType
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 AutoScale.measurement_duration 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 AutoScale.measurement_duration field.
metric_name 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}.
labels map<string,string>
Labels of custom metric in Monitoring that should be used for scaling. Each value must match the regular expression [a-zA-Z0-9./@_][0-9a-zA-Z./@_,:;()\\[\\]<>-]{0,198}. Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$.
target double
Target value for the custom metric. Instance Groups maintains this level for each availability zone. Value must be greater than 0.
folder_id string
Folder id of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 50.
service string
Service of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 200.

FixedScale

Field Description
size int64
Number of instances in the instance group. Acceptable values are 1 to 100, inclusive.

DeployPolicy

Field Description
max_unavailable 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 max_expansion is not specified or set to zero, max_unavailable must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
max_deleting 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.
max_creating 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.
max_expansion int64
The maximum number of instances that can be temporarily allocated above the group's target size during the update process. If max_unavailable is not specified or set to zero, max_expansion must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
startup_duration google.protobuf.Duration
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 yandex.cloud.compute.v1.instancegroup.ManagedInstance.Status for more information. Acceptable values are 0m to 1h, inclusive.
strategy enum Strategy
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.
minimal_action enum MinimalAction
If instance update requires a less disruptive action than minimal_action, Instance Groups performs minimal_action 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

Field Description
zones[] Zone
List of availability zones. The minimum number of elements is 1.

Zone

Field Description
zone_id string
Required. ID of the availability zone where the instance resides.
instance_tags_pool[] 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

Field Description
target_group_id string
ID of the Network Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

ManagedInstancesState

Field Description
target_size int64
Target number of instances for this instance group.
running_actual_count int64
The number of running instances that match the current instance template. For more information, see ManagedInstance.Status.RUNNING_ACTUAL.
running_outdated_count int64
The number of running instances that does not match the current instance template. For more information, see ManagedInstance.Status.RUNNING_OUTDATED.
processing_count int64
The number of instances in flight (for example, updating, starting, deleting). For more information, see ManagedInstance.Status.

Statuses

Field Description
creating int64
Instance is being created.
starting int64
Instance is being started.
opening int64
Instance is being opened to receive traffic.
warming int64
Instance is being warmed.
running int64
Instance is running normally.
closing int64
Instance is being closed to traffic.
stopping int64
Instance is being stopped.
updating int64
Instance is being updated.
deleting int64
Instance is being deleted.
failed int64
Instance failed and needs to be recreated.

LoadBalancerSpec

Field Description
target_group_spec TargetGroupSpec
Specification of the target group that the instance group will be added to. For more information, see Target groups and resources.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

TargetGroupSpec

Field Description
name string
Name of the target group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the target group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.

HealthChecksSpec

Field Description
health_check_specs[] HealthCheckSpec
Health checking specification. For more information, see Health check. The minimum number of elements is 1.
max_checking_health_duration google.protobuf.Duration
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 1s.

HealthCheckSpec

Field Description
interval google.protobuf.Duration
The interval between health checks. The default is 2 seconds. Acceptable values are 1s to 300s, inclusive.
timeout google.protobuf.Duration
Timeout for the managed instance to return a response for the health check. The default is 1 second. Acceptable values are 1s to 60s, inclusive.
unhealthy_threshold int64
The number of failed health checks for the managed instance to be considered unhealthy. The default (0) is 2. Value must be equal to 0,2,3,4,5,6,7,8,9,10.
healthy_threshold 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 equal to 0,2,3,4,5,6,7,8,9,10.
health_check_options oneof: tcp_options or http_options
  tcp_options TcpOptions
Configuration options for a TCP health check.
  http_options HttpOptions
Configuration options for an HTTP health check.

TcpOptions

Field Description
port int64
Port to use for TCP health checks. Acceptable values are 1 to 65535, inclusive.

HttpOptions

Field Description
port int64
Port to use for HTTP health checks. Acceptable values are 1 to 65535, inclusive.
path string
URL path to set for health checking requests.

Variable

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

ApplicationLoadBalancerSpec

Field Description
target_group_spec ApplicationTargetGroupSpec
Required. Basic properties of the Application Load Balancer target group attributed to the instance group.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

ApplicationTargetGroupSpec

Field Description
name string
Name of the target group.
description string
Description of the target group.
labels map<string,string>
Resource labels as key:value pairs.

ApplicationLoadBalancerState

Field Description
target_group_id string
ID of the Application Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

AutoHealingPolicy

Field Description
auto_healing_action enum AutoHealingAction
Instance Groups performs auto_healing_action 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

StopInstances

Stop instances from the instance group.

rpc StopInstances (StopInstancesRequest) returns (operation.Operation)

Metadata and response of Operation:

    Operation.metadata:StopInstancesMetadata

    Operation.response:InstanceGroup

StopInstancesRequest

Field Description
instance_group_id string
Required. ID of the instance group that the instances are being stopped from. To get the ID of the instance group, use the InstanceGroupService.List request. The maximum string length in characters is 50.
managed_instance_ids[] string
IDs of the instances to stop. After stopping, the instance can be updated, started, or deleted according to scale and deploy policies. Only IDs from the ManagedInstance.id field are allowed, not ManagedInstance.instance_id. The minimum number of elements is 1. The maximum string length in characters for each value is 50.

Operation

Field Description
id string
ID of the operation.
description string
Description of the operation. 0-256 characters long.
created_at google.protobuf.Timestamp
Creation timestamp.
created_by string
ID of the user or service account who initiated the operation.
modified_at google.protobuf.Timestamp
The time when the Operation resource was last modified.
done bool
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 google.protobuf.Any<StopInstancesMetadata>
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.
result oneof: error or response
The operation result. If done == false and there was no failure detected, neither error nor response is set. If done == false and there was a failure detected, error is set. If done == true, exactly one of error or response is set.
  error google.rpc.Status
The error result of the operation in case of failure or cancellation.
  response google.protobuf.Any<InstanceGroup>
if operation finished successfully.

StopInstancesMetadata

Field Description
instance_group_id string
ID of the instance group that the instances are being stopped from.

InstanceGroup

Field Description
id string
ID of the instance group.
folder_id string
ID of the folder that the instance group belongs to.
created_at google.protobuf.Timestamp
Creation timestamp in RFC3339 text format.
name string
Name of the instance group. The name is unique within the folder.
description string
Description of the instance group.
labels map<string,string>
Resource labels as key:value pairs.
instance_template InstanceTemplate
Instance template for creating the instance group. For more information, see Instance Templates.
scale_policy ScalePolicy
Scaling policy of the instance group.
deploy_policy DeployPolicy
Deployment policy of the instance group.
allocation_policy AllocationPolicy
Allocation policy of the instance group by zones and regions.
load_balancer_state LoadBalancerState
Status of the Network Load Balancer target group attributed to the instance group.
managed_instances_state ManagedInstancesState
States of instances for this instance group.
load_balancer_spec LoadBalancerSpec
Settings for balancing load between instances via Network Load Balancer (OSI model layer 3).
health_checks_spec HealthChecksSpec
Health checking specification. For more information, see Health check.
service_account_id 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 yandex.cloud.iam.v1.ServiceAccountService.List request.
status enum Status
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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.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 yandex.cloud.compute.v1.instancegroup.InstanceGroupService.ResumeProcesses. The group status will change to ACTIVE.
variables[] Variable
deletion_protection bool
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.
application_load_balancer_spec ApplicationLoadBalancerSpec
Settings for balancing load between instances via Application Load Balancer (OSI model layer 7).
application_load_balancer_state ApplicationLoadBalancerState
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.
auto_healing_policy AutoHealingPolicy
AutoHealingPolicy policy of the instance group.

InstanceTemplate

Field Description
description string
Description of the instance template. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 128. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.
platform_id 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.
resources_spec ResourcesSpec
Required. Computing resources of the instance such as the amount of memory and number of cores.
metadata map<string,string>
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 maximum string length in characters for each value is 262144. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_0-9a-z]*.
boot_disk_spec AttachedDiskSpec
Required. Boot disk specification that will be attached to the instance.
secondary_disk_specs[] AttachedDiskSpec
Array of secondary disks that will be attached to the instance. The maximum number of elements is 3.
network_interface_specs[] NetworkInterfaceSpec
Required. Array of network interfaces that will be attached to the instance.
scheduling_policy SchedulingPolicy
Scheduling policy for the instance.
service_account_id string
Service account ID for the instance.
network_settings NetworkSettings
Network settings for the instance.
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.
hostname string
Host name for the instance. This field is used to generate the yandex.cloud.compute.v1.Instance.fqdn value. The host name must be unique within the network and region. If not specified, the host name will be equal to yandex.cloud.compute.v1.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.
placement_policy PlacementPolicy
Placement Group
filesystem_specs[] AttachedFilesystemSpec
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.
metadata_options MetadataOptions
Metadata options for the instance

ResourcesSpec

Field Description
memory int64
The amount of memory available to the instance, specified in bytes. The maximum value is 824633720832.
cores int64
The number of cores available to the instance. Value must be equal to 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,80.
core_fraction 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 equal to 0,5,20,50,100.
gpus int64
The number of GPUs available to the instance. Value must be equal to 0,1,2,4.

AttachedDiskSpec

Field Description
mode enum Mode
Required. Access mode to the Disk resource.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access.
device_name 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}.
disk_spec DiskSpec
Required. oneof disk_spec or disk_id Disk specification that is attached to the instance. For more information, see Disks.
disk_id 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._{}]*.
name string
When set can be later used to change DiskSpec of actual disk. The maximum string length in characters is 128.

DiskSpec

Field Description
description string
Description of the disk. The maximum string length in characters is 256.
type_id string
Required. ID of the disk type.
size int64
Size of the disk, specified in bytes. Acceptable values are 4194304 to 28587302322176, inclusive.
source_oneof oneof: image_id or snapshot_id
  image_id string
ID of the image that will be used for disk creation. The maximum string length in characters is 50.
  snapshot_id string
ID of the snapshot that will be used for disk creation. The maximum string length in characters is 50.
preserve_after_instance_delete bool
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.

NetworkInterfaceSpec

Field Description
network_id string
ID of the network.
subnet_ids[] string
IDs of the subnets.
primary_v4_address_spec PrimaryAddressSpec
Primary IPv4 address that is assigned to the instance for this network interface.
primary_v6_address_spec PrimaryAddressSpec
Primary IPv6 address that is assigned to the instance for this network interface. IPv6 not available yet.
security_group_ids[] string
IDs of security groups.

PrimaryAddressSpec

Field Description
one_to_one_nat_spec OneToOneNatSpec
An external IP address configuration. If not specified, then this managed instance will have no external internet access.
dns_record_specs[] DnsRecordSpec
Internal DNS configuration
address string
Optional. Manual set static internal IP. To set use variables.

OneToOneNatSpec

Field Description
ip_version enum IpVersion
IP version for the public IP address.
  • IPV4: IPv4 address, for example 192.168.0.0.
  • IPV6: IPv6 address, not available yet.
address string
Manual set static public IP. To set use variables. (optional)
dns_record_specs[] DnsRecordSpec
External DNS configuration

DnsRecordSpec

Field Description
fqdn string
Required. FQDN (required)
dns_zone_id string
DNS zone id (optional, if not set, private zone used)
ttl int64
DNS record ttl, values in 0-86400 (optional) Acceptable values are 0 to 86400, inclusive.
ptr bool
When set to true, also create PTR DNS record (optional)

SchedulingPolicy

Field Description
preemptible bool
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.

NetworkSettings

Field Description
type enum Type
Type of instance network.

PlacementPolicy

Field Description
placement_group_id string
Identifier of placement group
host_affinity_rules[] HostAffinityRule
List of affinity rules. Scheduler will attempt to allocate instances according to order of rules.

HostAffinityRule

Field Description
key string
Affinity label or one of reserved values - 'yc.hostId', 'yc.hostGroupId'
op enum Operator
Include or exclude action
values[] string
Affinity value or host ID or host group ID

AttachedFilesystemSpec

Field Description
mode enum Mode
Mode of access to the filesystem that should be attached.
  • READ_ONLY: Read-only access.
  • READ_WRITE: Read/Write access. Default value.
device_name 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}.
filesystem_id 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._{}]*.

MetadataOptions

Field Description
gce_http_endpoint enum MetadataOption
Enabled access to GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_endpoint enum MetadataOption
Enabled access to AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
gce_http_token enum MetadataOption
Enabled access to IAM credentials with GCE flavored metadata
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled
aws_v1_http_token enum MetadataOption
Enabled access to IAM credentials with AWS flavored metadata (IMDSv1)
  • ENABLED: Option is enabled
  • DISABLED: Option is disabled

ScalePolicy

Field Description
scale_type oneof: fixed_scale or auto_scale
  fixed_scale FixedScale
Manual scaling policy of the instance group.
  auto_scale AutoScale
Automatic scaling policy of the instance group.
test_auto_scale AutoScale
Test spec for automatic scaling policy of the instance group.

AutoScale

Field Description
min_zone_size int64
Lower limit for instance count in each zone. Acceptable values are 0 to 100, inclusive.
max_size int64
Upper limit for total instance count (across all zones). 0 means maximum limit = 100. Acceptable values are 0 to 100, inclusive.
measurement_duration google.protobuf.Duration
Time in seconds allotted for averaging metrics. 1 minute by default. Acceptable values are 1m to 10m, inclusive.
warmup_duration google.protobuf.Duration
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 10m.
stabilization_duration google.protobuf.Duration
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 1m to 30m, inclusive.
initial_size int64
Target group size. The minimum value is 1.
cpu_utilization_rule CpuUtilizationRule
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 (custom_rules), the size of the instance group will be equal to the maximum of sizes calculated according to each metric.
custom_rules[] CustomRule
Defines an autoscaling rule based on a custom metric from Monitoring.
If more than one rule is specified, e.g. CPU utilization (cpu_utilization_rule) 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.
auto_scale_type enum AutoScaleType
Autoscaling type.
  • ZONAL: Scale each zone independently. This is the default.
  • REGIONAL: Scale group as a whole.

CpuUtilizationRule

Field Description
utilization_target double
Target CPU utilization level. Instance Groups maintains this level for each availability zone. Acceptable values are 10 to 100, inclusive.

CustomRule

Field Description
rule_type enum RuleType
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.
metric_type enum MetricType
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 AutoScale.measurement_duration 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 AutoScale.measurement_duration field.
metric_name 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}.
labels map<string,string>
Labels of custom metric in Monitoring that should be used for scaling. Each value must match the regular expression [a-zA-Z0-9./@_][0-9a-zA-Z./@_,:;()\\[\\]<>-]{0,198}. Each key must match the regular expression ^[a-zA-Z][0-9a-zA-Z_]{0,31}$.
target double
Target value for the custom metric. Instance Groups maintains this level for each availability zone. Value must be greater than 0.
folder_id string
Folder id of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 50.
service string
Service of custom metric in Monitoring that should be used for scaling. The maximum string length in characters is 200.

FixedScale

Field Description
size int64
Number of instances in the instance group. Acceptable values are 1 to 100, inclusive.

DeployPolicy

Field Description
max_unavailable 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 max_expansion is not specified or set to zero, max_unavailable must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
max_deleting 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.
max_creating 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.
max_expansion int64
The maximum number of instances that can be temporarily allocated above the group's target size during the update process. If max_unavailable is not specified or set to zero, max_expansion must be set to a non-zero value. Acceptable values are 0 to 100, inclusive.
startup_duration google.protobuf.Duration
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 yandex.cloud.compute.v1.instancegroup.ManagedInstance.Status for more information. Acceptable values are 0m to 1h, inclusive.
strategy enum Strategy
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.
minimal_action enum MinimalAction
If instance update requires a less disruptive action than minimal_action, Instance Groups performs minimal_action 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

Field Description
zones[] Zone
List of availability zones. The minimum number of elements is 1.

Zone

Field Description
zone_id string
Required. ID of the availability zone where the instance resides.
instance_tags_pool[] 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

Field Description
target_group_id string
ID of the Network Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

ManagedInstancesState

Field Description
target_size int64
Target number of instances for this instance group.
running_actual_count int64
The number of running instances that match the current instance template. For more information, see ManagedInstance.Status.RUNNING_ACTUAL.
running_outdated_count int64
The number of running instances that does not match the current instance template. For more information, see ManagedInstance.Status.RUNNING_OUTDATED.
processing_count int64
The number of instances in flight (for example, updating, starting, deleting). For more information, see ManagedInstance.Status.

Statuses

Field Description
creating int64
Instance is being created.
starting int64
Instance is being started.
opening int64
Instance is being opened to receive traffic.
warming int64
Instance is being warmed.
running int64
Instance is running normally.
closing int64
Instance is being closed to traffic.
stopping int64
Instance is being stopped.
updating int64
Instance is being updated.
deleting int64
Instance is being deleted.
failed int64
Instance failed and needs to be recreated.

LoadBalancerSpec

Field Description
target_group_spec TargetGroupSpec
Specification of the target group that the instance group will be added to. For more information, see Target groups and resources.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

TargetGroupSpec

Field Description
name string
Name of the target group. Value must match the regular expression |[a-z]([-a-z0-9]{0,61}[a-z0-9])?.
description string
Description of the target group. The maximum string length in characters is 256.
labels map<string,string>
Resource labels as key:value pairs. No more than 64 per resource. The maximum string length in characters for each value is 63. Each value must match the regular expression [-_./\\@0-9a-z]*. The string length in characters for each key must be 1-63. Each key must match the regular expression [a-z][-_./\\@0-9a-z]*.

HealthChecksSpec

Field Description
health_check_specs[] HealthCheckSpec
Health checking specification. For more information, see Health check. The minimum number of elements is 1.
max_checking_health_duration google.protobuf.Duration
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 1s.

HealthCheckSpec

Field Description
interval google.protobuf.Duration
The interval between health checks. The default is 2 seconds. Acceptable values are 1s to 300s, inclusive.
timeout google.protobuf.Duration
Timeout for the managed instance to return a response for the health check. The default is 1 second. Acceptable values are 1s to 60s, inclusive.
unhealthy_threshold int64
The number of failed health checks for the managed instance to be considered unhealthy. The default (0) is 2. Value must be equal to 0,2,3,4,5,6,7,8,9,10.
healthy_threshold 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 equal to 0,2,3,4,5,6,7,8,9,10.
health_check_options oneof: tcp_options or http_options
  tcp_options TcpOptions
Configuration options for a TCP health check.
  http_options HttpOptions
Configuration options for an HTTP health check.

TcpOptions

Field Description
port int64
Port to use for TCP health checks. Acceptable values are 1 to 65535, inclusive.

HttpOptions

Field Description
port int64
Port to use for HTTP health checks. Acceptable values are 1 to 65535, inclusive.
path string
URL path to set for health checking requests.

Variable

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

ApplicationLoadBalancerSpec

Field Description
target_group_spec ApplicationTargetGroupSpec
Required. Basic properties of the Application Load Balancer target group attributed to the instance group.
max_opening_traffic_duration google.protobuf.Duration
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 1s.
ignore_health_checks bool
Do not wait load balancer health checks.

ApplicationTargetGroupSpec

Field Description
name string
Name of the target group.
description string
Description of the target group.
labels map<string,string>
Resource labels as key:value pairs.

ApplicationLoadBalancerState

Field Description
target_group_id string
ID of the Application Load Balancer target group attributed to the instance group.
status_message string
Status message of the target group.

AutoHealingPolicy

Field Description
auto_healing_action enum AutoHealingAction
Instance Groups performs auto_healing_action 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

ListOperations

Lists operations for the specified instance group.

rpc ListOperations (ListInstanceGroupOperationsRequest) returns (ListInstanceGroupOperationsResponse)

ListInstanceGroupOperationsRequest

Field Description
instance_group_id string
Required. ID of the InstanceGroup resource to list operations for. To get the instance group ID, use a InstanceGroupService.List request. The maximum string length in characters is 50.
page_size int64
The maximum number of results per page to return. If the number of available results is more than page_size, the service returns a ListInstanceGroupOperationsResponse.next_page_token that can be used to get the next page of results in subsequent list requests. Acceptable values are 0 to 1000, inclusive.
page_token string
Page token. To get the next page of results, set page_token to the ListInstanceGroupOperationsResponse.next_page_token returned by a previous list request. The maximum string length in characters is 1000.
filter string
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.

ListInstanceGroupOperationsResponse

Field Description
operations[] operation.Operation
Lists operations for the specified instance group.
next_page_token string
This token allows you to get the next page of results for list requests. If the number of results is more than ListInstanceGroupOperationsRequest.page_size, use the next_page_token as the value for the ListInstanceGroupOperationsRequest.page_token query parameter in the next list request. Each subsequent list request will have its own next_page_token to continue paging through the results.

Operation

Field Description
id string
ID of the operation.
description string
Description of the operation. 0-256 characters long.
created_at google.protobuf.Timestamp