Running a Docker image on a VM using the management console, CLI, and API

Written by

Yandex Cloud

Improved by

Danila N.

Updated at May 13, 2025

Get your cloud ready
Create a VM
Build and upload the Docker image to Container Registry
Upload the Docker image to the VM
Check the result
How to delete the resources you created
See also

To run a Docker image on a VM using a Yandex Container Registry registry, complete these steps:

If you no longer need the resources you created, delete them.

Get your cloud ready

Navigate to the management console and log in to Yandex Cloud or register a new account.
On the Yandex Cloud Billing page, make sure you have a billing account linked and it has the ACTIVE or TRIAL_ACTIVE status. If you do not have a billing account, create one and link a cloud to it.

If you have an active billing account, you can navigate to the cloud page to create or select a folder for your infrastructure to operate in.

Learn more about clouds and folders.

Required paid resources

The infrastructure support costs include:

Fee for a continuously running VM (see Yandex Compute Cloud pricing).
Fee for using a dynamic or static public IP address (see Yandex Virtual Private Cloud pricing).
Fee for storing a Docker image in the registry and outgoing traffic (see Yandex Container Registry pricing).

Set up your environment

Install the Yandex Cloud command line interface.
Prepare an SSH key for VM access.
Create a registry in Container Registry and upload a Docker image into it for testing.
Install and configure Docker.

Create a service account

Create a service account and assign it the container-registry.images.puller role for the previously created registry:
Management console

CLI

API
1. In the management console, select the folder where you want to create your service account.
2. From the list of services, select Identity and Access Management.
3. Click Create service account.
4. Enter the service account name and click Create.
5. Go back to the management console and open the folder you created the service account in.
6. From the list of services, select Container Registry.
7. Select the registry and click the row with its name.
8. Navigate to the Access bindings tab.
9. In the top-right corner, click Assign roles.
10. Click Select subject and add the service account by providing its ID.
11. Click Add role and select the container-registry.images.puller role.
12. Click Save.
If you do not have the Yandex Cloud (CLI) command line interface yet, install and initialize it.
1. View a description of the CLI command to create a service account:
  yc iam service-account create --help
2. Create a service account:
  
  The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.
  yc iam service-account create --name <service_account_name>
  Result:
  id: ajelabcde12f******** folder_id: b0g12ga82bcv******** created_at: "2020-11-30T14:32:18.900092Z" name: myservice-acc
3. Assign the role to the service account:
  yc <service_name> <resource> add-access-binding <resource_name_or_ID> \ --role <role_ID> \ --subject serviceAccount:<service_account_ID>
  Where:
  - <service_name>: container service name.
  - <resource>: registry resource category.
  - <resource_name_or_ID>: Name or ID of the resource to assign the role for.
  - --role: container-registry.images.puller role ID.
  - --subject: ID of the service account getting the role, e.g., ajelabcde12f********.
1. To create a service account, use the ServiceAccountService/Create gRPC API method or the create REST API method for the ServiceAccount resource.
2. To assign the service account a role for the registry, use the updateAccessBindings REST API method for the Registry resource or the RegistryService/UpdateAccessBindings gRPC API call.

Create a VM

Create a VM with a public IP address and link the service account you created to it:

Management console

CLI

API

On the folder dashboard of the management console, click Create resource and select Virtual machine instance.
Under Boot disk image, select an image and a Linux-based OS version.
Under Location, select the availability zone to create your VM in. If you do not know which availability zone you need, leave the default one.
Optionally, under Disks and file storages, specify the required boot disk type and size.

To add a new secondary disk or connect an existing one, click Add.

You can also create a VM from an existing disk.
Under Network settings:
- In the Subnet field, select the network and subnet to connect your VM to. If the required network or subnet is not there, create it.
- Under Public IP address, leave Auto to assign a random external IP address from the Yandex Cloud pool to your VM. Alternatively, select a static address from the list if you reserved one. If you prefer not to assign a public IP address, select No address.
- Expand Additional and enable DDoS protection, if required.
Under Access, select SSH key and specify the VM access data:
- Under Login, enter a username. Do not use root or other reserved usernames. To perform operations requiring root privileges, use the sudo command.
- In the SSH key field, select the SSH key saved in your organization user profile.
  
  If there are no saved SSH keys in your profile, or you want to add a new key:
  - Click Add key.
  - Enter a name for the SSH key.
  - Upload or paste the contents of the public key file. You need to create a key pair for the SSH connection to a VM yourself.
  - Click Add.
  The SSH key will be added to your organization user profile.
  
  If users cannot add SSH keys to their profiles in the organization, the added public SSH key will only be saved to the user profile of the VM being created.
