Discuss with expertTry it for free
© 2026 Direct Cursus Technology L.L.C.

Authentication in Cloud Registry

Written by
Updated at July 23, 2026
View in Markdown

Before you start using Cloud Registry, you need to configure Docker and get authenticated for the appropriate interface:

  • For the management console, the minimum required role for a folder is viewer.
  • For the Docker CLI or Yandex Managed Service for Kubernetes, the minimum required role for a registry is cloud-registry.artifacts.puller.

Assign the required role to the Yandex Cloud user. Read about authentication methods and select the one that works best for you.

For more information about roles, see Access management in Yandex Cloud Registry.

Authentication methods

You can get authenticated:

Authenticating as a user

Note

The IAM token has a short lifetime of up to 12 hours. This makes it a good method for applications that automatically request an IAM token.

  1. If you do not have Docker yet, install it.

  2. Get an IAM token.

  3. Run this command:

    echo <IAM_token> | docker login \
  --username iam \
  --password-stdin \
  registry.yandexcloud.net

    Where:

    • <IAM_token>: Body of the previously obtained IAM token.
    • --username: Token type. iam means that an IAM token is used for authentication.
    • registry.yandexcloud.net: Endpoint that Docker will access when working with the Docker image registry. If it not specified, the request will be sent to the default service, Docker Hub.

  1. If you do not have Docker yet, install it.

  2. Create an API key for the service account you are going to use for authentication.

  3. Run this command:

    echo <API_key> | docker login \
  --username api_key \
  --password-stdin \
  registry.yandexcloud.net

    Where:

    • <API_key>: Body of the previously created API key.
    • --username: Token type. api_key means that an API key is used for authentication.
    • registry.yandexcloud.net: Endpoint that Docker will access when working with the image registry. If it not specified, the request will be sent to the default service, Docker Hub.

If the command returns the docker login is not supported with yc credential helper error message, disable your Docker credential helper.

Authenticating with a Docker credential helper

Docker Engine can keep user credentials in an external credential store. This is a more secure option than using a Docker configuration file. To use a credential store, you need an external program, Docker credential helper.

The Yandex Cloud CLI provides docker-credential-yc as a Docker credential helper for Yandex Cloud. It stores user credentials and enables you to use private Yandex Cloud registries without running the docker login command.

Configuring a credential helper

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

The folder used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

  1. Configure Docker to use docker-credential-yc:

    yc cloud-registry configure-docker

    Result:

    Credential helper is configured in '/home/<user>/.docker/config.json'

    The current user’s profile stores the settings.

    Warning

    The credential helper only works if you use Docker without sudo. To learn how to configure Docker to run on behalf of the current user without sudo, see this Docker guide.

  2. Make sure Docker is configured.

    The ${HOME}/.docker/config.json configuration file should now contain this line:

    "registry.yandexcloud.net": "yc"

  3. You can now use Docker, e.g., to push Docker images.

Additional credential helper features

Using the credential helper for a different Yandex Cloud CLI profile

You can use the credential helper for another profile, without switching from the current one, by running the following command:

yc cloud-registry configure-docker --profile <profile_name>

For more information about profile management, see these Yandex Cloud CLI step-by-step guides.

Disabling a credential helper

To stop using a credential helper for authentication, delete the registry.yandexcloud.net domain line from the credHelpers section in the ${HOME}/.docker/config.json configuration file.

Previous
Installing and configuring Docker
Next
Creating a Docker image