如何修复AWS CodeBuild中Docker镜像构建的无效标签格式问题？

问题场景 #

在AWS CodeBuild执行CI/CD流程时，Docker镜像构建命令报错，提示invalid tag "***/***/simple-python-flask-app:latest": invalid reference format，对应的buildspec.yml配置如下：

version: 0.2

env:
  parameter-store:
    DOCKER_REGISTRY_USERNAME: /my-app/docker-credentials/username
    DOCKER_REGISTRY_PASSWORD: /my-app/docker-credentials/password
    DOCKER_REGISTRY_URL: /my-app/docker-registry/url
phases:
  install:
    runtime-versions:
      python: 3.11
  pre_build:
    commands:
      - pip install -r day-14/simple-python-app/requirements.txt
  build:
    commands:
      - cd day-14/simple-python-app
      - echo "Building Docker Image"
      - docker build -t "$DOCKER_REGISTRY_URL/$DOCKER_REGISTRY_USERNAME/simple-python-flask-app:latest" .
      - docker push "$DOCKER_REGISTRY_URL/$DOCKER_REGISTRY_USERNAME/simple-python-flask-app:latest"
  post_build:
    commands:
      - echo "build is successfull"

构建日志关键错误片段：

[容器] 2023/12/30 19:08:13.546309 执行命令docker build -t "$DOCKER_REGISTRY_URL/$DOCKER_REGISTRY_USERNAME/simple-python-flask-app:latest" .
ERROR: invalid tag "***/***/simple-python-flask-app:latest": invalid reference format
[容器] 2023/12/30 19:08:13.735324 命令执行失败：docker build -t "$DOCKER_REGISTRY_URL/$DOCKER_REGISTRY_USERNAME/simple-python-flask-app:latest" . 退出状态码1

修复方案 #

1. 验证SSM参数存储的变量值 #

• 登录AWS控制台进入Systems Manager参数存储页面，检查/my-app/docker-registry/url和/my-app/docker-credentials/username的取值：
  • 镜像仓库URL需符合规范，比如ECR格式为{账户ID}.dkr.ecr.{区域}.amazonaws.com，Docker Hub则为docker.io；
  • 用户名需为仓库合法账号，无多余空格、换行等无效字符。

2. 确认CodeBuild服务角色权限 #

• 确保CodeBuild使用的IAM角色拥有ssm:GetParameter权限，可添加以下策略：

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "ssm:GetParameter",
            "Resource": [
                "arn:aws:ssm:{你的区域}:{你的账户ID}:parameter/my-app/docker-credentials/username",
                "arn:aws:ssm:{你的区域}:{你的账户ID}:parameter/my-app/docker-registry/url"
            ]
        }
    ]
}

3. 在buildspec.yml中添加变量校验 #

在pre_build阶段增加检查，提前发现空变量问题：

pre_build:
  commands:
    - pip install -r day-14/simple-python-app/requirements.txt
    - |
      if [ -z "$DOCKER_REGISTRY_URL" ] || [ -z "$DOCKER_REGISTRY_USERNAME" ]; then
          echo "错误：DOCKER_REGISTRY_URL或DOCKER_REGISTRY_USERNAME变量为空"
          exit 1
      fi

4. 规范Docker标签格式 #

• 镜像标签仅允许小写字母、数字、连字符(-)、下划线(_)、点(.)和斜杠(/)，不能以斜杠开头或结尾；
• 使用ECR时，URL无需添加http://或https://前缀，直接使用完整ECR域名即可。

内容的提问来源于stack exchange，提问作者Расим Гусаинов