[Yandex Cloud documentation](../../../index.md) > [Yandex Compute Cloud](../../index.md) > [Concepts](../index.md) > [Instance groups](index.md) > YAML specification

# Specification of an instance group in YAML format

You can create or edit an instance group based on the specification in [YAML](https://en.wikipedia.org/wiki/YAML) format. The specification describes:

* Basic attributes and settings of the group: name, description, [labels](../../../resource-manager/concepts/labels.md), [service account](../../../iam/concepts/users/service-accounts.md), and deletion protection.
* [VM instance template](instance-template.md) and [variables](variables-in-the-template.md) used in it.
* Policies for VM instance [allocation](policies/allocation-policy.md), [deployment](policies/deploy-policy.md), [scaling](policies/scale-policy.md), and [recovery](policies/healing-policy.md).
* Settings for balancing the traffic between VM instances using [Yandex Network Load Balancer](../../../network-load-balancer/index.md) or [Yandex Application Load Balancer](../../../application-load-balancer/index.md).

{% note info %}

You can also create an instance group using [Terraform](https://terraform.io) based on the description similar to a YAML specification. For more information, see the guides on [getting started with Terraform](../../../tutorials/infrastructure-management/terraform-quickstart.md), [creating an instance group](../../operations/instance-groups/create-fixed-group.md), and the [`yandex_compute_instance_group` reference](../../../terraform/resources/compute_instance_group.md).

{% endnote %}


## Example {#example}

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](../../tutorials/autoscale-monitoring.md):

```yaml
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********
```


## Fields {#fields}

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

* In the specification of the [CreateInstanceGroupRequest](https://github.com/yandex-cloud/cloudapi/blob/master/yandex/cloud/compute/v1/instancegroup/instance_group_service.proto#L219) structure and other [structures used in it](https://github.com/yandex-cloud/cloudapi/blob/master/yandex/cloud/compute/v1/instancegroup/instance_group.proto), in the API repository on GitHub (in [Protobuf](https://en.wikipedia.org/wiki/Protocol_Buffers) format).
* In the description of the [create](../../instancegroup/api-ref/InstanceGroup/create.md) REST API method of the `InstanceGroup` resource ([JSON](https://en.wikipedia.org/wiki/JSON))
* In the description of the [InstanceGroupService/Create](../../instancegroup/api-ref/grpc/InstanceGroup/create.md) 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.md) (`instance_template` field)
* [Variables in an instance template](variables-in-the-template.md) (`instance_template` and `variables` fields)
* [Allocation policy](policies/allocation-policy.md) (`allocation_policy` field)
* [Deployment policy](policies/deploy-policy.md) (`deploy_policy` field)
* [Scaling policy](policies/scale-policy.md) (`scale_policy` field)
* [Recovery policy](policies/healing-policy.md) (`auto_healing_policy` field)
* [Health checks and autohealing of group instances](autohealing.md) (`health_checks_spec` field)
* [Integrating an instance group with Network Load Balancer or Application Load Balancer](balancers.md) (`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 YAML {#translation-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`:

  {% list tabs group=data_format %}
  
  - JSON {#json}
  
    ```json
    "targetGroupSpec": {
      "name": "spec-example-tg",
      "description": "ALB target group for example instance group",
      "labels": {
        "foo": "bar",
        "environment": "production"
      }
    }
    ```
  
  - Protobuf {#protobuf}
  
    ```protobuf
    message TargetGroupSpec {
      string name = 1;
      string description = 2;
      map<string, string> labels = 3;
    }
    ```
  
  - YAML {#yaml}
  
    ```yaml
    target_group_spec:
      name: spec-example-tg
      description: ALB target group for example instance group
      labels:
        foo: bar
        environment: production
    ```
  
  {% endlist %}

* Arrays (JSON) and `repeated` (Protobuf) type fields are converted into YAML lists:

  {% list tabs group=data_format %}
  
  - JSON {#json}
  
    ```json
    "variables": [
      {
        "key": "foo",
        "value": "bar"
      },
      {
        "key": "baz",
        "value": "foobar"
      }
    ]
    ```
  
  - Protobuf {#protobuf}
  
    ```protobuf
    message Variable {
      string key = 1;
      string value = 2;
    }
    
    repeated Variable variables = 1;
    ```
  
  - YAML {#yaml}
  
    ```yaml
    variables:
      - key: foo
        value: bar
      - key: baz
        value: foobar
    ```
  
  {% endlist %}

* The `enum` (Protobuf) type structures are converted into scalar YAML values, i.e., strings corresponding to field names in Protobuf:

  {% list tabs group=data_format %}
  
  - Protobuf {#protobuf}
  
    ```protobuf
    message AttachedDiskSpec {
      enum Mode {
        MODE_UNSPECIFIED = 0;
        READ_ONLY = 1;
        READ_WRITE = 2;
      }
      Mode mode = 1;
    }
    ```
  
  - YAML {#yaml}
  
    ```yaml
    attached_disk_spec:
      mode: READ_WRITE
    ```
  
  {% endlist %}

## Value format {#values}

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 `int64` type {#int64}

The `int64` type values support the following suffixes:

| Suffix | Prefix and multiplier | Example |
| ----- | ----- | ----- |
| `k` | kilo- (2^10^) | `640k` = 640 × 2^10^ = `655360` |
| `m` | mega- (2^20^) | `48m` = 48 × 2^20^ = `50331648` |
| `g` | giga- (2^30^) | `10g` = 10 × 2^30^ = `10737418240` |
| `t` | tera- (2^40^) | `4t` = 4 × 2^40^ = `4398046511104` |
| `p` | peta- (2^50^) | `2p` = 2 × 2^50^ = `2251799813685248` |

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

### `boolean` type {#boolean}

`bool` or `boolean` fields support all values listed in the [YAML format specification](https://yaml.org/type/bool.html):

* 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 specification {#how}

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](../../operations/instance-groups/create-from-yaml.md)
* [Updating an instance group based on a YAML specification](../../operations/instance-groups/update-from-yaml.md)

## Use cases {#examples}

* [Running an autoscaling instance group](../../tutorials/vm-autoscale/index.md)