Yandex Cloud
Search
Contact UsGet started
  • Blog
  • Pricing
  • Documentation
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • ML & AI
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Customer Stories
    • Gateway to Russia
    • Cloud for Startups
    • Education and Science
  • Blog
  • Pricing
  • Documentation
Yandex project
© 2025 Yandex.Cloud LLC
Yandex Compute Cloud
  • Yandex Container Solution
    • Resource relationships
    • Graphics processing units (GPUs)
    • Images
      • Overview
      • Access
      • YAML specification
      • Instance template
      • Variables in an instance template
      • Scaling types
      • Instance health checks and automatic recovery
      • Integrating with network and L7 load balancers
      • Handling a stateful workload
      • Stopping and pausing an instance group
      • Sequentially restarting and recreating instances in a group
      • Statuses
    • Dedicated host
    • Encryption
    • Backups
    • Quotas and limits
  • Access management
  • Terraform reference
  • Monitoring metrics
  • Audit Trails events
  • Release notes

In this article:

  • Example
  • Fields
  • Converting JSON and Protobuf to YAML
  • Value format
  • Suffixes for the int64type
  • booleantype
  • Creating or editing an instance group based on a specification
  • Use cases
  1. Concepts
  2. Instance groups
  3. YAML specification

Specification of an instance group in YAML format

Written by
Yandex Cloud
Updated at April 28, 2025
  • Example
  • Fields
  • Converting JSON and Protobuf to YAML
  • Value format
    • Suffixes for the int64type
    • booleantype
  • Creating or editing an instance group based on a specification
  • Use cases

You can create or edit an instance group based on the specification in YAML format. The specification describes:

  • Basic attributes and settings of the group: name, description, labels, service account, and deletion protection.
  • VM instance template and variables used in it.
  • Policies for VM instance allocation, deployment, scaling, and recovery.
  • Settings for balancing the traffic between VM instances using Yandex Network Load Balancer or Yandex Application Load Balancer.

Note

You can also create an instance group using Terraform based on the description similar to a YAML specification. For more information, see Getting started with Terraform, Create an instance group, and the yandex_compute_instance_group resource guide.

ExampleExample

You can use the specification below to create an automatically scalable instance group, as in the tutorial on how to process messages from the Yandex Message Queue queue:

folder_id: b1gken0eihqn********
name: queue-autoscale-ig
instance_template:
  platform_id: standard-v3
  resources_spec:
    memory: 2g
    cores: 2
    core_fraction: 100
  boot_disk_spec:
    mode: READ_WRITE
    disk_spec:
      type_id: network-hdd
      size: 5g
      image_id: fd8m5bal0bi9********
  network_interface_specs:
    - network_id: enpocgefm44f********
      subnet_ids:
        - e2ljvdp4j276********
      primary_v4_address_spec: {
        one_to_one_nat_spec: {
          ip_version: IPV4
        }
      }
      security_group_ids:
        - enps0ar5s3ti********
  filesystem_specs:
    - mode: READ_WRITE
      device_name: sample-fs
      filesystem_id: epdccsrlalon********
  service_account_id: aje1ki4ae68u********
  network_settings:
    type: STANDARD
  scheduling_policy: {}
  placement_policy:
    placement_group_id: rmppvhrgm77g********
scale_policy:
  auto_scale:
    min_zone_size: 0
    max_size: 5
    measurement_duration: 60s
    warmup_duration: 0s
    stabilization_duration: 300s
    initial_size: 1
    auto_scale_type: REGIONAL
    custom_rules:
      - rule_type: WORKLOAD
        metric_type: GAUGE
        metric_name: queue.messages.stored_count
        labels:
          queue: queue-autoscale-queue
        target: 5
        service: message-queue
deploy_policy:
  max_unavailable: 1
  startup_duration: 0s
  strategy: OPPORTUNISTIC
  minimal_action: RESTART
auto_healing_policy:
  auto_healing_action: RESTART
allocation_policy:
  zones:
    - zone_id: ru-central1-a
service_account_id: ajefnb8427bh********

FieldsFields

