Specification of an instance group in YAML format

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

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

Example

You can use the specification below to create an automatically scalable VM group, as in the message processing scenario from the Yandex Message Queue queue:

folder_id: b1gken0eihqn2oa0fm2k
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: fd8m5bal0bi9tjhu7av2
  network_interface_specs:
  - network_id: enpocgefm44fp31qpdru
    subnet_ids:
    - e2ljvdp4j2762fl4qh1i
    primary_v4_address_spec:
      one_to_one_nat_spec:
        ip_version: IPV4
  scheduling_policy: {}
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
allocation_policy:
  zones:
  - zone_id: ru-central1-b
service_account_id: ajefnb8427bhl9t0pvf8

Fields

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 method Create of the InstanceGroup resource in the REST API (JSON format).
• In the description of the call InstanceGroupService/Create gRPC API.

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

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

Converting JSON and Protobuf to YAML

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

• The 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, that is, 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 format

In YAML format, all values in dictionary objects are implicitly strings, so you don't 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, and so on.

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

The booleantype

In fields of bool or boolean type, all values listed in the YAML format specification are supported:

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

How to create or edit 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 the instructions:

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