Under General information, specify the VM name. Follow these naming requirements:
- It must be from 2 to 63 characters long.
- It may contain lowercase Latin letters, numbers, and hyphens.
- It must start with a letter and cannot end with a hyphen.
Note

The VM name is used to generate an internal FQDN, which is set only once, when you create the VM. If the internal FQDN is important to you, make sure to choose an appropriate name for your VM.
Under Additional, select the service account you created in the previous step.
Click Create VM.

View the description of the CLI command to create a VM:
```
yc compute instance create --help
```
Prepare a key pair (public and private keys) for SSH access to your VM.

Select in Cloud Marketplace a public image based on a Linux OS (for example, CentOS 7).

To get a list of available images using the CLI, run this command:

yc compute image list --folder-id standard-images

Result:

+----------------------+-------------------------------------+--------------------------+----------------------+--------+
|          ID          |                NAME                 |          FAMILY          |     PRODUCT IDS      | STATUS |
+----------------------+-------------------------------------+--------------------------+----------------------+--------+
...
| fdvk34al8k5n******** | centos-7-1549279494                 | centos-7                 | dqni65lfhvv2******** | READY  |
| fdv7ooobjfl3******** | windows-2016-gvlk-1548913814        | windows-2016-gvlk        | dqnnc72gj2is******** | READY  |
| fdv4f5kv5cvf******** | ubuntu-1604-lts-1549457823          | ubuntu-1604-lts          | dqnnb6dc7640******** | READY  |
...
+----------------------+-------------------------------------+--------------------------+----------------------+--------+

Where:

ID: Image ID.
NAME: Image name.
FAMILY: ID of the image family the image belongs to.
PRODUCT IDS: IDs of Yandex Cloud Marketplace products associated with the image.
STATUS: Current status of the image. It may take one of the following values:
- STATUS_UNSPECIFIED: Image status is not defined.
- CREATING: Image is being created.
- READY: Image is ready to use.
- ERROR: You cannot use the image due to an issue.
- DELETING: Image is being deleted.

View a list of available subnets:

yc vpc subnet list

Result:

+----------------------+---------------------------+----------------------+----------------+-------------------+-----------------+
|          ID          |           NAME            |      NETWORK ID      | ROUTE TABLE ID |       ZONE        |      RANGE      |
+----------------------+---------------------------+----------------------+----------------+-------------------+-----------------+
| b0c6n43f9lgh******** | default-ru-central1-d     | enpe3m3fa00u******** |                | ru-central1-d     | [10.130.0.0/24] |
| e2l2da8a20b3******** | default-ru-central1-b     | enpe3m3fa00u******** |                | ru-central1-b     | [10.129.0.0/24] |
| e9bnlm18l70a******** | default-ru-central1-a     | enpe3m3fa00u******** |                | ru-central1-a     | [10.128.0.0/24] |
+----------------------+---------------------------+----------------------+----------------+-------------------+-----------------+

Create a VM in the default folder:
```
yc compute instance create \
  --name first-instance \
  --zone ru-central1-b \
  --network-interface subnet-name=default-ru-central1-b,nat-ip-version=ipv4 \
  --create-boot-disk image-folder-id=standard-images,image-family=centos-7 \
  --ssh-key ~/.ssh/id_ed25519.pub
  --service-account-name service-acc
```
Where:
- --name: VM name.
  
  Note
  
  The VM name is used to generate an internal FQDN, which is set only once, when you create the VM. If the internal FQDN is important to you, make sure to choose an appropriate name for your VM.
- --zone: Availability zone matching the selected subnet.
- subnet-name: Name of the selected subnet.
- image-family: Image family, e.g., centos-7. This option allows you to install the latest version of the operating system from the specified image family.
- Public IP. To create a VM without a public IP address, disable the nat-ip-version=ipv4 option.
- --ssh-key: Public SSH key path. The VM will automatically create a user named yc-user for this key.
- --service-account-name: Name of the service account created in the previous step.
This will create a VM called first-instance.

