Authentication in Container Registry
Before you start using Container Registry, you need to authenticate for the corresponding interface:
- In the Management console, the minimum required folder role is
viewer
. - In the Docker CLI, the minimum required role for the registry or repository is
container-registry.images.puller
.
For more information about roles, see Access management in Container Registry.
You can authenticate as a user or service account. Read about authentication methods and choose the appropriate one.
Authentication methods
You can authenticate:
- As a user:
- Using an OAuth token (lifetime is one year).
- Using an IAM token (lifetime is no longer than 12 hours).
- As a service account:
- Using authorized keys (no expiration).
- Using an IAM token (lifetime is no longer than 12 hours).
- Using a credentials store via a Docker Credential helper.
The authentication command looks like this:
docker login \
--username <token type> \
--password <token> \
cr.yandex
- Pass the token type in
<token type>
to theusername
parameter. Acceptable values:oauth
,iam
, orjson_key
. - Pass the token itself to the
password
parameter. - After specifying all the parameters, set
cr.yandex
as the address for authentication. Otherwise, the request will be sent to the default service, Docker Hub.
Authenticate as a user
Authentication using an OAuth token
Note
The validity period of an OAuth token is one year. Then you must get new OAuth token and repeat the authentication process.
-
If you don't have an OAuth token, get one via link.
-
Run the command:
docker login \ --username oauth \ --password <OAuth token> \ cr.yandex
Authentication using an IAM token
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.
-
Run the command:
docker login \ --username iam \ --password <IAM token> \ cr.yandex
Authenticate as a service account
Authentication using authorized keys
Note
Authorized keys do not expire, but you can always get new authorized keys and authenticate again if something goes wrong.
Using a service account, your programs can access Yandex Cloud resources. Get a file with authorized keys for your service account via the CLI.
-
Get authorized keys for your service account:
yc iam key create --service-account-name default-sa -o key.json id: aje8a87g4e... service_account_id: aje3932acd... created_at: "2019-05-31T16:56:47Z" key_algorithm: RSA_2048
-
Run the command:
cat key.json | docker login \ --username json_key \ --password-stdin \ cr.yandex Login Succeeded
- The
cat key.json
command writes the contents of the key file to the output stream. - The
--password-stdin
flag allows the password to be read from the input stream.
- The
Authentication using an IAM token
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.
-
Run the command:
docker login \ --username iam \ --password <IAM token> \ 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 credentials store, you need an external Docker Credential helper.
Yandex Cloud uses docker-credential-yc
as a Docker Credential helper. It stores user credentials and lets you use private Yandex Cloud registries without running the docker login
command. This authentication method supports operations on behalf of a user and service account. To work with docker-credential-yc
, you need the Yandex Cloud command-line interface: YC CLI.
You don't need to install the docker-credential-yc
separately: just install the YC CLI and configure the Credential helper following the description below.
Configuring a Credential helper
-
If you don't have a YC CLI profile yet, create one.
-
Configure Docker to use
docker-credential-yc
:yc container registry configure-docker Credential helper is configured in '/home/<user>/.docker/config.json'
Settings are saved in the current user's profile.
Warning
The Credential helper only works when using Docker without
sudo
. For information about how to configure Docker to run as the current user without using thesudo
command, see the official documentation. -
Make sure that Docker is configured.
The
/home/<user>/.docker/config.json
file must contain the following line:"cr.yandex": "yc"
-
You can now use Docker, for example, to push Docker images. You don't need to run
docker login
for that.
Additional Credential helper features
Using a Credential helper for a different YC 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 YC CLI profile management, see the step-by-step instructions.
Disabling a Credential helper
To avoid using Credential helpers for authentication, remove the cr.yandex
domain string from the credHelpers
block in the /home/<user>/.docker/config.json
file.