Running a Docker image on a VM using the management console, CLI, and API
To run a Docker image on a VM using a Yandex Container Registry registry, follow these steps:
- Prepare your cloud.
- Create a VM.
- Build and upload the Docker image to Container Registry.
- Download the Docker image to a VM.
- Check the result.
If you no longer need the resources you created, delete them.
Prepare your cloud
Sign up for Yandex Cloud and create a billing account:
- Go to the management console
and log in to Yandex Cloud or create an account if you do not have one yet. - On the Yandex Cloud Billing
page, make sure you have a billing account linked and it has theACTIVE
orTRIAL_ACTIVE
status. If you do not have a billing account, create one.
If you have an active billing account, you can go to the cloud page
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).
Configure the 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 consoleCLIAPI- In the management console
, select the folder where you want to create your service account. - In the list of services, select Identity and Access Management.
- Click Create service account.
- Enter the service account name and click Create.
- Go back to the management console
and open the folder you created the service account in. - In the list of services, select Container Registry.
- Select the registry and click the row with its name.
- Go to the Access bindings tab.
- In the top-right corner, click Assign bindings.
- Click
Select subject and add the service account by providing its ID. - Click Add role and select the
container-registry.images.puller
role. - Click Save.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
-
View a description of the CLI command to create a service account:
yc iam service-account create --help
-
Create a service account:
The folder specified in the CLI profile is used by default. 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
-
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********
.
-
To create a service account, use the ServiceAccountService/Create gRPC API method or the create REST API method for the
ServiceAccount
resource. -
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.
- In the management console
Create a VM
Create a VM with a public IP address and link the service account you created to it:
- In the management console
, select the folder to create your VM in. - In the list of services, select Compute Cloud.
- Click Create resource and select Virtual machine instance.
- Under General information:
-
Enter a name and description for the VM. The naming requirements are as follows:
- The name must be from 3 to 63 characters long.
- It may contain lowercase Latin letters, numbers, and hyphens.
- The first character must be a letter and the last character cannot be a hyphen.
Note
The VM name is used to generate an internal FQDN only once: when creating a VM. If the internal FQDN is important to you, choose an appropriate name for the VM at the creation stage.
-
Select the service account you created in the previous step.
-
Select an availability zone to place your VM in.
-
- Under Boot disk image, select an image and a Linux-based OS version.
- (Optional) Configure the boot disk under Disks:
-
Specify the required disk size.
-
Select the disk type.
If you want to create a VM from an existing disk, under Disks, add a disk.
-
- Under Computing resources:
- Choose a platform.
- Specify the guaranteed share and required number of vCPUs, as well as RAM size.
- If required, make your VM preemptible.
- Under Network settings:
- Enter a subnet ID or select a cloud network from the list. If you do not have a network, click Create network to create one:
- In the window that opens, enter a name for the new network and choose a subnet to connect the VM to. Each network should have at least one subnet (if there are no subnets, create one). Then click Create network.
- In the Public IP field, choose a method for assigning an IP address:
Auto
: Assign a random IP address from the Yandex Cloud IP address pool.List
: Select a public IP address from the list of previously reserved static addresses. For more information, see Converting a dynamic public IP address to static.No address
: Not to assign a public IP address.- (Optional) Enable DDoS protection.
- Enter a subnet ID or select a cloud network from the list. If you do not have a network, click Create network to create one:
- Under Access, specify the data for access to the VM:
-
Enter the username into the Login field.
Alert
Do not use
root
or other usernames reserved by the operating system. To perform operations requiring superuser permissions, use thesudo
command. -
In the SSH key field, paste the contents of the public key file.
-
- Click Create VM.
-
View the description of the CLI command to create a VM:
yc compute instance create --help
-
Prepare the public and private key pair for SSH access to the 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 | ... +----------------------+-------------------------------------+--------------------------+----------------------+--------+
-
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 only once: when creating a VM. If the internal FQDN is important to you, choose an appropriate name for the VM at the creation stage.
-
--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 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 namedyc-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 the public and private key pair for SSH access to the VM.
-
Get an Yandex Identity and Access Management token used for authentication in the examples:
- Guide for users with a Yandex account.
- How to get a token 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 information about the latest image in this 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}"
-
To learn more about the image, see 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 to assign to the VM when you create it. -
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 details. -
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:"primaryV4AddressSpec": { "oneToOneNatSpec": { "ipVersion": "IPV4" } }
-
-
serviceAccountId
: ID of the service account created in the previous step.
Read more about the request body format in 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 tokenIAM tokenDocker credential helper-
If you do not have an OAuth token yet, get one by following this link
. -
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.
-
Get an Identity and Access Management token.
-
Run this command:
yc iam create-token | docker login --username iam --password-stdin cr.yandex
Result:
... Login succeeded
-
If you do not have a YC CLI profile yet, create one.
-
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
Credential Helper only works when using Docker without
sudo
. You can learn how to configure Docker to run under current user withoutsudo
in the official documentation . -
Make sure that Docker is configured.
The following line must appear in the
/home/<user>/.docker/config.json
configuration file:"cr.yandex": "yc"
-
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 a 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.