awslabs/amazon-ecr-credential-helper
GitHub: awslabs/amazon-ecr-credential-helper
Amazon ECR Docker Credential Helper 让 Docker 在 push/pull 镜像时自动获取 Amazon ECR 的认证凭证，免去了手动执行 docker login 的繁琐步骤。
Stars: 2709 | Forks: 350
# Amazon ECR Docker Credential Helper
[](https://github.com/awslabs/amazon-ecr-credential-helper/actions/workflows/build.yaml)
[](https://goreportcard.com/report/github.com/awslabs/amazon-ecr-credential-helper)
[](https://repology.org/project/amazon-ecr-credential-helper/versions)
Amazon ECR Docker Credential Helper 是一个面向 Docker daemon 的
[credential helper](https://github.com/docker/docker-credential-helpers)
它让使用
[Amazon Elastic Container Registry](https://aws.amazon.com/ecr/) 变得更加容易。
## 目录
* [前置条件](#prerequisites)
* [安装说明](#installing)
+ [Amazon Linux 2023 (AL2023)](#amazon-linux-2023-al2023)
+ [Amazon Linux 2 (AL2)](#amazon-linux-2-al2)
+ [Mac OS](#mac-os)
+ [Debian Buster（及未来版本）](#debian-buster-and-future-versions)
+ [Ubuntu 19.04 Disco Dingo 及更新版本](#ubuntu-1904-disco-dingo-and-newer)
+ [Arch Linux](#arch-linux)
+ [Alpine Linux](#alpine-linux)
+ [Windows](#windows)
+ [通过 mise 软件包管理器安装](#from-mise-software-package-manager)
+ [从源码安装](#from-source)
* [配置](#configuration)
+ [Docker](#docker)
+ [AWS credentials](#aws-credentials)
+ [Amazon ECR Docker Credential Helper](#amazon-ecr-docker-credential-helper-1)
* [用法](#usage)
* [故障排除](#troubleshooting)
* [实验性功能](#experimental-features)
* [安全披露](#security-disclosures)
* [许可证](#license)
## 前置条件
您的系统上必须至少安装了 Docker 1.11。
您还必须具有可用的 AWS credentials。有关如何使用不同的 AWS credentials 的详细信息，请参阅 [AWS credentials 部分](#aws-credentials)。
## 安装说明
### Amazon Linux 2023 (AL2023)
您可以从 Amazon Linux 2023 软件仓库中安装 Amazon ECR Credential Helper。
```
sudo dnf install -y amazon-ecr-credential-helper
```
安装 credential helper 后，请参阅[配置部分](#configuration)以获取有关如何配置 Docker 以便与该 helper 配合使用的说明。
### Amazon Linux 2 (AL2)
您可以从 [`docker` 或 `ecs` extras](https://docs.aws.amazon.com/linux/al2/ug/al2-extras.html) 中安装 Amazon ECR Credential Helper。
```
sudo amazon-linux-extras enable docker
sudo yum install amazon-ecr-credential-helper
```
安装 credential helper 后，请参阅[配置部分](#configuration)以获取有关如何配置 Docker 以便与该 helper 配合使用的说明。
### Mac OS
在核心 tap 中提供了一个由社区维护的 Homebrew formula。
[](https://repology.org/project/amazon-ecr-credential-helper/versions)
```
brew install docker-credential-helper-ecr
```
在 macOS 上，另一种由社区维护的安装方法是使用 MacPorts。
[](https://repology.org/project/amazon-ecr-credential-helper/versions)
```
sudo port install docker-credential-helper-ecr
```
安装 credential helper 后，请参阅[配置部分](#configuration)以获取有关如何配置 Docker 以便与该 helper 配合使用的说明。
### Debian Buster（及未来版本）
您可以从 Debian Buster 归档文件中安装 Amazon ECR Credential Helper。该软件包也将包含在未来的 Debian 版本中。
[](https://repology.org/project/amazon-ecr-credential-helper/versions)
[](https://repology.org/project/amazon-ecr-credential-helper/versions)
[](https://repology.org/project/amazon-ecr-credential-helper/versions)
[](https://repology.org/project/amazon-ecr-credential-helper/versions)
[](https://repology.org/metapackage/amazon-ecr-credential-helper/versions)
```
sudo apt update
sudo apt install amazon-ecr-credential-helper
```
安装 credential helper 后，请参阅[配置部分](#configuration)以获取有关如何配置 Docker 以便与该 helper 配合使用的说明。
### Ubuntu 19.04 Disco Dingo 及更新版本
您可以从 Ubuntu 19.04 Disco Dingo（及更新版本）归档文件中安装 Amazon ECR Credential Helper。
[](https://repology.org/project/amazon-ecr-credential-helper/versions)
[](https://repology.org/project/amazon-ecr-credential-helper/versions)
```
sudo apt update
sudo apt install amazon-ecr-credential-helper
```
安装 credential helper 后，请参阅[配置部分](#configuration)以获取有关如何配置 Docker 以便与该 helper 配合使用的说明。
### Arch Linux
在 Arch User Repository 中提供了一个由社区维护的软件包。
[](https://repology.org/metapackage/amazon-ecr-credential-helper/versions)
```
git clone https://aur.archlinux.org/amazon-ecr-credential-helper.git
cd amazon-ecr-credential-helper
makepkg -si
```
安装 credential helper 后，请参阅[配置部分](#configuration)以获取有关如何配置 Docker 以便与该 helper 配合使用的说明。
### Alpine Linux
在 [Alpine Linux aports Repository](https://pkgs.alpinelinux.org/packages?name=docker-credential-ecr-login) 中提供了一个由社区维护的软件包。
[](https://repology.org/project/amazon-ecr-credential-helper/versions)
```
apk add docker-credential-ecr-login
```
安装 credential helper 后，请参阅[配置部分](#configuration)以获取有关如何配置 Docker 以便与该 helper 配合使用的说明。
### Windows
Windows 可执行文件可通过 [GitHub releases](https://github.com/awslabs/amazon-ecr-credential-helper/releases) 获取。
### 通过 mise 软件包管理器安装
要从 [mise](https://github.com/jdx/mise) 多语言包管理工具安装，您可以直接使用类似以下的命令并指定您想要安装的版本来进行安装：
```
mise use -g amazon-ecr-credential-helper@latest
```
### 从源码安装
为了构建并安装 Amazon ECR Docker Credential Helper，我们建议您的系统上安装有 Go 1.19 或更高版本，以及 `git` 和 `make`。
如果您刚刚安装了 Go，请确保同时将其添加到了您的 PATH 或环境变量（Windows）中。例如：
```
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin
```
或者在 Windows 上：
```
setx GOPATH %USERPROFILE%\go
;%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
```
如果您已经有 Docker 环境，只需在任何地方克隆此 repository 并运行 `make build-in-docker`。此命令会在 Docker 容器内使用 Go 构建二进制文件，并将其输出到本地目录。
通过 `TARGET_GOOS` 环境变量，您还可以对该二进制文件进行交叉编译。
安装 credential helper 后，请参阅[配置部分](#configuration)以获取有关如何配置 Docker 以便与该 helper 配合使用的说明。
## 配置
### Docker
无需使用 `docker login` 或 `docker logout`。
将 `docker-credential-ecr-login` 二进制文件放在您的 `PATH` 路径下。
在 Windows 上，根据可执行文件是在用户上下文还是系统上下文中运行，需要使用相应的 `Path` 用户或系统变量。
随后，需要在 `~/.docker/config.json` 中更新 docker 客户端的配置，以使用 **ecr-login** helper。
根据 docker 客户端执行时所在的操作系统和上下文，此配置可能位于不同的位置。
在 Linux 系统上：
- `/home//.docker/config.json` 用于 **user** 上下文
- `/root/.docker/config.json` 用于 **root** 上下文
在 Windows 上：
- `C:\Users\\.docker\config.json` 用于 **user** 上下文
- `C:\Windows\System32\config\systemprofile\.docker\config.json` 用于 **SYSTEM** 上下文
将文件内容设置如下：
```
{
"credsStore": "ecr-login"
}
```
这将配置 Docker daemon 对所有 Amazon ECR registries 使用该 credential helper。
对于 Docker 1.13.0 或更高版本，您可以配置 Docker 对不同的 ECR registries 使用不同的 credential helper。要为特定的 ECR registry 使用此 credential helper，请创建一个包含您的 ECR registry URI 的 `credHelpers` 部分：
```
{
"credHelpers": {
"public.ecr.aws": "ecr-login",
".dkr.ecr..amazonaws.com": "ecr-login"
}
}
```
如果您使用 `docker` 操作使用不同身份验证凭据的 registries，这将非常有用。
如果您需要向多个 registry 进行身份验证，包括非 ECR registries，您可以将 credHelpers 与 auths 结合使用。例如：
```
{
"credHelpers": {
".dkr.ecr..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
Amazon ECR Docker Credential Helper 允许您使用存储在不同位置的 AWS credentials。标准位置包括：
* 共享凭据文件 (`~/.aws/credentials`)
* `AWS_ACCESS_KEY_ID` 和 `AWS_SECRET_ACCESS_KEY` 环境变量
* [Amazon ECS 任务的 IAM 角色](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)
* [Amazon EC2 的 IAM 角色](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html)
要使用与共享凭据文件 (`~/.aws/credentials`) 中不同的命名 profile 相关联的凭据，您可以设置 `AWS_PROFILE` 环境变量。
Amazon ECR Docker Credential Helper 会读取并支持 AWS 共享配置文件 (`~/.aws/config`) 中指定的一些配置选项。要禁用这些选项，您必须将 `AWS_SDK_LOAD_CONFIG` 环境变量设置为 `false`。支持的选项包括：
* 使用 `role_arn` 和 `source_profile` 指定的代入角色
* 使用 `credential_process` 指定的外部凭据进程
* Web Identities，例如 [Kubernetes 中用于 Service Accounts 的 IAM 角色](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html)（*注意：Kubernetes 用户如果在容器中使用非 root 用户，可能会遇到[此 bug](https://github.com/kubernetes-sigs/external-dns/pull/1185) 中描述的权限问题，可能需要采取变通方法来调整 Kubernetes `securityContext`。*）
Amazon ECR Docker Credential Helper 使用与 AWS CLI 和 AWS SDKs 相同的凭据。有关配置 AWS credentials 的更多信息，请参阅 *AWS Command Line Interface User Guide* 中的 [Configuration and Credential Files](http://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)。
这些凭据必须应用了[允许访问 Amazon ECR](https://docs.aws.amazon.com/AmazonECR/latest/userguide/security-iam-awsmanpol.html) 的策略。
### Amazon ECR Docker Credential Helper
| 环境变量 | 示例值 | 描述 |
| ---------------------------- | ------------- | ------------------------------------------------------------------ |
| AWS_ECR_DISABLE_CACHE | true | 如果设置为非空值，则禁用本地文件身份验证缓存。禁用后，credential helper 将不会在本地文件系统存储或读取缓存的 ECR 授权 token，这要求每次 Docker 操作都必须从 AWS 获取新凭据。这在不希望将凭据持久化到磁盘的环境中可能很有用，尽管这会导致对 ECR 产生额外的 API 调用。 |
| AWS_ECR_CACHE_DIR | ~/.ecr | 指定本地文件身份验证缓存的目录位置 |
| AWS_ECR_IGNORE_CREDS_STORAGE | true | 忽略对 docker login 或 logout 的调用并假装它们成功 |
## 用法
`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 的其他 profile，您可以在调用 `docker` 时通过指定 `AWS_PROFILE` 环境变量来使用这些 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 repository 进行了身份验证，那么 Docker 可能存储了现已过期的 auth token。
Docker 将继续尝试使用该缓存的 auth token，而不是使用 credential helper。您必须使用 `docker logout 123456789012.dkr.ecr.us-west-2.amazonaws.com/my-repository` 显式删除之前缓存的过期 token。在此之后，Docker 将开始利用 ECR credential helper 来获取新的凭据，您将不再需要使用 `docker login` 或 `docker logout`。
Amazon ECR Docker Credential Helper 的日志存储在 `~/.ecr/log` 中。
有关 Amazon ECR 的更多信息，请参阅 [Amazon Elastic Container Registry User Guide](http://docs.aws.amazon.com/AmazonECR/latest/userguide/what-is-ecr.html)。
## 实验性功能
标记为实验性的功能可选择性地提供给用户进行测试并提供反馈。
如果您测试了实验性功能，您可以通过该功能的跟踪 issue 提供有关以下方面的反馈：
* 您对该功能的体验
* 问题或困难
* 建议的改进
实验性功能在设计和实现上是不完整的。可能随时引入向后不兼容的更改或完全停止支持。因此，**不建议**在生产环境中使用实验性功能。
## 安全披露
如果您认为自己发现了潜在的安全问题，请不要将其发布在 Issues 中。相反，请遵循[此处](https://aws.amazon.com/security/vulnerability-reporting/)的说明或[直接发送电子邮件至 AWS 安全部门](mailto:aws-security@amazon.com)。
## 许可证
Amazon ECR Docker Credential Helper 采用 Apache 2.0 许可证授权。
标签：AWS, Docker, DPI, EVTX分析, SOC Prime, 安全防御评估, 开发工具, 日志审计, 请求拦截