Contact usConsole
© 2023 Nebius Israel Ltd
Container Registry

Running a Docker image on a VM

This tutorial describes the steps required to run a Docker image on a VM using the Container Solution registry.

To run a Docker image on a VM using the registry:

  1. Prepare your cloud.
  2. Create a service account.
  3. Create a VM.
  4. Build and upload the Docker image to Container Registry.
  5. Download the Docker image to a VM.
  6. Check the result.

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

You can also deploy an infrastructure for running a Docker image on a VM via Terraform using a ready-made configuration file.

Getting started

Sign up for Nebius Israel and create a billing account:

  1. Go to the management console and log in to Nebius Israel or create an account if you do not have one yet.
  2. On the Billing page in the management console, 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.

If you have an active billing account, you can go to the cloud page to create or select a folder to run your infrastructure.

Learn more about clouds and folders.

Configure the environment

  1. Install the Nebius Israel command line interface.
  2. Prepare an SSH key for VM access.
  3. Create a registry in Container Solution to store the Docker image.
  4. Install Docker.

Create a service account

  1. Create a service account and grant it the container-registry.images.puller role for the previously created registry:

    1. In the management console, select a folder where you wish to create a service account.
    2. At the top of the screen, go to the Service accounts tab.
    3. Click Create service account.
    4. Enter the service account name and click Create.
    5. In the list of services, select Container Registry.
    6. Select the registry and click the row with its name.
    7. Click the Access bindings tab.
    8. In the top-right corner, click Assign roles.
    9. Click + Select subject and add the service account by supplying its ID.
    10. Click Add role and select container-registry.images.puller.
    11. Click Save.

    If you don't have the Nebius Israel 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 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: ajelabcde12f33nol1v5
folder_id: b0g12ga82bcv0cdeferg
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>|<resource_ID> \
  --role <role_ID> \
  --subject serviceAccount:<service_account_ID>

      Where:

      • <service_name>: container service name.
      • <resource>: Category of the registry resource.
      • <resource_name>: Name of the resource to grant the role to. You can specify a resource by its name or ID.
      • <resource_ID>: crpc9qeoft236r8tfalm registry ID to assign the role to.
      • <role_ID>: container-registry.images.puller role ID.
      • <service_account_ID>: ID of the service account (such as ajelabcde12f33nol1v5) being granted the role.

    Use the updateAccessBindings method for the registry resource.

Create a VM

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

    1. In the management console, select the folder to create your VM in.

    2. In the list of services, select Compute Cloud.

    3. Click Create VM.

    4. Under Basic parameters:

      • Enter a name and description for the VM. The naming requirements are as follows:

        • The length can be from 3 to 63 characters.
        • It may contain lowercase Latin letters, numbers, and hyphens.
        • The first character must be a letter. The last character can't 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 recently created service account.

      • Select an availability zone to place your VM in.

    5. Under Images from Cloud Marketplace, select an image and a Linux-based OS version.

    6. (Optional) Configure a 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.

    7. Under Computing resources:

    8. Under Network settings:

      • Enter a subnet ID or select a cloud network from the list. If you do not have a network, click Create a new 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.
      • In the Public IP field, choose a method for assigning an IP address:
        • Auto: Assign a random IP address from the Nebius Israel IP 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: Do not assign a public IP address.

    9. Under Access, specify the information required to access the instance:

      • Enter the username in the Login field.

        Alert

        Do not use the root username or other names reserved by the operating system. To perform operations that require superuser permissions, use the sudo command.

      • In the SSH key field, paste the contents of the public key file.

    10. Click Create VM.

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

      yc compute instance create --help

    2. Prepare the key pair (public and private keys) for SSH access to the 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 Nebius Israel 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                 | dqni65lfhvv2den5gtv9 | READY  |
| fdv7ooobjfl3******** | windows-2016-gvlk-1548913814        | windows-2016-gvlk        | dqnnc72gj2ist3ktjj1p | READY  |
| fdv4f5kv5cvf******** | ubuntu-1604-lts-1549457823          | ubuntu-1604-lts          | dqnnb6dc7640c5i968ro | READY  |
...
+----------------------+-------------------------------------+--------------------------+----------------------+--------+

    4. View a list of available subnets:

      yc vpc subnet list

      Result:

      +----------------------+---------------------------+----------------------+----------------+-------------------+-----------------+
|          ID          |           NAME            |      NETWORK ID      | ROUTE TABLE ID |       ZONE        |      RANGE      |
+----------------------+---------------------------+----------------------+----------------+-------------------+-----------------+
| b0c6n43f9lgh3695v2k2 | default-il1-c | enpe3m3fa00udao8g5lg |                | il1-c | [10.130.0.0/24] |
| e2l2da8a20b33g7o73bv | default-il1-b | enpe3m3fa00udao8g5lg |                | il1-b | [10.129.0.0/24] |
| e9bnlm18l70ao30pvfaa | default-il1-a | enpe3m3fa00udao8g5lg |                | il1-a | [10.128.0.0/24] |
+----------------------+---------------------------+----------------------+----------------+-------------------+-----------------+

    5. Create a VM in the default folder:

      yc compute instance create \
  --name first-instance \
  --zone il1-a \
  --network-interface subnet-name=default-il1-a,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 that corresponds to the selected subnet.

      • subnet-name: Name of the selected subnet.

      • image-family: Image family, such as 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: Path to the public SSH key. 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:

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

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

      • Guide for a service account.

    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 information about the latest image in this family:

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

      • To learn more about the image, see 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=b1gvmob95yysaplct532
