Creating an instance group from a Container Optimized Image in Compute Cloud

Written by

Updated at August 6, 2026

To run multiple service instances in Docker containers, you can create an instance group based on a Container Optimized Image. In such groups, you can update Docker containers with VM metadata using the COI or Docker Compose specification.

Alert

When creating instance groups, keep the limits in mind. Not to disrupt the component Instance Groups, do not update or delete manually created resources: target group Network Load Balancer, VMs, and disks. Instead of this, change or delete the entire group.

In Instance Groups, all operations are performed under a service account. If you don't have a service account, create one.

To be able to create, update, and delete VMs in the group, assign the compute.editor role to the service account.

To create an instance group based on a Container Optimized Image:

If you do not have the Yandex Cloud CLI yet, install and initialize it.
The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.
See the description of the CLI command for creating an instance group:
CLI
```
yc compute instance-group create --help
```
Check whether the folder has any networks:
CLI
```
yc vpc network list
```
If it does not, create one.
Create a YAML file and give it a name, e.g., specification.yaml.
Get the ID of the latest version of the public Container Optimized Image.

A Container Optimized Image in Container Registry may get updates and modifications that come with new releases. This will not automatically update the VM image to the latest version. To create an instance group with the latest Container Optimized Image version, manually check whether it is available:
CLI

Yandex Cloud Marketplace
```
yc compute image get-latest-from-family container-optimized-image --folder-id standard-images
```
Result:
```
id: <latest_COI_version_ID>
folder_id: standard-images
...
```
1. Go to the Cloud Marketplace page and select the image with the configuration you need:
  - Container Optimized Image.
  - Container Optimized Image GPU.
2. Under Product IDs, copy the image_id value.

In the specification.yaml file you created, specify the following:

General information about the group:
```
name: container-optimized-group
service_account_id: <service_account_ID>
description: "This instance group was created from YAML config."
```
Where:
- name: Instance group name. The name must be unique within the folder. It can only contain lowercase Latin letters, numbers, and hyphens. The first character must be a letter. The last character cannot be a hyphen. The name may be up to 63 characters long.
- service_account_id: Service account ID.
  
  To be able to create, update, and delete VMs in the group, assign the compute.editor role to the service account.
  
  You cannot delete a service account while it is linked to an instance group.
- description: Instance group description.

Instance template:

instance_template:
  platform_id: standard-v3
  resources_spec:
    memory: 2G
    cores: 2
  boot_disk_spec:
    mode: READ_WRITE
    disk_spec:
      image_id: <latest_COI_version_ID>
      type_id: network-hdd
      size: 32G
  network_interface_specs:
    - network_id: c64mknqgnd8a********
      primary_v4_address_spec: {}
      security_group_ids:
        - enps0ar5s3ti********
  placement_policy:
   placement_group_id: rmppvhrgm77g********
  metadata:
    docker-container-declaration: |-
      spec:
        containers:
          - name: nginx
            image: cr.yandex/mirror/nginx:1.17.4-alpine
            securityContext:
              privileged: false
            tty: false
            stdin: false

By default, the disk size is specified in bytes. You can specify a different unit of measurement using the applicable suffix.

Suffix	Prefix and multiplier	Example
`k`	kilo- (2¹⁰)	`640k` = 640 × 2¹⁰ = `655360`
`m`	mega- (2²⁰)	`48m` = 48 × 2²⁰ = `50331648`
`g`	giga- (2³⁰)	`10g` = 10 × 2³⁰ = `10737418240`
`t`	tera- (2⁴⁰)	`4t` = 4 × 2⁴⁰ = `4398046511104`
`p`	peta- (2⁵⁰)	`2p` = 2 × 2⁵⁰ = `2251799813685248`

Where:

platform_id: Platform ID.
memory: Amount of RAM.
cores: Number of vCPUs.
mode: Disk access mode:
- READ_ONLY: Read-only access.
- READ_WRITE: Read/write access.
image_id: Public Container Optimized Image ID.
type_id: Disk type.
size: Disk size. It must be at least 30 GB.
network_id: default-net ID.
primary_v4_address_spec: IPv4 specification. Only IPv4 is currently available. You can enable public access to the group instances by specifying the IP version for the public IP address.
security_group_ids: List of security group IDs.
metadata: Values to write to the VM metadata.
docker-container-declaration: VM metadata key that indicates the use of a Docker container COI specification. In the metadata, you can use a Docker Compose specification. To do this, specify the docker-compose key instead of the docker-container-declaration key.
placement_policy: Optional instance placement group settings:
- placement_group_id: Placement group ID.

Policies:

deploy_policy:
  max_unavailable: 1
  max_expansion: 0
scale_policy:
  fixed_scale:
    size: 3
allocation_policy:
  zones:
    - zone_id: ru-central1-a
      instance_tags_pool:
      - first
      - second
      - third

Where:

deploy_policy: Instance deployment policy for the group.
scale_policy: Instance scaling policy for the group.
allocation_policy: Policy for allocating VM instances across availability zones.

Full code for the specification.yaml file:

name: container-optimized-group
service_account_id: <service_account_ID>
description: "This instance group was created from YAML config."
instance_template:
  service_account_id: <service_account_ID> # ID of the service account for accessing private Docker images.
  platform_id: standard-v3
  resources_spec:
    memory: 2G
    cores: 2
  boot_disk_spec:
    mode: READ_WRITE
    disk_spec:
      image_id: <latest_COI_version_ID>
      type_id: network-hdd
      size: 32G
  network_interface_specs:
    - network_id: c64mknqgnd8a********
      primary_v4_address_spec: {}
      security_group_ids:
        - enps0ar5s3ti********
  placement_policy:
    placement_group_id: rmppvhrgm77g********
  metadata:
    docker-container-declaration: |-
      spec:
        containers:
          - name: nginx
            image: cr.yandex/mirror/nginx:1.17.4-alpine
            securityContext:
              privileged: false
            tty: false
            stdin: false
deploy_policy:
  max_unavailable: 1
  max_expansion: 0
scale_policy:
  fixed_scale:
    size: 3
allocation_policy:
  zones:
     - zone_id: ru-central1-a
       instance_tags_pool:
       - first
       - second
       - third

Note

To use a Docker Compose specification in specification.yaml, specify the docker-compose key instead of the docker-container-declaration key.

Create an instance group in the default folder:
CLI
```
yc compute instance-group create --file specification.yaml
```
This command will create a group of three same-type instances with the following configuration:
- Name: container-optimized-group.
- Based on the latest version of the public Container Optimized Image.
- With a running Docker container based on cr.yandex/mirror/nginx:1.17.4-alpine.
- Network: default-net.
- Availability zone: ru-central1-a.
- vCPUs: 2; RAM: 2 GB.
- Network HDD: 32 GB.

Creating an instance group from a Container Optimized Image in Compute Cloud

Was the article helpful?