Amazon ECR Docker 凭证助手

Amazon ECR 标志

Amazon ECR Docker 凭证助手是 Docker 守护程序的凭证助手，它使得使用Amazon Elastic Container Registry变得更加容易。

先决条件

您的系统必须安装至少 Docker 1.11 版本。

您还必须有可用的 AWS 凭证。有关如何使用不同的 AWS 凭证的详细信息，请参阅 AWS 凭证部分。

安装

Amazon Linux 2023 (AL2023)

您可以从 Amazon Linux 2023 存储库安装 Amazon ECR 凭证助手。

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

安装凭证助手后，请参阅配置部分以了解如何配置 Docker 以使用该助手的说明。

Amazon Linux 2 (AL2)

您可以从 docker 或 ecs extras 安装 Amazon ECR 凭证助手。

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

安装凭证助手后，请参阅配置部分以了解如何配置 Docker 以使用该助手的说明。

Mac OS

核心 tap 中提供了一个社区维护的 Homebrew 公式。

$ brew install docker-credential-helper-ecr

在 macOS 上，另一个社区维护的安装方法是使用 MacPorts。

$ sudo port install docker-credential-helper-ecr

安装凭证助手后，请参阅配置部分以了解如何配置 Docker 以使用该助手的说明。

Debian Buster（及未来版本）

您可以从 Debian Buster 存档安装 Amazon ECR 凭证助手。此包也将包含在未来的 Debian 版本中。

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

安装凭证助手后，请参阅配置部分以了解如何配置 Docker 以使用该助手的说明。

Ubuntu 19.04 Disco Dingo 及更新版本

您可以从 Ubuntu 19.04 Disco Dingo（及更新版本）存档安装 Amazon ECR 凭证助手。

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

安装凭证助手后，请参阅配置部分以了解如何配置 Docker 以使用该助手的说明。

Arch Linux

Arch 用户仓库中提供了一个社区维护的包。

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

安装凭证助手后，请参阅配置部分以了解如何配置 Docker 以使用该助手的说明。

Alpine Linux

Alpine Linux aports 仓库中提供了一个社区维护的包。

$ apk add docker-credential-ecr-login

[!注意] 徽章仅显示 edge 版本，请查看仓库以获取稳定版本或添加 --repository=http://dl-cdn.alpinelinux.org/alpine/edge/community

安装凭证助手后，请参阅配置部分以了解如何配置 Docker 以使用该助手的说明。

Windows

Windows 可执行文件可通过 GitHub 发布获取。

[!注意] Windows ARM 支持被视为实验性功能。

请参阅 https://github.com/awslabs/amazon-ecr-credential-helper/issues/795

从源代码构建

要构建和安装Amazon ECR Docker凭证助手，我们建议您的系统安装Go 1.19或更高版本、git和make。

如果您刚刚安装了Go，请确保将其添加到PATH或环境变量(Windows)中。例如：

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

或在Windows中：

setx GOPATH %USERPROFILE%\go
<您现有的PATH定义>;%USERPROFILE%\go\bin

如果您没有定义PATH，下面的命令将会静默失败，运行docker-credential-ecr-login将输出：command not found

您可以通过go命令行工具安装它。

运行以下命令安装：

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

[!警告] 免责声明：此存储库中的Dockerfile用于在GitHub Actions CI中测试Amazon ECR凭证助手二进制文件的交叉编译，并作为开发人员从源代码本地构建的实用工具。它是一个参考实现，不适用于构建和运行生产容器的安全强化。

如果您已经有Docker环境，只需在任何地方克隆此存储库并运行make build-in-docker。此命令使用Docker容器内的Go构建二进制文件，并将其输出到本地目录。

通过设置TARGET_GOOS环境变量，您还可以交叉编译二进制文件。

安装凭证助手后，请参阅配置部分，了解如何配置Docker以使用该助手的说明。

配置

Docker

无需使用docker login或docker logout。

将docker-credential-ecr-login二进制文件放在您的PATH上，并将~/.docker/config.json文件的内容设置为：

{
	"credsStore": "ecr-login"
}

这将配置Docker守护程序为所有Amazon ECR注册表使用凭证助手。

Amazon ECR Docker凭证助手可以与您现有的docker登录认证令牌一起使用：

{
	"credsStore": "ecr-login",
	"auths": {
		"https://index.docker.io/v1/": {
			"auth": [docker.io-auth-token]
		},
		"registry.gitlab.com": {
			"auth": [gitlab-auth-token]
		},
	}
}

使用Docker 1.13.0或更高版本，您可以为不同的ECR注册表配置不同的凭证助手。要为特定的ECR注册表使用此凭证助手，请创建一个credHelpers部分，包含ECR注册表的URI：

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

如果您使用docker操作使用不同身份验证凭证的注册表，这将非常有用。

AWS凭证

Amazon ECR Docker凭证助手允许您使用存储在不同位置的AWS凭证。标准位置包括：

共享凭证文件（~/.aws/credentials）
AWS_ACCESS_KEY_ID和AWS_SECRET_ACCESS_KEY环境变量
Amazon ECS任务的IAM角色
Amazon EC2的IAM角色

要使用共享凭证文件（~/.aws/credentials）中与不同命名配置文件相关联的凭证，您可以设置AWS_PROFILE环境变量。

Amazon ECR Docker凭证助手读取并支持AWS共享配置文件（~/.aws/config）中指定的一些配置选项。要禁用这些选项，您必须将AWS_SDK_LOAD_CONFIG环境变量设置为false。支持的选项包括：

使用role_arn和source_profile指定的假定角色
使用credential_process指定的外部凭证进程
Web身份，如Kubernetes中的IAM角色服务账户（注：使用非root用户容器的Kubernetes用户可能会遇到此bug中描述的权限问题，可能需要通过调整Kubernetes securityContext来采取解决方案。）

Amazon ECR Docker凭证助手使用与AWS CLI和AWS SDK相同的凭证。有关配置AWS凭证的更多信息，请参阅AWS Command Line Interface用户指南中的配置和凭证文件。

凭证必须应用允许访问Amazon ECR的策略。

Amazon ECR Docker凭证助手

环境变量	示例值	描述
AWS_ECR_DISABLE_CACHE	true	如果设置为非空值，则禁用本地文件身份验证缓存
AWS_ECR_CACHE_DIR	~/.ecr	指定本地文件身份验证缓存目录位置
AWS_ECR_IGNORE_CREDS_STORAGE	true	忽略对docker登录或注销的调用，并假装它们成功

使用方法

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

如果您已为AWS CLI配置了其他配置文件，可以在调用docker时通过指定AWS_PROFILE环境变量来使用这些配置文件。例如：

AWS_PROFILE=myprofile docker pull 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repository:my-tag

无需使用docker login或docker logout。

故障排除

如果您之前通过手动使用docker login命令对ECR存储库进行过身份验证，那么Docker可能已经存储了一个已过期的身份验证令牌。 Docker将继续尝试使用该缓存的身份验证令牌，而不是利用凭证助手。您必须使用docker logout 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repository显式删除先前缓存的过期令牌。之后， Docker将开始利用ECR凭证助手获取新的凭证，您将不再需要使用docker login或docker logout。

Amazon ECR Docker凭证助手的日志存储在~/.ecr/log中。

有关Amazon ECR的更多信息，请参阅Amazon Elastic Container Registry用户指南。