Create a VM using the Create method for the Instance resource:

Prepare a key pair (public and private keys) for SSH access to your VM.
Get a IAM token used for authentication in the examples:
- Guide for users with a Yandex account.
- Guide for a service account.
Get the ID of the folder.

Get information about the image to create your VM from (image ID and minimum disk size):

If you know the image family, get info on the latest image in that family:

export IAM_TOKEN=CggaATEVAgA...
export FAMILY=ubuntu-1804
curl --header "Authorization: Bearer ${IAM_TOKEN}" \
  "https://compute.api.cloud.yandex.net/compute/v1/images:latestByFamily?folderId=standard-images&family=${FAMILY}"

You can get information on the image from the list of public images.

Get the subnet ID and availability zone ID. Specify the ID of the folder where the subnet was created in your request:

export IAM_TOKEN=CggaATEVAgA...
export FOLDER_ID=b1gvmob95yys********
curl --header "Authorization: Bearer ${IAM_TOKEN}" \
  "https://vpc.api.cloud.yandex.net/vpc/v1/subnets?folderId=${FOLDER_ID}"
{
  "subnets": [
    {
      "v4CidrBlocks": [
        "10.130.0.0/24"
      ],
    "id": "b0c6n43ftldh********",
    "folderId": "b1gvmob95yys********",
    "createdAt": "2018-09-23T12:15:00Z",
    "name": "default-ru-central1-b",
    "description": "Auto-created default subnet for zone ru-central1-b",
    "networkId": "enpe3m3faglu********",
    "zoneId": "ru-central1-b"
  },
  ...
  ]}

Create a file named body.json with the body of the request to create a VM:

{
  "folderId": "b1gvmob95yys********",
  "name": "instance-demo-no-pwauth",
  "zoneId": "ru-central1-b",
  "platformId": "standard-v3",
  "resourcesSpec": {
    "memory": "2147483648",
    "cores": "2"
  },
  "metadata": {
    "user-data": "#cloud-config\nusers:\n  - name: user\n    groups: sudo\n    shell: /bin/bash\n    sudo: 'ALL=(ALL) NOPASSWD:ALL'\n    ssh_authorized_keys:\n      - ssh-ed25519 AAAAB3N... user@example.com"
  },
  "bootDiskSpec": {
    "diskSpec": {
      "size": "2621440000",
      "imageId": "fd8rc75pn12f********"
    }
  },
  "networkInterfaceSpecs": [
    {
      "subnetId": "b0c6n43ftldh********",
      "primaryV4AddressSpec": {
        "oneToOneNatSpec": {
          "ipVersion": "IPV4"
        }
      }
    }
  ],
  "serviceAccountId": "ajelabcde12f********"
}

Where:

folderId: Folder ID.
name: Name the VM will get when created.
zoneId: Availability zone matching the selected subnet.
platformId: Platform.
resourceSpec: Resources available to the VM. The values must match the selected platform.
metadata: In metadata, provide the public key for accessing the VM via SSH. For more information, see VM metadata.
bootDiskSpec: Boot disk settings. Specify the selected image ID and disk size. The disk size must not be less than the minimum value specified in the image info.
networkInterfaceSpecs: Network settings:
- subnetId: ID of the selected subnet.
- primaryV4AddressSpec: IP address to assign to the VM. To add a public IP address to your VM, specify the following:
```
"primaryV4AddressSpec": {
  "oneToOneNatSpec": {
    "ipVersion": "IPV4"
  }
}
```
serviceAccountId: ID of the service account created in the previous step.

For more information about the request body format, see the API reference.

Create a VM:

export IAM_TOKEN=CggaATEVAgA...
curl --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --data '@body.json' \
  https://compute.api.cloud.yandex.net/compute/v1/instances

After creating the VM, build and upload the Docker image to Container Registry.

Build and upload the Docker image to Container Registry

To make command execution easier, add the following variables:
- Username and your VM's public IP to the ${PUBLIC_IP} variable:
```
export PUBLIC_IP=<username>@<VM_public_IP_address>
```
- ID of the previously created registry in crpc9qeoft23******** format to the ${REGISTRY_ID} variable:
```
export REGISTRY_ID=<registry_ID>
```
Authenticate as yourself:
OAuth token

