CloudBuilder中动态标签Docker镜像无法被后续步骤调用的问题咨询

问题场景 #

在CloudBuilder中构建带动态生成标签的Docker镜像，需要在后续构建流程中直接运行该镜像，但当前配置无法生效，使用的构建配置如下：

steps:
- id: "Store value for docker image tag"
  name: ubuntu
  entrypoint: bash
  args:
   - -c
   - date +%Y%m%d%H%M%S > /workspace/image_tag.txt
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: bash
  args: [ '-c', 'docker build -t gcr.io/blah/my_image:$(cat /workspace/image_tag.txt) -f src/Dockerfile ./src' ]
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: bash
  args: [ '-c', 'docker push gcr.io/blah/my_image:$(cat /workspace/image_tag.txt)' ]
...

- name: 'gcr.io/blah/my_image:$(cat /workspace/image_tag.txt)'
  entrypoint: /bin/sh
  args:
  - -c
#  - execute some commands and script within the image...

注：gcr.io/blah/my_image为自定义构建器。

直接在构建步骤的name字段填写gcr.io/blah/my_image:$(cat /workspace/image_tag.txt)的写法无效，构建时抛出如下错误：

构建运行失败：generic::invalid_argument: invalid build: invalid build step name "gcr.io/blah/my_image:$(cat /workspace/image_tag.txt)": could not parse reference: gcr.io/blah/my_image:$(cat /workspace/image_tag.txt)

目前镜像可正常推送至镜像仓库，需要新增构建步骤运行此前推送的该动态标签镜像。

问题根因 #

该写法确实存在逻辑错误：Cloud Build 构建步骤的name字段由Cloud Build服务端在所有步骤执行前统一解析，不会触发Shell命令替换逻辑。
你在docker build、docker push步骤里用$(cat /workspace/image_tag.txt)能生效，是因为这两个步骤显式指定了entrypoint: bash，命令替换是在Bash进程运行时解析的；但name字段是Cloud Build用来提前拉取步骤运行所需镜像的字段，不会经过Shell解释，$(cat ...)会被直接当成镜像标签的一部分，不符合OCI镜像引用格式，因此抛出解析错误。

可行解决方案 #

方案1：双标签推送（最简单，适配单串行流水线场景） #

构建镜像时同时打两个标签：一个动态时间戳标签用于版本留存，另一个固定别名标签（如ci-build、temp-run）供后续步骤直接引用，示例配置：

steps:
- id: "Store value for docker image tag"
  name: ubuntu
  entrypoint: bash
  args:
   - -c
   - date +%Y%m%d%H%M%S > /workspace/image_tag.txt
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: bash
  # 同时打动态标签和固定别名标签
  args: [ '-c', 'docker build -t gcr.io/blah/my_image:$(cat /workspace/image_tag.txt) -t gcr.io/blah/my_image:ci-temp -f src/Dockerfile ./src' ]
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: bash
  # 两个标签都推送到仓库
  args: [ '-c', 'docker push gcr.io/blah/my_image:$(cat /workspace/image_tag.txt) && docker push gcr.io/blah/my_image:ci-temp' ]

# 后续步骤直接用固定标签引用，无需动态解析
- name: 'gcr.io/blah/my_image:ci-temp'
  entrypoint: /bin/sh
  args:
  - -c
  - # 执行镜像内的命令和脚本

注意：多并发构建场景下固定标签可能被其他构建覆盖，仅推荐单流水线串行构建使用。

方案2：通过docker run显式运行动态标签镜像（兼容并发场景） #

不需要在name字段直接引用自定义镜像，复用官方docker构建器，通过docker run命令拉取并运行对应动态标签的镜像，命令参数在Bash内执行时可正常解析命令替换，示例配置：

steps:
# 前面生成标签、构建、推送镜像的步骤保持原有逻辑不变
- id: "Store value for docker image tag"
  name: ubuntu
  entrypoint: bash
  args:
   - -c
   - date +%Y%m%d%H%M%S > /workspace/image_tag.txt
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: bash
  args: [ '-c', 'docker build -t gcr.io/blah/my_image:$(cat /workspace/image_tag.txt) -f src/Dockerfile ./src' ]
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: bash
  args: [ '-c', 'docker push gcr.io/blah/my_image:$(cat /workspace/image_tag.txt)' ]

# 用docker run运行动态标签镜像
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: bash
  args:
  - -c
  - |
    IMG_TAG=$(cat /workspace/image_tag.txt)
    # 加-v参数挂载workspace目录，对齐Cloud Build默认的工作目录挂载行为
    docker run -v /workspace:/workspace gcr.io/blah/my_image:$IMG_TAG /bin/sh -c "
      # 此处填写需要在自定义镜像内执行的命令和脚本
    "

该方案完全保留原有动态标签逻辑，不会出现标签覆盖问题，适合多构建并发的场景。

方案3：使用Cloud Build内置替换变量（无需自定义生成标签） #

如果动态标签仅用于构建版本区分，可直接使用Cloud Build预置的全局替换变量，这类变量在构建启动前就会完成全局替换，可以直接写在name字段中，无需单独生成标签文件，示例：

steps:
# 不需要单独的生成标签步骤，直接用内置变量
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: bash
  args: [ '-c', 'docker build -t gcr.io/blah/my_image:$BUILD_ID -f src/Dockerfile ./src' ]
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: bash
  args: [ '-c', 'docker push gcr.io/blah/my_image:$BUILD_ID' ]

# 内置变量可直接在name字段使用，会被提前替换
- name: 'gcr.io/blah/my_image:$BUILD_ID'
  entrypoint: /bin/sh
  args:
  - -c
  - # 执行镜像内的命令

常用内置替换变量包括$PROJECT_ID（项目ID）、$BUILD_ID（构建唯一ID）、$COMMIT_SHA（代码提交完整哈希）、$SHORT_SHA（代码提交短哈希）、$TAG_NAME（触发构建的Git标签）等，可根据需求选择。

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