Yandex Cloud
  • Services
  • Solutions
  • Why Yandex Cloud
  • Pricing
  • Documentation
  • Contact us
Get started
Language / Region
© 2022 Yandex.Cloud LLC
Yandex Container Registry
  • Getting started
  • Step-by-step instructions
    • All instructions
    • Authenticating in Yandex Container Registry
    • Managing a Docker image
      • Getting information about available Docker images
      • Creating a Docker image
      • Pushing a Docker image to a registry
      • Pulling a Docker image from a registry
      • Deleting a Docker image from a registry
    • Managing Helm charts
      • Getting information about available Helm charts
      • Pushing a Helm chart to a registry
      • Pulling a Helm chart from a registry
      • Deleting a Helm chart from a registry
    • Managing a registry
      • Getting information about existing registries
      • Creating a registry
      • Updating a registry
      • Deleting a registry
    • Managing a repository
      • Getting information about existing repositories
    • Managing policies for automatically deleting Docker images
      • Getting information about existing lifecycle policies
      • Creating a lifecycle policy
      • Updating a lifecycle policy
      • Performing lifecycle policy dry runs
      • Deleting a lifecycle policy
    • Scanning Docker images for vulnerabilities
    • Working with roles
      • Assigning a role
      • Viewing assigned roles
      • Revoking a role
  • Yandex Container Solution
  • Practical guidelines
    • All tutorials
    • Running a Docker image on a VM
    • Setting up automatic scanning of a Docker image
  • Concepts
    • Overview
    • Docker image
    • Docker volume
    • Registry
    • Repository
    • Docker policies for automatically deleting Docker images
    • Vulnerability scanner
    • Backups
    • Quotas and limits
  • Access management
  • Pricing policy
  • API reference
    • Authentication in the API
    • gRPC
      • Overview
      • ImageService
      • LifecyclePolicyService
      • RegistryService
      • RepositoryService
      • ScannerService
      • OperationService
    • REST
      • Overview
      • Image
        • Overview
        • delete
        • get
        • list
      • LifecyclePolicy
        • Overview
        • create
        • delete
        • dryRun
        • get
        • getDryRunResult
        • list
        • listDryRunResultAffectedImages
        • listDryRunResults
        • update
      • Registry
        • Overview
        • create
        • delete
        • get
        • list
        • listAccessBindings
        • listIpPermission
        • setAccessBindings
        • setIpPermission
        • update
        • updateAccessBindings
        • updateIpPermission
      • Repository
        • Overview
        • delete
        • get
        • getByName
        • list
        • listAccessBindings
        • setAccessBindings
        • updateAccessBindings
        • upsert
      • Scanner
        • Overview
        • get
        • getLast
        • list
        • listVulnerabilities
        • scan
  • Troubleshooting
  • Questions and answers
  1. Step-by-step instructions
  2. Authenticating in Yandex Container Registry

Authentication in Container Registry

Written by
Yandex Cloud
,
improved by
Alexey K.
  • Authentication methods
  • Authenticate as a user
    • Authentication using an OAuth token
    • Authentication using an IAM token
  • Authenticate as a service account
    • Authentication using authorized keys
    • Authentication using an IAM token
  • Authenticate using a Docker Credential helper
    • Configuring a Credential helper
    • Additional Credential helper features

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 the username parameter. Acceptable values: oauth, iam, or json_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.

  1. If you don't have an OAuth token, get one via link.

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

  1. Get an IAM token.

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

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

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.

  1. Get an IAM token.

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

  1. If you don't have a YC CLI profile yet, create one.

  2. 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 the sudo command, see the official documentation.

  3. Make sure that Docker is configured.

    The /home/<user>/.docker/config.json file must contain the following line:

    "cr.yandex": "yc"
    
  4. 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.

Was the article helpful?

Language / Region
© 2022 Yandex.Cloud LLC
In this article:
  • Authentication methods
  • Authenticate as a user
  • Authentication using an OAuth token
  • Authentication using an IAM token
  • Authenticate as a service account
  • Authentication using authorized keys
  • Authentication using an IAM token
  • Authenticate using a Docker Credential helper
  • Configuring a Credential helper
  • Additional Credential helper features