IAM token

Docker credential helper
1. If you do not have an OAuth token yet, get one by following this link.
2. Run this command:
  echo <OAuth_token> | docker login --username oauth --password-stdin cr.yandex
  Result:
  Login Succeeded
Note

The IAM token has a short lifetime: no more than 12 hours. This makes it a good method for applications that automatically request an IAM token.
1. Get an IAM token.
2. Run this command:
  yc iam create-token | docker login --username iam --password-stdin cr.yandex
  Result:
  ... Login Succeeded
1. If you do not have a CLI profile yet, create one.
2. Configure Docker to use docker-credential-yc:
  yc container registry configure-docker
  Result:
  Credential helper is configured in '/home/<user>/.docker/config.json'
  Settings are saved in the current user's profile.
  
  Warning
  
  The credential helper only works if you use Docker without sudo. To learn how to configure Docker to run under the current user without sudo, see the official documentation.
3. Make sure that Docker is configured.
  
  The following line must appear in the /home/<user>/.docker/config.json configuration file:
  "cr.yandex": "yc"
4. You can now use Docker, for example, to push Docker images. You do not need to run the docker login command for that.
Create a file called Dockerfile:
```
touch .dockerfile
```
Open Dockerfile in a text editor, e.g.:
```
nano .dockerfile
```

Add the lines below to the file:

FROM ubuntu:latest
CMD echo "Hi, I'm inside"

Build the Docker image:

docker build . -t cr.yandex/${REGISTRY_ID}/ubuntu:hello -f .dockerfile

Result:

...
Successfully built b68ee9b6b1af
Successfully tagged cr.yandex/crpmnjr98tm5********/ubuntu:hello

Push the built Docker image to Container Registry:

docker push cr.yandex/${REGISTRY_ID}/ubuntu:hello

Result:

The push refers to repository [cr.yandex/crpc9qeoft23********/ubuntu]
cc9d18e90faa: Pushed
0c2689e3f920: Pushed
47dde53750b4: Pushed
hello: digest: sha256:42068479274f1d4c7ea095482430dcba24dcfe8c23ebdf6d32305928******** size: 943

Upload the Docker image to the VM

Use SSH to connect to the VM.

Authenticate under the service account tied to the machine:

curl --header Metadata-Flavor:Google 169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token | \
cut -f1 -d',' | \
cut -f2 -d':' | \
tr -d '"' | \
docker login --username iam --password-stdin cr.yandex

Result:

Login Succeeded

Download the Docker image to the VM:

docker pull cr.yandex/${REGISTRY_ID}/ubuntu:hello

Result:

hello: Pulling from crpc9qeoft23********/ubuntu
6a5697faee43: Pulling fs layer
ba13d3bc422b: Pulling fs layer
...
Digest: sha256:42068479274f1d4c7ea095482430dcba24dcfe8c23ebdf6d32305928********
Status: Downloaded newer image for cr.yandex/crpc9qeoft23********/ubuntu:hello
cr.yandex/crpc9qeoft23********/ubuntu:hello

Check the result

Run the Docker image on the VM:

docker run cr.yandex/${REGISTRY_ID}/ubuntu:hello

Result:

Hi, I'm inside

How to delete the resources you created

To stop paying for the resources you created:

Delete the VM.
Delete the static public IP if you reserved one.
Delete the Docker image.
Delete the registry.

Running a Docker image on a VM using the management console, CLI, and API

Get your cloud readyGet your cloud ready

Required paid resourcesRequired paid resources

Set up your environmentSet up your environment

Create a service accountCreate a service account

Create a VMCreate a VM

Build and upload the Docker image to Container RegistryBuild and upload the Docker image to Container Registry

Upload the Docker image to the VMUpload the Docker image to the VM

Check the resultCheck the result

How to delete the resources you createdHow to delete the resources you created

See alsoSee also

Was the article helpful?

Get your cloud ready

Required paid resources

Set up your environment

Create a service account

Create a VM

Build and upload the Docker image to Container Registry

Upload the Docker image to the VM

Check the result

How to delete the resources you created

See also