GitLab Runner配置Docker Hub认证解决拉取限速及AWS参数存储引用

问题现象 #

拉取Docker镜像时触发速率限制，报错如下：

Running with gitlab-runner 14.0.1 (c1xsefsq)
   on gitlab-runners-xxxxxx   vjqSst4o
Preparing the "docker+machine" executor 01:42
 Using Docker executor with image node:14 ...
 Pulling docker image node:14 ...
 WARNING: Failed to pull image with policy "always": toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit (manager.go:205:0s)
 ERROR: Preparation failed: failed to pull image "node:14" with specified policies [always]:
toomanyrequests: You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit (manager.go:205:0s)

已尝试的配置 #

为通过Docker Hub付费账号认证解决速率限制，已尝试修改GitLab Runner的config.toml文件，添加DOCKER_AUTH_CONFIG环境变量：

[[runners]]
  environment = ["DOCKER_AUTH_CONFIG={\"auths\":{\"registry.example.com:5000\":{\"auth\":\"<NEW ACCESS TOKEN HERE FROM MY DOCKERHUB ACCOUNT>=\"}}}"]

同时在Terragrunt配置中设置了相关环境变量：

runners_environment_vars      = ["DOCKER_AUTH_CONFIG={"auths":{"https://index.docker.io/v1/":{"auth":"MY TOKEN"}}}"

需求 #

需实现：在Terragrunt代码中从AWS参数存储引用Docker Hub访问令牌，完成GitLab Runner的Docker Hub认证配置，彻底解决镜像拉取速率限制问题。

解决方案 #

1. 存储Docker Hub认证令牌到AWS参数存储 #

• 生成Docker Hub的auth值：将DockerHub用户名:访问令牌进行Base64编码（可通过echo -n "用户名:令牌" | base64命令生成）
• 在AWS Systems Manager参数存储中创建安全字符串类型的参数，路径建议设为/gitlab-runner/dockerhub-auth-token，值为上述Base64编码后的字符串

2. 在Terragrunt中引用SSM参数并配置GitLab Runner #

在Terragrunt配置文件（如terragrunt.hcl）中添加以下内容：

步骤1：添加SSM参数数据源

data "aws_ssm_parameter" "dockerhub_auth_token" {
  name           = "/gitlab-runner/dockerhub-auth-token"
  with_decryption = true # 安全字符串类型参数需开启解密
}

步骤2：构造DOCKER_AUTH_CONFIG环境变量

在GitLab Runner的环境变量配置中，注入动态获取的令牌：

runners_environment_vars = [
  "DOCKER_AUTH_CONFIG={\"auths\":{\"https://index.docker.io/v1/\":{\"auth\":\"${data.aws_ssm_parameter.dockerhub_auth_token.value}\"}}}"
]

3. 配置IAM权限 #

确保GitLab Runner所在的IAM角色拥有访问该SSM参数的权限，添加以下IAM策略：

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "ssm:GetParameter",
      "Resource": "arn:aws:ssm:你的AWS区域:你的AWS账号ID:parameter/gitlab-runner/dockerhub-auth-token"
    }
  ]
}

内容的提问来源于stack exchange，提问作者Maruthirao Konda