Yandex Cloud
  • Services
  • Solutions
  • Why Yandex Cloud
  • Pricing
  • Documentation
  • Contact us
Get started
Language / Region
© 2022 Yandex.Cloud LLC
Yandex Compute Cloud
  • Getting started
    • Overview
    • Creating a Linux VM
    • Creating a Windows VM
    • Creating instance groups
  • Step-by-step instructions
    • All instructions
    • Creating VMs
      • Creating a Linux VM
      • Creating a Windows VM
      • Creating a VM from a set of disks
      • Creating a VM with disks from snapshots
      • Creating a VM from a custom image
      • Creating a VM with a GPU
      • Making a VM preemptible
    • DSVM
      • Overview
      • Creating a VM from a public DSVM image
    • Placement groups
      • Creating a placement group
      • Deleting a placement group
      • Creating a VM in a placement group
      • Adding a VM to a placement group
      • Removing a VM from a placement group
    • Images with pre-installed software
      • Creating a VM from a public image
      • Configuring software
      • Running a VM based on a public image
      • Getting a list of public images
    • Getting information about a VM
      • Getting information about a VM
      • Getting serial port's output
    • Managing VMs
      • Stopping and starting a VM
      • Resetting a VM user password
      • Attaching a disk to a VM
      • Detaching a disk from a VM
      • Moving a VM to a different availability zone
      • Moving a VM to another folder
      • Attaching a public IP address to a VM
      • Detaching a public IP address from a VM
      • Making a VM's public IP address static
      • Updating a VM
      • Changing VM computing resources
      • Deleting a VM
    • Working on VMs
      • Connecting to a VM via SSH
      • Connecting to a VM via RDP
      • Connecting to a VM via PowerShell
      • Working with Yandex Cloud from inside a VM
      • Installing NVIDIA drivers
      • Restoring access to a VM
    • Managing the password reset agent
      • Verifying agent operation
      • Installing the agent
      • Deleting the agent
    • Creating new disks
      • Creating an empty disk
      • Creating an empty disk with a large block
      • Creating a non-replicated disk
    • Disk management
      • Creating a disk snapshot
      • Updating a disk
      • Moving a disk to another folder
      • Deleting a disk
      • Deleting a disk snapshot
    • Disk placement groups
      • Creating a disk placement group
      • Removing a disk from a placement group
    • Creating new images
      • Preparing a disk image
      • Uploading your image
      • Creating an image from a disk
      • Creating an image from a snapshot
      • Creating an image from other custom image
    • Managing images
      • Getting a list of images
      • Deleting a disk image
    • File storage
      • Creating file storage
      • Attaching file storage to a VM
      • Detaching file storage from a VM
      • Updating file storage
      • Deleting file storage
    • Managing the serial console
      • Getting started
      • Connecting to a serial console via SSH
      • Connecting to a serial console via CLI
      • Starting your terminal in the Windows serial console (SAC)
      • Disabling access to the serial console
    • Creating instance groups
      • Creating a fixed-size instance group
      • Creating a fixed-size instance group with a network load balancer
      • Creating a fixed-size instance group with an L7 load balancer
      • Creating an automatically scaled instance group
      • Creating an instance group from a Container Optimized Image
      • Creating an instance group based on the YAML specification
    • Getting information about instance groups
      • Getting a list of instance groups
      • Getting information about an instance group
      • Getting a list of instances in a group
    • Managing instance groups
      • Editing an instance group
      • Edit an instance group based on the YAML specification
      • Configuring application health check on the VM
      • Updating a group
        • Incremental update
        • Uninterrupted updates
      • Pausing an instance group
      • Resuming an instance group
      • Stopping an instance group
      • Starting an instance group
      • Deleting an instance group
    • Dedicated hosts
      • Creating a VM in a group of dedicated hosts
      • Creating a VM on a dedicated host
  • Yandex Container Solution
  • Practical guidelines
    • Configuring NTP time synchronization
    • Running instance groups with auto scaling
    • Automatically scaling an instance group for handling messages from a queue
    • Updating an instance group under load
    • Deploying Remote Desktop Gateway
    • Transferring logs from a VM instance to Yandex Cloud Logging
    • Creating a VM backup with Hystax Acura Backup
  • Concepts
    • Relationship between resources
    • Virtual machines
      • Overview
      • Platforms
      • vCPU performance levels
      • Preemptible VMs
      • Network on a VM
      • Software-accelerated network
      • Live migration
      • Placement groups
      • Statuses
      • Metadata
      • Resetting a Windows VM password
    • Graphics accelerators
    • Disks and file storage
      • Overview
      • Disks
      • Disk snapshots
      • Non-replicated disk placement groups
      • File storage
      • Read and write operations
    • Images
    • Instance groups
      • Overview
      • Access
      • YAML specification
      • Instance template
      • Variables in an instance template
      • Policies
        • Overview
        • Allocation policy
        • Deployment policy
        • Scaling policy
      • Scaling types
      • Auto-healing
      • Updating
        • Overview
        • Allocating instances across zones
        • Deployment algorithm
        • Rules for updating virtual machines
        • Changing secondary disks in an instance template
      • Stopping and pausing an instance group
      • Statuses
    • Dedicated host
    • Backups
    • Quotas and limits
  • Access management
  • Pricing policy
    • Current pricing policy
    • Archive
      • Before January 1, 2019
      • From January 1 to March 1, 2019
      • From March 1 to May 1, 2019
  • API reference
    • Authentication in the API
    • gRPC
      • Overview
      • DiskPlacementGroupService
      • DiskService
      • DiskTypeService
      • FilesystemService
      • HostGroupService
      • HostTypeService
      • ImageService
      • InstanceService
      • PlacementGroupService
      • SnapshotScheduleService
      • SnapshotService
      • ZoneService
      • InstanceGroupService
      • OperationService
    • REST
      • Overview
      • DiskPlacementGroup
        • Overview
        • create
        • delete
        • get
        • list
        • listDisks
        • listOperations
        • update
      • Disk
        • Overview
        • create
        • delete
        • get
        • list
        • listOperations
        • move
        • update
      • DiskType
        • Overview
        • get
        • list
      • Filesystem
        • Overview
        • create
        • delete
        • get
        • list
        • listOperations
        • update
      • HostGroup
        • Overview
        • create
        • delete
        • get
        • list
        • listHosts
        • listInstances
        • listOperations
        • update
      • HostType
        • Overview
        • get
        • list
      • Image
        • Overview
        • create
        • delete
        • get
        • getLatestByFamily
        • list
        • listOperations
        • update
      • Instance
        • Overview
        • addOneToOneNat
        • attachDisk
        • attachFilesystem
        • create
        • delete
        • detachDisk
        • detachFilesystem
        • get
        • getSerialPortOutput
        • list
        • listOperations
        • move
        • removeOneToOneNat
        • restart
        • start
        • stop
        • update
        • updateMetadata
        • updateNetworkInterface
      • PlacementGroup
        • Overview
        • create
        • delete
        • get
        • list
        • listInstances
        • listOperations
        • update
      • SnapshotSchedule
        • Overview
        • create
        • delete
        • disable
        • enable
        • get
        • list
        • listDisks
        • listOperations
        • listSnapshots
        • update
        • updateDisks
      • Snapshot
        • Overview
        • create
        • delete
        • get
        • list
        • listOperations
        • update
      • Zone
        • Overview
        • get
        • list
      • Operation
        • Overview
        • get
      • InstanceGroup
        • Overview
        • list
        • get
        • listLogRecords
        • updateFromYaml
        • updateAccessBindings
        • pauseProcesses
        • stop
        • start
        • delete
        • listInstances
        • createFromYaml
        • update
        • setAccessBindings
        • listOperations
        • create
        • listAccessBindings
        • resumeProcesses
  • Questions and answers
    • General questions
    • Virtual machines
    • Connection
    • Disks, snapshots, and images
    • Disaster recovery
    • Monitoring
    • Licensing
    • All questions on the same page
  1. Concepts
  2. Instance groups
  3. YAML specification

Specification of an instance group in YAML format

Written by
Yandex Cloud
  • Example
  • Fields
  • Converting JSON and Protobuf to YAML
  • Value format
    • Suffixes for the int64type
    • The booleantype
  • How to create or edit an instance group based on a specification

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:

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.

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

Was the article helpful?

Language / Region
© 2022 Yandex.Cloud LLC
In this article:
  • Example
  • Fields
  • Converting JSON and Protobuf to YAML
  • Value format
  • Suffixes for the int64type
  • The booleantype
  • How to create or edit an instance group based on a specification