The list, structure, and descriptions of specification fields are provided:

  • In the specification of the CreateInstanceGroupRequest structure and other structures used in it, in the API repository on GitHub (in Protobuf format).
  • In the description of the create REST API method of the InstanceGroup resource (JSON)
  • In the description of the InstanceGroupService/Create gRPC API call.

API references are generated from specifications published on GitHub.

Some first-level fields and their nested fields are also described in the following documentation sections:

  • Instance template (instance_template field)
  • Variables in an instance template (instance_template and variables fields)
  • Allocation policy (allocation_policy field)
  • Deployment policy (deploy_policy field)
  • Scaling policy (scale_policy field)
  • Recovery policy (auto_healing_policy field)
  • Health checks and autohealing of group instances (health_checks_spec field)
  • Integrating an instance group with Network Load Balancer or Application Load Balancer (load_balancer_spec and application_load_balancer_spec fields)

These sections are updated manually. They may be not as up-to-date as the API references and our specification on GitHub.

Converting JSON and Protobuf to YAMLConverting JSON and Protobuf to YAML

You can create a YAML specification from a JSON or Protobuf specification using the following rules:

  • Objects (JSON), message structures, and map (Protobuf) type fields are converted into YAML dictionary objects (key-value pairs). The object keys and field names are converted from lowerCamelCase and CamelCase into snake_case:

    JSON
    Protobuf
    YAML
    "targetGroupSpec": {
      "name": "spec-example-tg",
      "description": "ALB target group for example instance group",
      "labels": {
        "foo": "bar",
        "environment": "production"
      }
    }
    
    message TargetGroupSpec {
      string name = 1;
      string description = 2;
      map<string, string> labels = 3;
    }
    
    target_group_spec:
      name: spec-example-tg
      description: ALB target group for example instance group
      labels:
        foo: bar
        environment: production
    
  • Arrays (JSON) and repeated (Protobuf) type fields are converted into YAML lists:

    JSON
    Protobuf
    YAML
    "variables": [
      {
        "key": "foo",
        "value": "bar"
      },
      {
        "key": "baz",
        "value": "foobar"
      }
    ]
    
    message Variable {
      string key = 1;
      string value = 2;
    }
    
    repeated Variable variables = 1;
    
    variables:
      - key: foo
        value: bar
      - key: baz
        value: foobar
    
  • The enum (Protobuf) type structures are converted into scalar YAML values, i.e., strings corresponding to field names in Protobuf:

    Protobuf
    YAML
    message AttachedDiskSpec {
      enum Mode {
        MODE_UNSPECIFIED = 0;
        READ_ONLY = 1;
        READ_WRITE = 2;
      }
      Mode mode = 1;
    }
    
    attached_disk_spec:
      mode: READ_WRITE
    

Value formatValue format

In YAML format, all values in dictionary objects are implicitly strings, so you do not need to use quotation marks for them. The string contents must match the types specified in the API reference or in the Protobuf specification: string, int64, bool, etc.

Suffixes for the typeSuffixes for the int64type

The int64 type values support the following suffixes:

Suffix Prefix and multiplier Example
k kilo- (210) 640k = 640 × 210 = 655360
m mega- (220) 48m = 48 × 220 = 50331648
g giga- (230) 10g = 10 × 230 = 10737418240
t tera- (240) 4t = 4 × 240 = 4398046511104
p peta- (250) 2p = 2 × 250 = 2251799813685248

If a value uses a suffix, it must be prefixed by an integer.

typebooleantype

bool or boolean fields support all values listed in the YAML format specification:

  • True: y, Y, yes, Yes, YES, true, True, TRUE, on, On, ON.
  • False: n, N, no, No, NO, false, False, FALSE, off, Off, OFF.

Creating or editing an instance group based on a specificationCreating or editing an instance group based on a specification

You can create an instance group based on a YAML specification using the command line interface (CLI) or API. For more information, see these guides:

  • Creating an instance group based on a YAML specification
  • Updating an instance group based on a YAML specification

Use casesUse cases

  • Running an autoscaling instance group

Was the article helpful?

Previous
Access
Next
Instance template
Yandex project
© 2025 Yandex.Cloud LLC