curl -H "Authorization: Bearer ${IAM_TOKEN}" \
  "https://vpc.api.il.nebius.cloud/vpc/v1/subnets?folderId=${FOLDER_ID}"
{
  "subnets": [
    {
      "v4CidrBlocks": [
        "10.130.0.0/24"
      ],
    "id": "b0c6n43ftldh30l0vfg2",
    "folderId": "b1gvmob95yysaplct532",
    "createdAt": "2018-09-23T12:15:00Z",
    "name": "default-il1-a",
    "description": "Auto-created default subnet for zone il1-a",
    "networkId": "enpe3m3fagludao8aslg",
    "zoneId": "il1-a"
  },
  ...
  ]}

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

      {
  "folderId": "b1gvmob95yysaplct532",
  "name": "instance-demo-no-pwauth",
  "zoneId": "il1-a",
  "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": "fd8rc75pn12fe3u2dnmb"
    }
  },
  "networkInterfaceSpecs": [
    {
      "subnetId": "b0c6n43ftldh30l0vfg2",
      "primaryV4AddressSpec": {
        "oneToOneNatSpec": {
          "ipVersion": "IPV4"
        }
      }
    }
  ],
  "serviceAccountId": "ajelabcde12f33nol1v5"
}

      Where:

      • folderId: Folder ID.
      • name: Name assigned to the VM upon creation.
      • zoneId: Availability zone that corresponds to the selected subnet.
      • platformId: Platform.
      • resourceSpec: Resources available to the VM. The values must match the selected platform.
      • metadata: In the metadata, provide the public key for VM access via SSH. For more information, see VM metadata.
      • bootDiskSpec: Boot disk settings. Specify the selected image ID and disk size. Set at least the minimum value specified in the image details.
      • networkInterfaceSpecs: Network setting:

        • subnetId: ID of the selected subnet.

        • primaryV4AddressSpec: IP address to assign to the VM. To add a public IP 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.

    1. Create a VM:

      export IAM_TOKEN=CggaATEVAgA...
curl -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${IAM_TOKEN}" \
  -d '@body.json' \
  https://compute.api.il.nebius.cloud/compute/v1/instances

Build and upload the Docker image to Container Registry

  1. To make command execution easier, add the following variables:

    • Username and your VM's public IP as ${PUBLIC_IP}:

      export PUBLIC_IP=<username>@<VM_public_IP_address>

    • ID of the previously created registry in crpc9qeoft236r8tfalm format as ${REGISTRY_ID}:

      export REGISTRY_ID=<registry_ID>

  2. Authenticate as yourself:

    Note

    The IAM token has a short lifetime — no more than 12 hours. That's why this is a good method for applications that automatically request an IAM token.

    1. Get an IAM token.

    2. Run the following command:

      yc iam create-token | docker login --username iam --password-stdin cr.il.nebius.cloud

      Result:

      ...
Login succeeded

    1. If you do not have a Nebius Israel 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

      Credential helper only works when using Docker without sudo. You can learn how to configure Docker to run under current user without sudo in the official documentation.

    3. Make sure that Docker is configured.

      The /home/<user>/.docker/config.json configuration file must include the following line:

      "cr.il.nebius.cloud": "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.

  3. Create a file called Dockerfile:

    touch .dockerfile

  4. Open Dockerfile in a text editor, such as:

    nano .dockerfile

  5. Add the lines below to the file:

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

  6. Build a Docker image:

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

    Result:

    ...
Successfully built b68ee9b6b1af
Successfully tagged cr.il.nebius.cloud/crpmnjr98tm54bejc46m/ubuntu:hello

  7. Push the built Docker image to Container Registry:

    docker push cr.il.nebius.cloud/${REGISTRY_ID}/ubuntu:hello

    Result:

    The push refers to repository [cr.il.nebius.cloud/crpc9qeoft236r8tfalm/ubuntu]
cc9d18e90faa: Pushed
0c2689e3f920: Pushed
47dde53750b4: Pushed
hello: digest: sha256:42068479274f1d4c7ea095482430dcba24dcfe8c23ebdf6d32305928e55071cf size: 943

Download the Docker image on the VM

  1. Use SSH to connect to the VM.

  2. Authenticate under the service account tied to the machine:

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

    Result:

    Login succeeded

  3. Download the Docker image to the VM:

    docker pull cr.il.nebius.cloud/${REGISTRY_ID}/ubuntu:hello

    Result:

    hello: Pulling from crpc9qeoft236r8tfalm/ubuntu
6a5697faee43: Pulling fs layer
ba13d3bc422b: Pulling fs layer
...
Digest: sha256:42068479274f1d4c7ea095482430dcba24dcfe8c23ebdf6d32305928e55071cf
Status: Downloaded newer image for cr.il.nebius.cloud/crpc9qeoft236r8tfalm/ubuntu:hello
cr.il.nebius.cloud/crpc9qeoft236r8tfalm/ubuntu:hello

