Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Integration with Container Registry

Written by
Improved by
Updated at November 21, 2025

Yandex Container Registry offers storage and distribution of Docker images. By integrating it, you enable Managed Service for Kubernetes to run pods with applications from Docker images stored in the Container Registry. To use Container Registry, set up a Docker credential helper. It enables access to private registries using a service account.

To integrate Managed Service for Kubernetes with Container Registry:

  1. Create service accounts.
    1. Create a service account for resources.
    2. Create a service account for Managed Service for Kubernetes nodes.
  2. Create security groups.
  3. Create the required Kubernetes resources.
    1. Create a Managed Service for Kubernetes cluster.
    2. Create a Managed Service for Kubernetes node group.
  4. Create the required Container Registry resources.
    1. Create a registry.
    2. Configure a credential helper.
    3. Set up a Docker image.
  5. Connect to the Managed Service for Kubernetes cluster.
  6. Run the test app.
  7. Delete the resources you created.

Getting started

Go to the Yandex Cloud management console and select the folder where you want to perform the operations. If that folder does not exist, create it:

  1. In the management console, select the appropriate cloud from the list on the left.

  2. At the top right, click Create folder.

  3. Give your folder a name. The naming requirements are as follows:

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

  4. Optionally, specify the description for your folder.

  5. Select Create a default network. This will create a network with subnets in each availability zone. Within this network, you will also have a default security group, within which all network traffic will be allowed.

  6. Click Create.

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

  1. View the description of the create folder command:

    yc resource-manager folder create --help

  2. Create a new folder:

    • with a name and without a description:

      yc resource-manager folder create \
   --name new-folder
      • 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.

    • with a name and description:

      yc resource-manager folder create \
   --name new-folder \
   --description "my first folder with description"

Use the create method for the Folder resource of the Yandex Resource Manager service.

The support cost for this solution includes:

Create service accounts

Create these service accounts:

  • Service account for resources with the k8s.clusters.agent and vpc.publicAdmin roles for the folder to host the new Managed Service for Kubernetes cluster. This service account will be used to create resources for your Managed Service for Kubernetes cluster.
  • Service account for Managed Service for Kubernetes nodes with the container-registry.images.puller role for the folder containing the Docker image registry. The Managed Service for Kubernetes nodes will use this account to pull the required Docker images from the registry.

Create a service account for resources

To create a service account that will be used to create the resources for the Managed Service for Kubernetes cluster:

  1. Save the folder ID from your CLI profile configuration to a variable:

    FOLDER_ID=$(yc config get folder-id)

    $FOLDER_ID = yc config get folder-id

  2. Create a service account:

    yc iam service-account create --name k8s-res-sa-$FOLDER_ID

    yc iam service-account create --name k8s-res-sa-$FOLDER_ID

  3. Save the service account ID to a variable:

    RES_SA_ID=$(yc iam service-account get --name k8s-res-sa-${FOLDER_ID} --format json | jq .id -r)

    $RES_SA_ID = (yc iam service-account get --name k8s-res-sa-$FOLDER_ID --format json | ConvertFrom-Json).id

  4. Assign the k8s.clusters.agent role for the folder to the service account:

    yc resource-manager folder add-access-binding \
  --id $FOLDER_ID \
  --role k8s.clusters.agent \
  --subject serviceAccount:$RES_SA_ID

  5. Assign the vpc.publicAdmin role for the folder to the service account:

    yc resource-manager folder add-access-binding \
  --id $FOLDER_ID \
  --role vpc.publicAdmin \
  --subject serviceAccount:$RES_SA_ID

Create a service account for cluster nodes

To create a service account the Managed Service for Kubernetes nodes will use to pull the required Docker images from the registry:

  1. Save the folder ID from your CLI profile configuration to a variable:

    FOLDER_ID=$(yc config get folder-id)

    $FOLDER_ID = yc config get folder-id

  2. Create a service account:

    yc iam service-account create --name k8s-node-sa-$FOLDER_ID

    yc iam service-account create --name k8s-node-sa-$FOLDER_ID

  3. Save the service account ID to a variable:

    NODE_SA_ID=$(yc iam service-account get --name k8s-node-sa-${FOLDER_ID} --format json | jq .id -r)

    $NODE_SA_ID = (yc iam service-account get --name k8s-node-sa-$FOLDER_ID --format json | ConvertFrom-Json).id

  4. Assign the container-registry.images.puller role for the folder to the service account:

    yc resource-manager folder add-access-binding \
  --id $FOLDER_ID \
  --role container-registry.images.puller \
  --subject serviceAccount:$NODE_SA_ID

Create security groups

Create security groups for the Managed Service for Kubernetes cluster and its node groups.

Warning

The configuration of security groups determines the performance and availability of the cluster and the services and applications running in it.

Set up Kubernetes resources

Create a Managed Service for Kubernetes cluster

Tip

In this example, the basic cluster parameters are used. Once the cluster is created, you cannot change some of the settings, e.g., the choice of the Container Network Interface, the use of Yandex Key Management Service for secret encryption, and a number of others. We recommend you to check out this detailed guide on creating a Managed Service for Kubernetes cluster.

Create a Managed Service for Kubernetes cluster and specify the previously created service accounts in the --service-account-id and --node-service-account-id parameters and security groups in the --security-group-ids parameter.

Run this command:

yc managed-kubernetes cluster create \
  --name k8s-demo \
  --network-name yc-auto-network \
  --zone ru-central1-a \
  --subnet-name yc-auto-subnet-0 \
  --public-ip \
  --service-account-id $RES_SA_ID \
  --node-service-account-id $NODE_SA_ID \
  --security-group-ids <security_group_IDs>

Run this command:

yc managed-kubernetes cluster create `
  --name k8s-demo `
  --network-name yc-auto-network `
  --zone ru-central1-a `
  --subnet-name yc-auto-subnet-0 `
  --public-ip `
  --service-account-id $RES_SA_ID `
  --node-service-account-id $NODE_SA_ID `
  --security-group-ids <security_group_IDs>

Create a Managed Service for Kubernetes node group

  1. Make sure the Managed Service for Kubernetes cluster was created successfully.

    1. In the management console, select the folder the Managed Service for Kubernetes cluster was created in.
    2. In the list of services, select Managed Service for Kubernetes.
    3. Check that your Managed Service for Kubernetes cluster was created successfully:
      • The Status column should state Running.
      • The State column should state Healthy.

  2. Create a Managed Service for Kubernetes node group and specify the previously created security groups in the --network-interface security-group-ids parameter:

    yc managed-kubernetes node-group create \
  --name k8s-demo-ng \
  --cluster-name k8s-demo \
  --platform standard-v3 \
  --cores 2 \
  --memory 4 \
  --core-fraction 50 \
  --disk-type network-ssd \
  --fixed-size 2 \
  --network-interface subnets=yc-auto-subnet-0,ipv4-address=nat,security-group-ids=[<security_group_IDs>] \
  --async

    yc managed-kubernetes node-group create `
  --name k8s-demo-ng `
  --cluster-name k8s-demo `
  --platform standard-v3 `
  --cores 2 `
  --memory 4 `
  --core-fraction 50 `
  --disk-type network-ssd `
  --fixed-size 2 `
  --network-interface subnets=yc-auto-subnet-0,ipv4-address=nat,security-group-ids=[<security_group_IDs>] `
  --async

Create Container Registry resources

Create a registry

Create a container registry:

yc container registry create --name yc-auto-cr

Configure a Docker credential helper

To simplify authentication in Container Registry, configure a Docker credential helper. It enables you to use private Yandex Cloud registries without running the docker login command.

To configure a credential helper, run this command:

yc container registry configure-docker

Set up a Docker image

Build a Docker image and push it to the registry.

  1. Create a Dockerfile named hello.dockerfile and paste the following lines into it:

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

  2. Build the Docker image.

    1. Get the ID of the previously created registry and save it to a variable:

      REGISTRY_ID=$(yc container registry get --name yc-auto-cr --format json | jq .id -r)

      $REGISTRY_ID = (yc container registry get --name yc-auto-cr --format json | ConvertFrom-Json).id

    2. Build the Docker image:

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

    3. Push the Docker image to the registry:

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

  3. Make sure the image is now in the registry:

    yc container image list

    Result:

    +----------------------+---------------------+-----------------------------+-------+-----------------+
|          ID          |       CREATED       |            NAME             | TAGS  | COMPRESSED SIZE |
+----------------------+---------------------+-----------------------------+-------+-----------------+
| crpa2mf008mp******** | 2019-11-20 11:52:17 | crp71hkgiolp********/ubuntu | hello | 27.5 MB         |
+----------------------+---------------------+-----------------------------+-------+-----------------+

Connect to the Managed Service for Kubernetes cluster

Install kubect and configure it to work with the new cluster.

Run the test app

Run the pod with the app from the Docker image and make sure no additional authentication in Container Registry was required to push the Docker image.

  1. Run the pod with the app from the Docker image:

    kubectl run --attach hello-ubuntu --image cr.yandex/${REGISTRY_ID}/ubuntu:hello

  2. Check the running pod and view its full name:

    kubectl get po

    Result:

    NAME                           READY  STATUS     RESTARTS  AGE
hello-ubuntu-5847fb9***-*****  0/1    Completed  3         61s

  3. Check the logs of the container running on that pod:

    kubectl logs hello-ubuntu-5847fb9***-*****

    Result:

    Hi, I'm inside

    The pod pulled the Docker image with no additional authentication required on the Container Registry side.

Delete the resources you created

Some resources are not free of charge. Delete the resources you no longer need to avoid paying for them:

  1. Delete the Managed Service for Kubernetes cluster:

    yc managed-kubernetes cluster delete --name k8s-demo

  2. Delete the service accounts:

    Warning

    Do not delete the service account until you delete the Managed Service for Kubernetes cluster.

    • Delete the service account for resources:

      yc iam service-account delete --id $RES_SA_ID

    • Delete the service account for Managed Service for Kubernetes nodes:

      yc iam service-account delete --id $NODE_SA_ID

  3. Delete the Container Registry resources.

    1. Get the name of the Docker image pushed to the registry:

      IMAGE_ID=$(yc container image list --format json | jq .[0].id -r)

      $IMAGE_ID = (yc container image list --format json | ConvertFrom-Json).id

    2. Delete the Docker image:

      yc container image delete --id $IMAGE_ID

    3. Delete the registry:

      yc container registry delete --name yc-auto-cr

See also

Previous
Installing an NGINX ingress controller with a Certificate Manager certificate
Next
Signing and verifying Container Registry Docker images