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

If you do not have OpenSSH installed yet, follow this guide to install it.

1. Run cmd.exe or powershell.exe (make sure to update PowerShell before doing so).

2. Use the ssh-keygen command to create a new key:

   ssh-keygen -t ed25519 -C "<optional_comment>"
   

   You can specify an empty string in the -C parameter to avoid adding a comment, or you may not specify the -C parameter at all: in this case, a default comment will be added.

   After running this command, you will be prompted to specify the name and path to the key files, as well as enter the password for the private key. If you only specify the name, the key pair will be created in the current directory. The public key will be saved in a file with the .pub extension, while the private key, in a file without extension.

   By default, the command prompts you to save the key under the id_ed25519 name in the following folder: C:\Users\<username>/.ssh. If there is already an SSH key named id_ed25519 in this directory, you may accidentally overwrite it and lose access to the resources it is used in. Therefore, you may want to use unique names for all SSH keys.

Create keys using the PuTTY app:

1. Download and install PuTTY.

2. Add the folder with PuTTY to the PATH variable:

   1. Click Start and type Change system environment variables in the Windows search bar.
   2. Click Environment Variables... at the bottom right.
   3. In the window that opens, find the PATH parameter and click Edit.
   4. Add your folder path to the list.
   5. Click OK.

3. Launch the PuTTYgen app.

4. Select EdDSA as the pair type to generate. Click Generate and move the cursor in the field above it until key creation is complete.

   

5. In Key passphrase, enter a strong password. Enter it again in the field below.

6. Click Save private key and save the private key. Do not share its key phrase with anyone.

7. Click Save public key and save the public key to a file named <key_name>.pub.

Download and install the Docker Desktop distribution for macOS. For more information, see the developer documentation.

1. Download and install the Docker Desktop distribution for Windows.

2. After the installation is complete, add the current user to the docker-users group:

   1. Run Computer Management as administrator:

      compmgmt.msc
      

   2. Expand the (Local) Computer Management menu, then go to Utilities → Local Users and Groups → Groups and open the docker-users group.

   3. Click Add and add the required user to the group.

   4. Click OK.

3. Run Docker Desktop and make sure the app status is running.

For information about additional Docker settings for Windows, see the developer documentation.

If you do not have the Yandex Cloud CLI installed yet, install and initialize it.

By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

1. Make sure that a registry has not been created in the folder yet:

   yc container registry list
   

   Result:

   +----+------+-----------+
   | ID | NAME | FOLDER ID |
   +----+------+-----------+
   +----+------+-----------+
   

   If the folder already contains a registry, see Updating a registry for info on how you can update it.

2. Create a registry:

   • With automated vulnerability scanning:

     yc container registry create --name my-reg --secure
     

     Warning

     Automatic Docker image scanning makes your registry more secure. The default vulnerability scan settings are consistent with the Yandex Cloud cloud infrastructure security standard.

   • Without automated vulnerability scanning:

     yc container registry create --name my-reg
     

   Result:

   done
   id: crpd50616s9a********
   folder_id: b1g88tflru0e********
   name: my-reg
   status: ACTIVE
   created_at: "2019-01-09T14:34:06.601Z"
   

   Follow these registry naming requirements:

   • It must be from 2 to 63 characters long.
   • It can only contain lowercase Latin letters, numbers, and hyphens.
   • It must start with a letter and cannot end with a hyphen.

   The --name parameter is optional. You can create a registry without a name and use its ID to access it. The name field is user-defined. It is used when listing in the Yandex Cloud CLI and not used in the Docker CLI.

3. Make sure the registry was created:

   yc container registry list
   

   Result:

   +----------------------+--------+----------------------+
   |          ID          |  NAME  |      FOLDER ID       |
   +----------------------+--------+----------------------+
   | crpd50616s9a******** | my-reg | b1g88tflru0e******** |
   +----------------------+--------+----------------------+
   

To create a registry, use the create method for the Registry resource.

If you do not have the Yandex Cloud CLI installed 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:

   By default, the CLI uses the folder specified when creating the profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also set a different folder for any specific command using the --folder-name or --folder-id parameter.

   yc iam service-account create --name images-puller
   

   Result:

   id: ajelabcde12f********
   folder_id: b0g12ga82bcv********
   created_at: "2020-11-30T14:32:18.900092Z"
   name: myservice-acc
   

3. Assign the container-registry.images.puller role to the service account:

   yc container registry add-access-binding <registry_name_or_ID> \
     --role container-registry.images.puller \
     --subject serviceAccount:<service_account_ID>
   

   Where --subject is the ID of the service account getting the role, e.g., ajelabcde12f********.

1. To create a service account, use the create REST API method for the ServiceAccount resource or the ServiceAccountService/Create gRPC API call.

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.

1. View the description of the CLI command to create a VM:

   yc compute instance create --help
   

2. Prepare a key pair (public and private keys) for SSH access to your VM.

3. 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.

4. 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] |
   +----------------------+---------------------------+----------------------+----------------+-------------------+-----------------+
   

5. 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 REST API method for the Instance resource:

1. Prepare a key pair (public and private keys) for SSH access to your VM.

2. Get a Yandex Identity and Access Management token used for authentication in the examples:

   • Guide for users with a Yandex account.
   • Guide for service accounts.

3. Get the ID of the folder.

4. 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.

5. 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"
     },
     ...
     ]}
   

6. 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.

7. 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