Specification of an instance group in YAML format

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.

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 (Protobuf format).
• In the description of the create REST API method of the InstanceGroup resource (JSON format).
• 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 (the instance_template field).
• Variables in an instance template (the instance_template and variables fields).
• Allocation policy (the allocation_policy field).
• Deployment policy (the deploy_policy field).
• Scaling policy (the scale_policy field).
• Recovery policy (the auto_healing_policy field).
• Health checks and autohealing of group instances (the health_checks_spec field).
• Integrating an instance group with Network Load Balancer or Application Load Balancer (the 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 such fields as map (Protobuf) are converted to YAML dictionary objects (key-value pairs). The object keys and field names are converted from lowerCamelCase and CamelCase to 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 fields of the repeated type (Protobuf) are converted to 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) structures are converted to 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

Values of the int64 type support the following suffixes:

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:

• Create an instance group based on the specification in YAML format
• Editing an instance group based on a YAML specification