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
andvariables
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 asmap
(Protobuf) are converted to YAML dictionary objects (key-value pairs). The object keys and field names are converted fromlowerCamelCase
andCamelCase
tosnake_case
.JSONProtobufYAML"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.JSONProtobufYAML"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.ProtobufYAMLmessage 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.
int64
type
Suffixes for the Values of the int64
type 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.
boolean
type
The 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: