catonet/k8s-ecr-login-renew

为AWS ECR自动刷新Kubernetes Docker凭证

AWS弹性容器注册表（ECR）提供了经济高效的私有容器镜像 registry，但ECR的Docker凭证每12小时过期。

为解决此问题，本工具可自动刷新Kubernetes中的凭证，以Cron Job形式部署，确保Kubernetes集群始终能从ECR拉取Docker镜像。

Docker镜像

工具支持标准64位Linux和ARM（树莓派）架构，最新镜像如下：

• nabsul/k8s-ecr-login-renew:v1.5
• nabsul/k8s-ecr-login-renew:arm32v7-v1.5

环境变量

工具主要通过环境变量配置，具体如下：

• AWS_ACCESS_KEY_ID（必填）：用于创建Docker凭证的AWS访问密钥。
• AWS_SECRET_ACCESS_KEY（必填）：从AWS获取Docker凭证所需的AWS密钥。
• AWS_REGION（必填）：ECR实例所在的AWS区域。
• DOCKER_SECRET_NAME（必填）：存储Docker凭证的Kubernetes secret名称。
• TARGET_NAMESPACE（可选）：逗号分隔的命名空间列表，将在每个命名空间中创建Docker secret。未设置时默认值为default。
• DOCKER_REGISTRIES（可选）：逗号分隔的registry URL列表。未提供时使用AWS返回的默认URL。
  • 示例：DOCKER_REGISTRIES=https://321321.dkr.ecr.us-west-2.amazonaws.com,https://123123.dkr.ecr.us-east-2.amazonaws.com

使用示例

以下步骤详细说明如何设置Cron Job并进行测试。可直接使用example/service-account.yml和example/deploy.yml文件进行测试，但使用example/pod.yml前需填写registry URL。

创建ECR实例

此处不详细说明，因为已有大量文档介绍。关键步骤：

• 创建AWS ECR实例
• 在实例中创建仓库

推送测试镜像到ECR

为完成后续步骤，需创建并上传镜像到ECR。若需快速测试，示例中包含一个构建nginx服务器的简单Dockerfile：

• 在本地安装AWS CLI工具和Docker
• 登录registry：$(aws2 ecr get-login --no-include-email --region [AWS_REGION])
• 构建镜像：docker build -t [ECR_URL]:latest example/.
• 推送镜像到registry：docker push [ECR_URL]:latest

设置AWS权限

在AWS IAM中创建具有registry只读权限的用户，应授予最小必要权限。理想策略：

• 只读访问权限
• 限制到特定ECR实例

步骤参考：

• 选择"添加用户"，勾选"编程访问"
• 为用户创建组
• 为组创建策略：
  • 服务：Elastic Container Registry
  • 访问级别：List & Read
  • 资源：选择要访问的特定ECR实例

创建后获取访问密钥ID和密钥，用于下一步。

部署AWS访问密钥到Kubernetes

需在Kubernetes中创建包含IAM用户凭证的secret，可通过kubectl命令行创建：

shell
kubectl create secret -n ns-ecr-renew-demo generic ecr-renew-cred-demo \
  --from-literal=REGION=[AWS_REGION] \
  --from-literal=ID=[AWS_KEY_ID] \
  --from-literal=SECRET=[AWS_SECRET]

所需Kubernetes服务账户

需创建具有创建/删除/获取Docker secret权限的服务账户，应授予最小必要权限。示例配置见example/service-account.yml，可直接应用：

shell
kubectl apply -f example/service-account.yml

部署Cron Job

使用example/deploy.yml部署Cron Job：

shell
kubectl apply -f example/deploy.yml

测试Cron Job

最简单的测试方法是从Kubernetes仪表板手动触发Cron Job，这将创建一个Job，可查看日志排查错误。Job完成后，目标Docker secret应被创建或更新。

也可通过命令手动触发Job：

shell
kubectl create job --from=cronjob/ecr-renew-demo ecr-renew-demo-manual-1

查看Job状态和日志：

shell
kubectl describe job ecr-renew-demo-manual-1
kubectl logs job/ecr-renew-demo-manual-1

部署测试镜像

若已推送镜像到ECR，现在可部署该镜像到Pod。编辑example/pod.yml，将[ECR_URI]替换为registry的URI，然后运行：

shell
kubectl apply -f example/pod.yml

检查Pod运行状态：

shell
kubectl exec -it ecr-image-pull-test-demo bash

这将登录到运行中的Pod，可执行ls、cat /usr/share/nginx/html/index.html和exit等命令。也可运行：

shell
kubectl port-forward ecr-image-pull-test-demo 8080:80

然后在浏览器中打开http://localhost:8080，查看nginx默认欢迎页面。

清理演示环境

演示完成后，可删除整个命名空间进行清理：

shell
kubectl delete namespace ns-ecr-renew-demo

在非默认命名空间运行

示例配置在ns-ecr-renew-demo命名空间运行，通过TARGET_NAMESPACE环境变量配置。未提供时默认使用default命名空间。

多命名空间支持

TARGET_NAMESPACE环境变量可指定多个命名空间，使用逗号分隔，支持通配符：?（匹配单个字符）和*（匹配零或多个字符）。有效值示例：

• namespace1
• namespace1,namespace2
• *
• namespace1,prefix-*,*-suffix
• namespace1,namespace?0

注意：若使用通配符，工具必须被授予列出集群所有命名空间的权限。

自动化测试

由于本工具主要是AWS和Kubernetes之间的"粘合"工具，单元测试价值有限。测试设计为在真实Kubernetes集群上运行，会自动检测集群，若使用的命名空间已存在则拒绝运行（避免意外覆盖真实配置）。

注意：仅在本地Windows机器上使用Docker Desktop测试过这些单元测试。

本地运行测试的前提条件：

• 构建工具镜像：docker build -t test-ecr-renew .
• 创建包含所需AWS参数的secret：

shell
kubectl create secret test-ecr-renew-aws-settings \
  --from-literal=REGION=[AWS_REGION] \
  --from-literal=ID=[AWS_KEY_ID] \
  --from-literal=SECRET=[AWS_SECRET] \
  --from-literal=IMAGE=[TEST_IMAGE]

然后运行测试：

shell
go test -v ./test/...

测试限制

目前未测试权限，主要因为Docker Desktop难以强制RBAC权限。