Связаться с намиПодключиться

Спецификация группы виртуальных машин в формате YAML

Статья создана
Улучшена
Обновлена 28 апреля 2025 г.

Группу ВМ можно создать или изменить по спецификации в формате YAML. В спецификации описываются:

Примечание

Также группу ВМ можно создать с помощью Terraform по описанию, схожему со спецификацией в формате YAML. Подробнее см. в руководстве по началу работы с Terraform, инструкции по созданию группы ВМ и справочнике ресурса yandex_compute_instance_group.

Пример

По следующей спецификации можно создать автоматически масштабируемую группу ВМ, как в сценарии обработки сообщений из очереди Yandex Message 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: kz1-a
service_account_id: ajefnb8427bh********

Поля

Список, структура и англоязычные описания полей спецификации представлены:

Справочники API генерируются из спецификаций, размещенных на GitHub.

Некоторые поля первого уровня и вложенные в них поля также описаны на русском языке в разделах документации:

Эти разделы обновляются вручную. Они могут быть менее актуальными, чем справочники API и спецификация на GitHub.

Преобразование JSON и Protobuf в YAML

Создать YAML-спецификацию по описанию в формате JSON или Protobuf можно по следующим правилам:

  • Объекты (JSON), структуры message и поля типа map (Protobuf) преобразуются в словарные объекты YAML (пары «ключ — значение»). Ключи объектов и названия полей преобразуются из lowerCamelCase и CamelCase в snake_case.

    "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

  • Массивы (JSON) и поля типа repeated (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

  • Структуры типа enum (Protobuf) преобразуются в скалярные значения YAML — строки, соответствующие названиям полей в Protobuf.

    message AttachedDiskSpec {
  enum Mode {
    MODE_UNSPECIFIED = 0;
    READ_ONLY = 1;
    READ_WRITE = 2;
  }
  Mode mode = 1;
}

    attached_disk_spec:
  mode: READ_WRITE

Формат значений

В формате YAML все значения в словарных объектах неявно являются строками, использовать для их обозначения кавычки необязательно. Содержимое строк должно соответствовать типам, указанным в справочнике API или в спецификации в формате Protobuf: string, int64, bool и т. п.

Суффиксы для типа int64

В значениях типа int64 поддерживаются следующие суффиксы:

Суффикс Приставка и множитель Пример
k кило- (210) 640k = 640 × 210 = 655360
m мега- (220) 48m = 48 × 220 = 50331648
g гига- (230) 10g = 10 × 230 = 10737418240
t тера- (240) 4t = 4 × 240 = 4398046511104
p пета- (250) 2p = 2 × 250 = 2251799813685248

Если в значении используется суффикс, перед ним должно стоять целое число.

Тип boolean

В полях типа bool или boolean поддерживаются все значения, перечисленные в спецификации формата YAML:

  • Истина: y, Y, yes, Yes, YES, true, True, TRUE, on, On, ON.
  • Ложь: n, N, no, No, NO, false, False, FALSE, off, Off, OFF.

Как создать или изменить группу ВМ по спецификации

Создать группу виртуальных машин по YAML-спецификации можно через интерфейс командной строки (CLI) или API. Подробнее см. в инструкциях:

Примеры использования

Предыдущая
Доступ
Следующая
Шаблон виртуальной машины