Check the result

Run the Docker image on the VM:

docker run cr.il.nebius.cloud/${REGISTRY_ID}/ubuntu:hello

Result:

Hi, I'm inside

How to delete the resources you created

To stop paying for the resources you created:

How to create an infrastructure using Terraform

With Terraform, you can quickly create a cloud infrastructure in Nebius Israel and manage it using configuration files. They store the infrastructure description in HashiCorp Configuration Language (HCL). Terraform and its providers are distributed under the Business Source License.

For more information about the provider resources, see the documentation on the Terraform website.

If you change the configuration files, Terraform automatically determines which part of your configuration is already deployed and what should be added or removed.

To create an infrastructure for running a Docker image on a VM using the registry:

  1. Install Terraform and specify the source for installing the Nebius Israel provider (see Configure a provider, step 1).

  2. Prepare a file with the infrastructure description:

    1. Create a directory for the file with the infrastructure description.
    2. Download the archive (1.5 KB).
    3. Unpack the archive to the directory. As a result, it should contain the run-docker-on-vm.tf configuration file.

    1. Create a directory for the file with the infrastructure description.

    2. In the directory, create a configuration file named run-docker-on-vm.tf:

      Contents of the run-docker-on-vm.tf file
      locals {
  zone             = "<default_availability_zone>"
  username         = "<VM_username>"
  ssh_key_path     = "<path_to_public_SSH_key>"
  target_folder_id = "<VM_target_folder>"
  registry_name    = "<registry_name>"
  sa_name          = "<service_account_name>"
  network_name     = "<cloud_network_name>"
  subnet_name      = "<subnet_name>"
  vm_name          = "<VM_name>"
  image_id         = "<image_ID>"
}

terraform {
  required_providers {
    yandex    = {
      source  = "yandex-cloud/yandex"
      version = ">= 0.47.0"
    }
  }
}

provider "yandex" {
  zone = local.zone
}

resource "yandex_container_registry" "my-registry" {
  name       = local.registry_name
  folder_id  = local.target_folder_id
  labels     = {
    my-label = "my-label-value"
  }
}

resource "yandex_iam_service_account" "registry-sa" {
  name      = local.sa_name
  folder_id = local.target_folder_id
}

resource "yandex_resourcemanager_folder_iam_member" "registry-sa-role-images-puller" {
  folder_id = local.target_folder_id
  role      = "container-registry.images.puller"
  member    = "serviceAccount:${yandex_iam_service_account.registry-sa.id}"
}

resource "yandex_vpc_network" "docker-vm-network" {
  name = local.network_name
}

resource "yandex_vpc_subnet" "docker-vm-network-subnet-a" {
  name           = local.subnet_name
  zone           = local.zone
  v4_cidr_blocks = ["192.168.1.0/24"]
  network_id     = yandex_vpc_network.docker-vm-network.id
}

resource "yandex_compute_instance" "docker-vm" {
  name               = local.vm_name
  platform_id        = "standard-v3"
  zone               = local.zone
  service_account_id = "${yandex_iam_service_account.registry-sa.id}"

  resources {
    cores  = 2
    memory = 2
  }

  boot_disk {
    initialize_params {
      image_id = local.image_id
      size     = 5
    }
  }

  network_interface {
    subnet_id = "${yandex_vpc_subnet.docker-vm-network-subnet-a.id}"
    nat       = true
  }

  metadata = {
    user-data = "#cloud-config\nusers:\n  - name: ${local.username}\n    groups: sudo\n    shell: /bin/bash\n    sudo: 'ALL=(ALL) NOPASSWD:ALL'\n    ssh-authorized-keys:\n      - ${file("${local.ssh_key_path}")}"
  }
}

  3. Under locals, set the parameters for resources to create:

    • zone: Availability zone that will host the VM.
    • username: Name of the user to be created on the VM.
    • ssh_key_path: Path to the file with a public SSH key to authenticate the user on the VM. For details, see Creating an SSH key pair.
    • target_folder_id: ID of the folder to host the VM.
    • registry_name: Container Registry registry name.
    • sa_name: Service account name.
    • network_name: Name of the cloud network.
    • subnet_name: Name of the subnet.
    • vm_name: VM name.
    • image_id: ID of the image to create the VM from. For details, see Getting a list of public images.

  4. Create resources:

    1. In the terminal, change to the folder where you edited the configuration file.

    2. Make sure the configuration file is correct using the command:

      terraform validate

      If the configuration is correct, the following message is returned:

      Success! The configuration is valid.

    3. Run the command:

      terraform plan

      The terminal will display a list of resources with parameters. No changes are made at this step. If the configuration contains errors, Terraform will point them out.

    4. Apply the configuration changes:

      terraform apply

    5. Confirm the changes: type yes in the terminal and press Enter.

  5. Build and upload the Docker image to Container Registry

  6. Download the Docker image on the VM

  7. Check the result

© 2023 Nebius Israel Ltd
In this article: