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 or Yandex Managed Service for Kubernetes, the minimum required role for the registry or repository is
container-registry.images.puller
.
Assign the proper role to a Yandex Cloud user or service account. 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 (lifetime is one year).
- Using an Yandex Identity and Access Management token (maximum lifetime is 12 hours).
-
As a service account:
- Using authorized keys (unlimited lifetime).
- Using an Identity and Access Management token (maximum lifetime is 12 hours).
- Using a secret of the service account of the external Kubernetes cluster or external node group managed by Managed Service for Kubernetes.
The authentication command looks like this:
docker login \
--username <token_type> \
--password <token> \
cr.yandex
Where:
--username
: Token type. Acceptable values:oauth
,iam
, orjson_key
.--password
: 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.
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
-
If you do not have an OAuth token yet, get one by following this link
. -
Run this command:
docker login \ --username oauth \ --password <OAuth token> \ cr.yandex
Authentication using an Identity and Access Management 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 this 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.
Your programs can get access to Yandex Cloud resources using service accounts. Get a file with authorized keys for your service account through the Yandex Cloud CLI.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
-
Get authorized keys for your service account and save them to the
key.json
file:yc iam key create --service-account-name default-sa -o key.json
Result:
id: aje8a87g4eaj******** service_account_id: aje3932acde3******** created_at: "2019-05-31T16:56:47Z" key_algorithm: RSA_2048
-
Run this command:
cat key.json | docker login \ --username json_key \ --password-stdin \ cr.yandex
Where:
- 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.
Result:
Login succeeded
- The
Authentication using an Identity and Access Management 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 this command:
docker login \ --username iam \ --password <IAM token> \ cr.yandex
Authentication using a Kubernetes secret
Note
These instructions only apply to external Kubernetes clusters and external nodes managed by Managed Service for Kubernetes.
For a node placed in Yandex Compute Cloud to pass authentication, assign the container-registry.images.puller
role to this node's service account.
If you do not have the Yandex Cloud command line interface yet, install and initialize it.
Kubernetes resources can get access to Container Registry objects using Kubernetes secrets created based on keys of service accounts.
To prepare this secret:
-
Get an authorized key for your service account and save it to the
key.json
file:yc iam key create --service-account-name <service_account_name> -o key.json
-
Run the authentication command:
cat key.json | docker login \ --username json_key \ --password-stdin \ cr.yandex
Result:
Login succeeded
If any errors occur, see Troubleshooting in Container Registry.
-
Make sure that the key is in the correct format. To do this, open the Docker configuration file:
cat $HOME/.docker/config.json
Result:
{ "auths": { "cr.yandex": { "auth": "anNvbl9rZXk ... tXG4iCn0=" } } }
Note
Previously configured access to Docker may prevent a key from being received in the correct format. To get the correct key, disable a credential helper or delete the existing
$HOME/.docker/config.json
file. -
Create a secret in your Kubernetes cluster:
kubectl create secret generic <secret_name> \ --namespace=<namespace> \ --from-file=.dockerconfigjson=$HOME/.docker/config.json \ --type=kubernetes.io/dockerconfigjson
You can specify, for example,
kube-system
as a namespace. Managed Service for Kubernetes will use this namespace after you create a node group. -
Use the secret to create pods or Deployment controllers, for example:
--- apiVersion: v1 kind: Pod metadata: name: <pod_name> namespace: <namespace> spec: containers: - name: <name_of_your_container> image: <container_image_name> imagePullSecrets: - name: <secret_name>
When creating secrets and pods, make sure to specify the same namespace for them in the
namespace
parameter; otherwise, an authentication error will occur.
For more information, see the Kubernetes documentation
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
The 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. This authentication method supports operations on behalf of a user and service account.
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
.