Authentication in Container Registry
Read about authentication methods and choose the appropriate one.
If you don't have the Nebius AI command line interface yet, install and initialize it.
Authentication methods
You can authenticate:
- As a service account:
- Using authorized keys (unlimited lifetime).
- Using an Identity and Access Management token (maximum lifetime is 12 hours).
- Using a Docker Credential helper credential store.
The authentication command looks like this:
docker login \
--username <token type> \
--password <token> \
cr.ai.nebius.cloud
Where:
username
: Token type. Acceptable values:iam
, orjson_key
.password
: Token body.cr.ai.nebius.cloud
: 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 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.
-
[Get an Identity and Access Management token].
-
Run this command:
docker login \ --username iam \ --password <Identity and Access Management token> \ cr.ai.nebius.cloud
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 Nebius AI resources using service accounts. Get a file with authorized keys for your service account via the Nebius AI CLI.
-
Get and save authorized keys for your service account in the
key.json
file:ncp iam key create --service-account-name default-sa -o key.json
Result:
id: aje8a87g4e... service_account_id: aje3932acd... 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.ai.nebius.cloud
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 <Identity and Access Management token> \ cr.ai.nebius.cloud
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
Nebius AI CLI uses docker-credential-yc
as a Docker Credential helper for Nebius AI. It stores user credentials and lets you use private Nebius AI 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 don't have the Nebius AI 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
:ncp 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.ai.nebius.cloud": "ncp"
-
You can now use Docker, for example, to push Docker images.
Additional Credential helper features
Using a Credential helper for a different Nebius AI CLI profile
You can use the Credential helper for another profile, without switching from the current one, by running the following command:
ncp container registry configure-docker --profile <profile name>
For more information about Nebius AI 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.ai.nebius.cloud
domain line under credHelpers
.