The Amazon ECR Docker Credential Helper is a credential helper for the Docker daemon that makes it easier to use Amazon Elastic Container Registry.
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.
You can install the Amazon ECR Credential Helper from the Amazon Linux 2023 repositories.
$ sudo dnf install -y amazon-ecr-credential-helperOnce you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.
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-helperOnce you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.
A community-maintained Homebrew formula is available in the core tap.
$ brew install docker-credential-helper-ecrOn macOS, another community-maintained installation method is to use MacPorts.
$ sudo port install docker-credential-helper-ecrOnce you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.
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-helperOnce you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.
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-helperOnce you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.
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 -siOnce you have installed the credential helper, see the Configuration section for instructions on how to configure Docker to work with the helper.
A community-maintained package is available in the Alpine Linux aports Repository.
$ apk add docker-credential-ecr-loginNote
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 executables are available via GitHub releases.
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.
There is no need to use docker login or docker logout.
Place the docker-credential-ecr-login binary on your PATH and set the
contents of your ~/.docker/config.json file to be:
{
"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]
}
}
}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_IDandAWS_SECRET_ACCESS_KEYenvironment 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_arnandsource_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.
| Environment Variable | Sample Value | Description |
|---|---|---|
| AWS_ECR_DISABLE_CACHE | true | Disables the local file auth cache if set to a non-empty value |
| AWS_ECR_CACHE_DIR | ~/.ecr | Specifies the local file auth cache directory location |
| AWS_ECR_IGNORE_CREDS_STORAGE | true | Ignore calls to docker login or logout and pretend they succeeded |
docker pull 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repository:my-tag
docker push 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repository:my-tag
docker pull public.ecr.aws/amazonlinux/amazonlinux:latest
If you have configured additional profiles for use with the AWS CLI, you can use
those profiles by specifying the AWS_PROFILE environment variable when invoking docker.
For example:
AWS_PROFILE=myprofile docker pull 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repository:my-tag
There is no need to use docker login or docker logout.
If you have previously authenticated with an ECR repository by using the docker login command manually
then Docker may have stored an auth token which has since expired.
Docker will continue to attempt to use that cached auth token
instead of utilizing the credential helper. You must explicitly remove the previously cached expired
token using docker logout 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repository. After that
Docker will start utilizing the ECR credential helper to fetch fresh credentials, and you will no longer
need to use docker login or docker logout.
Logs from the Amazon ECR Docker Credential Helper are stored in ~/.ecr/log.
For more information about Amazon ECR, see the the Amazon Elastic Container Registry User Guide.
Features marked as experimental are optionally made available to users to test and provide feedback.
If you test any experimental feaures, you can give feedback via the feature's tracking issue regarding:
- Your experience with the feature
- Issues or problems
- Suggested improvements
Experimental features are incomplete in design and implementation. Backwards incompatible changes may be introduced at any time or support dropped entirely. Therefore experimental features are not recommended for use in production environments.
If you think you’ve found a potential security issue, please do not post it in the Issues. Instead, please follow the instructions here or email AWS security directly.
The Amazon ECR Docker Credential Helper is licensed under the Apache 2.0 License.
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}
