AWS ECR Token 自动刷新

1. 问题

AWS ECR 认证 Token 有效期 12 小时，过期后需要重新执行 docker login 或 aws ecr get-login-password。

2. 解决方案

使用 ECR Credential Helper，Docker 拉取镜像时自动调用 AWS API 获取最新 Token。

适用场景：开发机、CI/CD、服务器等任何有 Docker 的环境。

3. IAM 策略配置

3.1 限制特定仓库的策略

AWS 托管策略 AmazonEC2ContainerRegistryReadOnly 授权所有仓库（*）。要限制只能拉取特定仓库，需创建自定义策略。

策略说明：

• ecr:GetAuthorizationToken 的 Resource 必须为 *（Token 是针对整个 Registry 的，不支持单仓库 Token。）
• 其他操作的 Resource 可限制为具体仓库 ARN

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AllowLogin",
            "Effect": "Allow",
            "Action": [
                "ecr:GetAuthorizationToken"
            ],
            "Resource": "*"
        },
        {
            "Sid": "AllowPullSpecificRepo",
            "Effect": "Allow",
            "Action": [
                "ecr:BatchCheckLayerAvailability",
                "ecr:GetDownloadUrlForLayer",
                "ecr:BatchGetImage",
                "ecr:DescribeRepositories",
                "ecr:ListImages",
                "ecr:DescribeImages"
            ],
            "Resource": [
                "arn:aws:ecr:REGION:ACCOUNT_ID:repository/NAMESPACE/*"
            ]
        }
    ]
}

说明：上述策略允许拉取 NAMESPACE/* 下的所有镜像。

4. 配置 Credential Helper

4.1 安装

根据操作系统，参考 GitHub 官方安装指南 进行安装。

4.2 配置 Docker

编辑或创建 ~/.docker/config.json：

{
    "credsStore": "ecr-login"
}

或者仅针对 ECR 使用 Credential Helper（推荐）：

{
    "credHelpers": {
        "ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com": "ecr-login"
    }
}

说明：

• credsStore：全局使用该 Credential Helper
• credHelpers：仅对特定 Registry 使用（推荐，不影响其他镜像源）

4.3 配置 AWS 凭证

# 方式一：通过 AWS CLI 配置
aws configure

# 方式二：使用环境变量
export AWS_ACCESS_KEY_ID=YOUR_ACCESS_KEY
export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
export AWS_DEFAULT_REGION=REGION

5. 验证

5.1 测试 Credential Helper

# 测试 Credential Helper 是否工作
echo "ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com" | docker-credential-ecr-login get

成功会返回类似：

{
    "ServerURL": "ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com",
    "Username": "AWS",
    "Secret": "eyJwYXlsb2FkIjoiQ..."
}

5.2 拉取镜像

docker pull ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com/NAMESPACE/REPO-NAME:latest

配置正确后，拉取镜像无需手动 docker login。

6. 常见问题

错误：no basic auth credentials

• 检查 ~/.docker/config.json 配置
• 运行 aws ecr get-login-password --region REGION 验证 AWS 凭证
• 检查 IAM 策略是否包含 ecr:GetAuthorizationToken

错误：denied: User is not authorized

• 检查 IAM 策略是否包含 ecr:BatchGetImage 等权限
• 确认仓库 ARN 是否正确

仍需手动登录

• 确认 ~/.docker/config.json 配置正确
• 重启 Docker