Authentication in Container Registry

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

• In the Management console, the minimum required folder role is viewer.
• In the Docker CLI or Yandex Managed Service for Kubernetes, the minimum required role for the registry or repository is container-registry.images.puller.

Assign the required role to the Yandex Cloud user. Read about authentication methods and choose the appropriate one.

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

Authentication methodsAuthentication methods

You can authenticate:

• As a user:

  • Using an OAuth token (with a 12-month lifetime).
  • Using an Yandex Identity and Access Management token (with a 12 hours lifetime or less).

• Using a Docker credential helper.

Authenticating as a userAuthenticating as a user

The authentication command looks like this:

echo <token> | docker login \
  --username <token_type> \
  --password-stdin \
  cr.yandex

Where:

• --username: Token type. The possible values are oauth or iam.
• <token>: Token body.
• cr.yandex: The endpoint that Docker will access when working with the image registry. If it not specified, the request will be sent to Docker Hub as the default service.

Authentication using an OAuth tokenAuthentication using an OAuth token

1. If you do not have an OAuth token yet, get one by following this link.

2. Run this command:

   echo <OAuth_token> | docker login \
     --username oauth \
     --password-stdin \
     cr.yandex
   

Authentication using an Identity and Access Management tokenAuthentication using an Identity and Access Management token

1. Get an Identity and Access Management token.

2. Run this command:

   echo <IAM_token> | docker login \
     --username iam \
     --password-stdin \
     cr.yandex
   

Authenticate using a Docker credential helperAuthenticate using a Docker credential helper

The Docker Engine can keep user credentials in an external credentials store. This is more secure than storing credentials in the Docker configuration file. To use a credential store, you need external Docker credential helper software.

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

Configuring a credential helperConfiguring a credential helper

If you do not have the Yandex Cloud command line interface yet, install and initialize it.

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.

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

2. Make sure that Docker is configured.

   The ${HOME}/.docker/config.json configuration file must include the following line:

   "cr.yandex": "yc"
   

3. You can now use Docker, for example, to push Docker images.

Additional credential helper featuresAdditional credential helper features

Using a credential helper for a different Yandex Cloud CLI profileUsing a 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 container registry configure-docker --profile <profile_name>

For more information about Yandex Cloud CLI profile management, see the step-by-step instructions.

Disabling a credential helperDisabling a credential helper

To avoid using a credential helper for authentication, edit the ${HOME}/.docker/config.json configuration file to remove the cr.yandex domain line under credHelpers.