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 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).
Authenticating as a user
Warning
To get authenticated in Container Registry using the docker login
command, disable Docker credential helper. For more information, see Troubleshooting in Container Registry.
The authentication command looks like this:
echo <token> | docker login \
--username <token_type> \
--password-stdin \
cr.yandex
Where:
--username
: Token type. The possible values areoauth
oriam
.<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 token
Note
An OAuth token lives 12 months. After that, you need to get a new one
-
If you do not have an OAuth token yet, get one by following this link
. -
Run this command:
echo <OAuth_token> | docker login \ --username oauth \ --password-stdin \ cr.yandex
Authentication using an Identity and Access Management token
Note
The IAM token has a short lifetime: no more than 12 hours. This makes it a good method for applications that automatically request an IAM token.
-
Run this command:
echo <IAM_token> | docker login \ --username iam \ --password-stdin \ cr.yandex
Authenticate 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
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 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.
-
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 withoutsudo
in the official documentation . -
Make sure that Docker is configured.
The
${HOME}/.docker/config.json
configuration file must include the following line:"cr.yandex": "yc"
-
You can now use Docker, for example, to push Docker images.
Additional credential helper features
Using 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 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
.