Amazon ECR Docker 凭证助手

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

目录

• 先决条件
• 安装
  • Amazon Linux 2023 (AL2023)
  • Amazon Linux 2 (AL2)
  • Mac OS
  • Debian Buster（及未来版本）
  • Ubuntu 19.04 Disco Dingo 及更新版本
  • Arch Linux
  • Alpine Linux
  • 从源码安装
• 配置
  • Docker
  • AWS 凭证
  • Amazon ECR Docker 凭证助手
• 使用
• 故障排除
• 安全披露
• 许可证

先决条件

您的系统必须安装至少 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凭证助手

使用方法

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用户指南。

实验性功能

标记为实验性的功能可选择提供给用户进行测试和提供反馈。

如果您测试任何实验性功能，可以通过功能的跟踪问题提供反馈，包括：

• 您使用该功能的体验
• 问题或困难
• 改进建议

实验性功能在设计和实现上尚不完整。可能随时引入向后不兼容的更改或完全停止支持。因此，不建议在生产环境中使用实验性功能。

安全披露

如果您认为发现了潜在的安全问题，请不要在Issues中发布。相反，请按照此处的说明操作或直接发送电子邮件至AWS安全团队。

许可证

Amazon ECR Docker凭证助手根据Apache 2.0许可证授权。