docker-credential-acr-helper: A docker credential helper for Alibaba Cloud Container Registry (ACR)

Preface

Normally, if we want to do docker pull or docker push on private images on Alibaba Cloud Container Registry (ACR), we need to configure the corresponding access credentials via docker login command in advance.

The method of configuring a username and password via the docker login command has several problems, as follows:

  • Requires users to record and maintain an additional set of docker-specific passwords, and password management is a bit of a pain.
  • ACR only supports the configuration of a fixed password with no expiration time. The cost of password change and revocation is high, and users are easily afraid to operate.
  • It is not possible to finely configure the permissions for fixed passwords, and it is not possible to achieve the permission control requirements like only allowing pull operations but not push operations.
  • Although it is possible to obtain an unlimited number of temporary passwords through the Open API, docker login does not support the automatic refresh of temporary passwords. If you use a temporary password for docker login, you will need to get the temporary password frequently and then update it with docker login, which is also a hassle.

Fortunately, Docker provides a mechanism called Credential helper, through which Credential helper can be plugged in in a way that The Credential helper extends the way docker can get access credentials, and is no longer limited to configuring access credentials via docker login.

The docker-credential-acr-helper developed for ACR is a project to help docker get access credentials to ACR image repositories project.

Introduction

As mentioned earlier, docker-credential-acr-helper is a project developed specifically for ACR to help docker get access credentials to ACR image repositories.

docker-credential-acr-helper solves the aforementioned problems.

  • Based on Aliyun's existing authentication system, you can directly use the user's familiar Aliyun access credentials, no need to record and maintain additional docker-specific username and password.
  • Automatically obtain temporary passwords for docker operations, not relying on fixed passwords, and no need to manually refresh temporary passwords frequently.
  • Users can configure AliCloud RAM access control policies to achieve the need for granular permission control for temporary passwords, as described in the ACR documentation.

Usage

You can experience the features provided by this project by following these steps.

  1. Go to the github releases page and download the latest version of the compiled binary archive

  2. Use the checksums.txt file on the page to verify the archive, and extract the archive to get the corresponding binaries docker-credential-acr-helper.

  3. chmod +x docker-credential-acr-helper

  4. cp docker-credential-acr-helper /usr/local/bin

  5. Configure alibaba cloud access credentials, for example, use the configuration file to specify the access credentials:

    $ cat ~/.alibabacloud/credentials
[default] # Default client
type = access_key # The authentication method is access_key
access_key_id = foo # Key
access_key_secret = bar # Secret

6. Exit the ACR registry domain you want to test with docker logout <acr_registry_domain> and clean up the corresponding saved docker credentials. Confirm that you do not have access to the corresponding ACR private image by docker pull <acr_image>. 8. Modify the credHelpers configuration item in the docker configuration file ~/.docker/config.json to specify to use docker-credential-acr-helper to get access credentials when accessing an ACR registry domain (See the Official Docker Documentation or the project README for more details on this configuration) . Example configuration:

{
  "credHelpers" : {
    "registry.cn-beijing.aliyuncs.com" : "acr-helper"
  }
}
  1. Verify that the configuration is complete with docker pull <acr_image> and you can access the corresponding ACR private image again.

Integrated into third-party projects as a golang package

It is also possible to use this project as a golang package, integrating the project's capabilities into third-party projects.

For example, when using github.com/google/go-containerregistry/pkg/crane to operate the docker registry, you can integrate docker-credential-acr-helper in your project using the following method:

import (
    "github.com/google/go-containerregistry/pkg/authn"
    "github.com/google/go-containerregistry/pkg/crane"
    "github.com/mozillazg/docker-credential-acr-helper/pkg/credhelper"
)

func main() {
    kc := authn.NewMultiKeychain(
            authn.DefaultKeychain,
            authn.NewKeychainFromHelper(credhelper.NewACRHelper()),  // <- here
    )
    ref := os.Getenv("REPO_URL")
    digest, err := crane.Digest(ref, crane.WithAuthFromKeychain(kc))
    if err != nil {
            panic(err)
    }
    fmt.Printf("got digest for %q:\n%s\n", ref, digest)
}

The full sample code is here： examples/go-containerregistry-auth

FAQ

Whether to support ACR Enterprise Edition?

Yes.

How to implement different Alibaba Cloud access credentials for different ACR domains?

this can be achieved by writing separate shell scripts for different access credentials.

For example:

$ cat /usr/local/bin/docker-credential-acr-helper-user-1
#!/usr/bin/env bash

# export ALIBABA_CLOUD_ACCESS_KEY_ID=foo
# export ALIBABA_CLOUD_ACCESS_KEY_SECRET=bar
export ALIBABA_CLOUD_CREDENTIALS_FILE=/path/to/user-1-credentials

exec /usr/local/bin/docker-credential-acr-helper "$@"

$ chmod +x /usr/local/bin/docker-credential-acr-helper-user-1

Then configure ~/.docker/config.json to implement different ACR domains using shell scripts configured with different access credentials:

{
  "credHelpers" : {
    "registry.cn-beijing.aliyuncs.com" : "acr-helper",
    "registry.cn-hangzhou.aliyuncs.com" : "acr-helper-user-1",
    "registry.cn-shenzhen.aliyuncs.com" : "acr-helper-user-2"
  }
}

Comments