Amazon ECR Docker Credential Helper

The Amazon ECR Docker Credential Helper is a credential helper for the Docker daemon that makes it easier to use Amazon Elastic Container Registry.

Table of Contents

• Prerequisites
• Installing
  • Amazon Linux 2023 (AL2023)
  • Amazon Linux 2 (AL2)
  • Mac OS
  • Debian Buster (and future versions)
  • Ubuntu 19.04 Disco Dingo and newer
  • Arch Linux
  • Alpine Linux
  • Windows
  • From mise software package manager
  • From Source
• Configuration
  • Docker
  • AWS credentials
  • Amazon ECR Docker Credential Helper
• Usage
• Troubleshooting
• Experimental features
• Security disclosures
• License

Prerequisites

You must have at least Docker 1.11 installed on your system.

You also must have AWS credentials available. See the AWS credentials section for details on how to use different AWS credentials.

Installing

Amazon Linux 2023 (AL2023)

You can install the Amazon ECR Credential Helper from the Amazon Linux 2023 repositories.

sudo dnf install -y amazon-ecr-credential-helper

Once you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.

Amazon Linux 2 (AL2)

You can install the Amazon ECR Credential Helper from the docker or ecs extras.

sudo amazon-linux-extras enable docker
sudo yum install amazon-ecr-credential-helper

Once you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.

Mac OS

A community-maintained Homebrew formula is available in the core tap.

brew install docker-credential-helper-ecr

On macOS, another community-maintained installation method is to use MacPorts.

sudo port install docker-credential-helper-ecr

Once you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.

Debian Buster (and future versions)

You can install the Amazon ECR Credential Helper from the Debian Buster archives. This package will also be included in future releases of Debian.

sudo apt update
sudo apt install amazon-ecr-credential-helper

Once you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.

Ubuntu 19.04 Disco Dingo and newer

You can install the Amazon ECR Credential Helper from the Ubuntu 19.04 Disco Dingo (and newer) archives.

sudo apt update
sudo apt install amazon-ecr-credential-helper

Once you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.

Arch Linux

A community-maintained package is available in the Arch User Repository.

git clone https://aur.archlinux.org/amazon-ecr-credential-helper.git
cd amazon-ecr-credential-helper
makepkg -si

Once you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.

Alpine Linux

A community-maintained package is available in the Alpine Linux aports Repository.

apk add docker-credential-ecr-login

[!NOTE] Badge only shows edge, check repository for stable releases or add --repository=http://dl-cdn.alpinelinux.org/alpine/edge/community

Once you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.

Windows

Windows executables are available via GitHub releases.

[!NOTE] Windows ARM support is considered experimental.

See https://github.com/awslabs/amazon-ecr-credential-helper/issues/795

From mise software package manager

To install from mise polyglot package tool manager, you can directly install using a command like this one specifying the version you want to install:

mise use -g amazon-ecr-credential-helper@latest

From Source

To build and install the Amazon ECR Docker Credential Helper, we suggest Go 1.19 or later, git and make installed on your system.

If you just installed Go, make sure you also have added it to your PATH or Environment Vars (Windows). For example:

export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin

Or in Windows:

setx GOPATH %USERPROFILE%\go
<your existing PATH definitions>;%USERPROFILE%\go\bin

If you haven't defined the PATH, the command below will fail silently, and running docker-credential-ecr-login will output: command not found

You can install this via the go command line tool.

To install run:

go install github.com/awslabs/amazon-ecr-credential-helper/ecr-login/cli/docker-credential-ecr-login@latest

[!WARNING] Disclaimer: the Dockerfile in this repository is used to test cross-compilation of the Amazon ECR credential helper binaries in GitHub Actions CI and as a developer utility for building locally from source. It is a reference implementation and not security hardened for building and running production containers.

If you already have Docker environment, just clone this repository anywhere and run make build-in-docker. This command builds the binary with Go inside the Docker container and output it to local directory.

With TARGET_GOOS environment variable, you can also cross compile the binary.

Once you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.

Configuration

Docker

There is no need to use docker login or docker logout.

Place the docker-credential-ecr-login binary on your PATH. On Windows, depending on whether the executable is ran in the User or System context, the corresponding Path user or system variable needs to be used.

Following that the configuration for the docker client needs to be updated in ~/.docker/config.json to use the ecr-login helper. Depending on the operating system and context under which docker client will be executed, this configuration can be found in different places.

On Linux systems: - /home/<username>/.docker/config.json for user context - /root/.docker/config.json for root context

On Windows: - C:\Users\<username>\.docker\config.json for user context - C:\Windows\System32\config\systemprofile\.docker\config.json for the SYSTEM context

Set the contents of the file to the following:

{
    "credsStore": "ecr-login"
}

This configures the Docker daemon to use the credential helper for all Amazon ECR registries.

With Docker 1.13.0 or greater, you can configure Docker to use different credential helpers for different ECR registries. To use this credential helper for a specific ECR registry, create a credHelpers section with the URI of your ECR registry:

{
    "credHelpers": {
        "public.ecr.aws": "ecr-login",
        "<aws_account_id>.dkr.ecr.<region>.amazonaws.com": "ecr-login"
    }
}

This is useful if you use docker to operate on registries that use different authentication credentials.

If you need to authenticate with multiple registries, including non-ECR registries, you can combine credHelpers with auths. For example:

{
  "credHelpers": {
    "<aws_account_id>.dkr.ecr.<region>.amazonaws.com": "ecr-login"
  },
  "auths": {
      "ghcr.io": {
        "auth": [GITHUB_PERSONAL_ACCESS_TOKEN]
      },
      "https://index.docker.io/v1/": {
        "auth": [docker.io-auth-token]
      },
      "registry.gitlab.com": {
        "auth": [gitlab-auth-token]
      }
    }
}

AWS credentials

The Amazon ECR Docker Credential Helper allows you to use AWS credentials stored in different locations. Standard ones include:

• The shared credentials file (~/.aws/credentials)
• The AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables
• An IAM role for an Amazon ECS task
• An IAM role for Amazon EC2

To use credentials associated with a different named profile in the shared credentials file (~/.aws/credentials), you may set the AWS_PROFILE environment variable.

The Amazon ECR Docker Credential Helper reads and supports some configuration options specified in the AWS shared configuration file (~/.aws/config). To disable these options, you must set the AWS_SDK_LOAD_CONFIG environment variable to false. The supported options include:

• Assumed roles specified with role_arn and source_profile
• External credential processes specified with credential_process
• Web Identities like IAM Roles for Service Accounts in Kubernetes (Note: Kubernetes users using containers with a non-root user may encounter permission issues described in this bug and may need to employ a workaround adjusting the Kubernetes securityContext.)

The Amazon ECR Docker Credential Helper uses the same credentials as the AWS CLI and the AWS SDKs. For more information about configuring AWS credentials, see Configuration and Credential Files in the AWS Command Line Interface User Guide.

The credentials must have a policy applied that allows access to Amazon ECR.

Amazon ECR Docker Credential Helper

Environment Variable	Sample Value	Description
AWS_ECR_DISABLE_CACHE	true	Disables the local file auth cache if set to a non-empty value. When disabled, the credential helper will not store or read cached ECR authorization tokens from the local filesystem, requiring fresh credentials to be fetched from AWS for each Docker operation. This may be useful in environments where persisting credentials to