创建 Pub/Sub 触发器

借助 Cloud Build Pub/Sub 触发器,您可以执行构建来响应通过 Pub/Sub 发布的 Google Cloud 事件。您可以使用 Pub/Sub 事件中的信息对构建进行参数化,并确定是否应执行构建来响应事件。 Pub/Sub 触发器可以配置为侦听任何 Pub/Sub 主题。

本页面介绍了如何创建 Pub/Sub 触发器来构建,以响应 Artifact Registry、Container Registry 和 Cloud Storage 上的事件。

准备工作

  • 启用 Cloud Build API。

    启用 API

  • 确保您的源代码包含代码库中的构建配置文件Dockerfile
  • 如需使用此页面上的 gcloud 命令,请安装 Cloud SDK

创建构建触发器来响应 Artifact Registry 事件

您可以创建一个 Pub/Sub 触发器来响应 Artifact Registry 事件,例如推送、标记或删除映像。本部分介绍如何创建 Pub/Sub 触发器,该触发器会在新标记推送到现有映像时调用构建。如果您不熟悉 Artifact Registry,请参阅工件管理概览

控制台

如需创建一个触发器,用于通过 Google Cloud Console 侦听推送到 Artifact Registry 中现有映像的新标记,请执行以下操作:

  1. 打开触发器页面

    打开“触发器”页面

  2. 从页面顶部选择您的项目,然后点击打开

  3. 点击创建触发器

  4. 输入以下触发器设置:

    • 名称:输入触发器的名称。
    • 说明(可选):输入触发器的说明。
    • 事件:选择 Pub/Sub 消息作为用于调用触发器的事件。
    • 订阅:选择要订阅作为触发器事件的 Pub/Sub 主题。您会在下拉菜单中看到项目中的所有现有主题。

      • Pub/Sub 主题:从下拉菜单中选择 gcr 主题,或按照配置 Pub/Sub 通知中的说明手动创建主题。
    • 来源:选择要在触发器运行时构建的代码库。

    • 修订版本:选择要在触发器运行时构建的分支或标记。

      • 分支:输入调用构建所基于的分支的名称。
      • 标记:输入调用构建所基于的标记的名称。
    • 配置:选择构建配置文件(位于远程代码库),或创建要用于构建的内嵌构建配置文件。

      • 类型:选择要用于构建的配置类型。
        • Cloud Build 配置文件(yaml 或 json):为您的配置使用构建配置文件。
        • Dockerfile:为您的配置使用 Dockerfile
        • Buildpack:为您的配置使用 buildpack
      • 位置:为您的配置指定位置。

        • 代码库:如果您的配置文件位于远程代码库中,请提供构建配置文件的位置、Dockerfile 目录或 buildpack 目录。如果您的构建配置类型是 Dockerfile 或 buildpack,则需要为生成的映像提供名称,还需要视情况提供构建的超时时间。提供了 Dockerfile 或 buildpack 映像名称后,您会看到您的构建将执行的 docker buildpack 命令的预览。
        • Buildpack 环境变量(可选):如果您选择了 buildpacks 作为配置类型,请点击添加软件包环境变量以指定 buildpack 环境变量和值。如需详细了解 buildpack 环境变量,请参阅环境变量
        • 内嵌:如果您选择了 Cloud Build 配置文件(yaml 或 json)作为配置选项,则可以指定内嵌构建配置。点击打开编辑器,使用 YAML 或 JSON 语法在 Google Cloud Console 中编写您的构建配置文件。点击完成以保存您的构建配置。

    • 替代变量(可选):如果您选择了构建配置文件作为构建配置选项,则您可以选择使用此字段来定义特定于触发器的替代变量

      在以下示例中,我们想要通过与 gcr 事件关联的载荷和操作获取映像标记的名称。为此,请使用载荷绑定创建替代变量。

      指定以下变量和值:

      变量名称 变量值
      _IMAGE_TAG $(body.message.data.tag)
      _ACTION $(body.message.data.action)

      body.message 引用发布者发布并由订阅者使用的 PubSubMessage。如需查看 Pub/Sub 通知载荷的更多示例,请参阅通知示例

    • 过滤条件(可选):您可以在触发器中创建过滤条件,以通过对替代变量指定过滤条件确定触发器是否会执行构建来响应传入的载荷。过滤条件表达式求得的值必须为 true,才能执行构建。

      在包含多个消息的主题上设置 Pub/Sub 触发器时,我们建议使用过滤条件。过滤器可用于精确控制为响应传入的 Pub/Sub 消息而执行的构建。如需了解在未设置过滤条件的情况下设置触发器的相关风险,请参阅与未过滤的触发器有关的风险

      在以下示例中,我们希望触发器在新标记推送到现有映像时执行构建。我们使用过滤条件运算符来检查 _IMAGE_TAG 变量是否与现有标记名称匹配,以及 _ACTION 变量是否与 INSERT 匹配,以查找新添加的数据。

      指定以下内容作为过滤条件:

      • _IMAGE_TAG != ""
      • _ACTION == INSERT

      Pub/Sub 触发器中的过滤语法使用通用表达式语言 (CEL) 进行表达式求值。如需详细了解 CEL,请参阅 cel-spec 代码库。如需查看可应用于 Pub/Sub 触发器的更多过滤语法示例,请参阅使用 CEL 过滤构建事件

  1. 点击创建以创建构建触发器
  2. .

gcloud

如需创建一个触发器,用于通过 gcloud 命令监听推送到 Artifact Registry 中现有映像的新标记,请执行以下操作:

  1. 打开一个终端窗口。
  2. 运行 gcloud alpha 命令,在项目中创建一个构建触发器。在以下示例中,触发器配置为根据替代变量 _IMAGE_TAG 定义的指定载荷,响应标记与 prod 匹配且操作与 INSERT 匹配的构建。

     gcloud alpha builds triggers create pubsub \
       --name=TRIGGER_NAME \
       --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
       --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
       --substitutions=\
         _IMAGE_TAG_='$(body.message.data.tag)'
         _ACTION='$(body.message.data.action)'
       --filter='_IMAGE_TAG == "" && _ACTION == "INSERT"'
       --repo=REPO_NAME
       --tag=TAG_NAME  # or --branch=BRANCH_NAME
    

    其中:

    • TRIGGER_NAME 是触发器的名称。
    • PROJECT_ID 是您的 Cloud 项目的 ID。
    • TOPIC_NAME 是您订阅的 Pub/Sub 主题的名称。
    • BUILD_CONFIG 是构建配置文件的路径。
    • INLINE_BUILD_CONFIG 是内嵌构建配置文件的路径。
    • REPO_NAME 是调用构建所基于的源代码库的名称。
    • 如果您想要将触发器设置为基于标记构建,则 TAG_NAME 是您的标记的名称。
    • 如果您想要将触发器设置为基于分支构建,则 BRANCH_NAME 是您的分支的名称。

创建构建触发器来响应 Container Registry 事件

您可以创建 Pub/Sub 触发器来响应 Container Registry 事件,例如推送、标记或删除映像。本部分介绍如何创建 Pub/Sub 触发器,该触发器会在映像与自定义过滤条件设置的标记匹配时调用构建。如果您不熟悉 Container Registry,请参阅 Container Registry 快速入门,了解如何使用标记推送和拉取映像。

控制台

如需使用 Google Cloud Console 创建触发器以侦听 Container Registry 中的映像推送并根据标记名称进行匹配,请执行以下操作:

  1. 打开触发器页面

    打开“触发器”页面

  2. 从页面顶部选择您的项目,然后点击打开

  3. 点击创建触发器

  4. 输入以下触发器设置:

    • 名称:输入触发器的名称。
    • 说明(可选):输入触发器的说明。
    • 事件:选择 Pub/Sub 消息作为用于调用触发器的事件。
    • 订阅:选择要订阅作为触发器事件的 Pub/Sub 主题。您会在下拉菜单中看到项目中的所有现有主题。

      • Pub/Sub 主题:从下拉菜单中选择 gcr 主题,或按照配置 Pub/Sub 通知中的说明手动创建主题。
    • 来源:选择要在触发器运行时构建的代码库。

    • 修订版本:选择要在触发器运行时构建的分支或标记。

      • 分支:输入调用构建所基于的分支的名称。
      • 标记:输入调用构建所基于的标记的名称。
    • 配置:选择构建配置文件(位于远程代码库),或创建要用于构建的内嵌构建配置文件。

      • 类型:选择要用于构建的配置类型。
        • Cloud Build 配置文件(yaml 或 json):为您的配置使用构建配置文件。
        • Dockerfile:为您的配置使用 Dockerfile
        • Buildpack:为您的配置使用 buildpack
      • 位置:为您的配置指定位置。

        • 代码库:如果您的配置文件位于远程代码库中,请提供构建配置文件的位置、Dockerfile 目录或 buildpack 目录。如果您的构建配置类型是 Dockerfile 或 buildpack,则需要为生成的映像提供名称,还需要视情况提供构建的超时时间。提供了 Dockerfile 或 buildpack 映像名称后,您会看到您的构建将执行的 docker buildpack 命令的预览。
        • Buildpack 环境变量(可选):如果您选择了 buildpacks 作为配置类型,请点击添加软件包环境变量以指定 buildpack 环境变量和值。如需详细了解 buildpack 环境变量,请参阅环境变量
        • 内嵌:如果您选择了 Cloud Build 配置文件(yaml 或 json)作为配置选项,则可以指定内嵌构建配置。点击打开编辑器,使用 YAML 或 JSON 语法在 Google Cloud Console 中编写您的构建配置文件。点击完成以保存您的构建配置。

    • 替代变量(可选):如果您选择了构建配置文件作为构建配置选项,则您可以选择使用此字段来定义特定于触发器的替代变量

      在以下示例中,我们想要通过与 gcr 事件关联的载荷和操作获取映像标记的名称。为此,请使用载荷绑定创建替代变量。

      指定以下变量和值:

      变量名称 变量值
      _IMAGE_TAG $(body.message.data.tag)
      _ACTION $(body.message.data.action)

      body.message 引用发布者发布并由订阅者使用的 PubSubMessage。如需查看 Pub/Sub 通知载荷的更多示例,请参阅通知示例

    • 过滤条件(可选):您可以在触发器中创建过滤条件,以通过对替代变量指定过滤条件确定触发器是否会执行构建来响应传入的载荷。过滤条件表达式求得的值必须为 true,才能执行构建。

      在包含多个消息的主题上设置 Pub/Sub 触发器时,我们建议使用过滤条件。过滤器可用于精确控制为响应传入的 Pub/Sub 消息而执行的构建。如需了解在未设置过滤条件的情况下设置触发器的相关风险,请参阅与未过滤的触发器有关的风险

      在以下示例中,我们希望触发器在 _IMAGE_TAG 标记变量的名称与特定标记名称(例如 prod)匹配时执行构建。您可以将过滤条件运算符指定为“==”,以进行完全匹配。您还可以检查与 gcr 事件关联的操作。例如,您可以将 _ACTION 指定为 INSERT 以查找新添加的数据。

      指定以下内容作为过滤条件:

      • _IMAGE_TAG == prod
      • _ACTION == INSERT

      Pub/Sub 触发器中的过滤语法使用通用表达式语言 (CEL) 进行表达式求值。如需详细了解 CEL,请参阅 cel-spec 代码库。如需查看可应用于 Pub/Sub 触发器的更多过滤语法示例,请参阅过滤构建

  1. 点击创建以创建构建触发器
  2. .

gcloud

如需创建触发器以侦听 Container Registry 中的映像推送并使用 gcloud 命令根据标记名称进行匹配,请执行以下操作:

  1. 打开一个终端窗口。
  2. 运行 gcloud alpha 命令,在项目中创建一个构建触发器。在以下示例中,触发器配置为根据替代变量 _IMAGE_TAG 定义的指定载荷,响应标记与 prod 匹配且操作与 INSERT 匹配的构建。

     gcloud alpha builds triggers create pubsub \
       --name=TRIGGER_NAME \
       --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
       --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
       --substitutions=\
         _IMAGE_TAG_='$(body.message.data.tag)'
         _ACTION='$(body.message.data.action)'
       --filter='_IMAGE_TAG == "prod" && _ACTION == "INSERT"'
       --repo=REPO_NAME
       --tag=TAG_NAME  # or --branch=BRANCH_NAME
    

    其中:

    • TRIGGER_NAME 是触发器的名称。
    • PROJECT_ID 是您的 Cloud 项目的 ID。
    • TOPIC_NAME 是您订阅的 Pub/Sub 主题的名称。
    • BUILD_CONFIG 是构建配置文件的路径。
    • INLINE_BUILD_CONFIG 是内嵌构建配置文件的路径。
    • REPO_NAME 是调用构建所基于的源代码库的名称。
    • 如果您想要将触发器设置为基于标记构建,则 TAG_NAME 是您的标记的名称。
    • 如果您想要将触发器设置为基于分支构建,则 BRANCH_NAME 是您的分支的名称。

创建构建触发器来响应 Cloud Storage 事件

您可以创建一个 Pub/Sub 触发器来响应 Cloud Storage 事件(例如,新的二进制文件被推送到现有存储分区时)。本部分介绍如何创建 Pub/Sub 触发器,该触发器会在将新二进制文件部署到上传的存储分区时使用构建进行响应。如果您不熟悉 Cloud Storage,请参阅快速入门

控制台

如需使用 Google Cloud Console 创建触发器以侦听 Cloud Storage 事件,请执行以下操作:

  1. 打开触发器页面

    打开“触发器”页面

  2. 从页面顶部选择您的项目,然后点击打开

  3. 点击创建触发器

  4. 输入以下触发器设置:

    • 名称:输入触发器的名称。
    • 说明(可选):输入触发器的说明。
    • 事件:选择 Pub/Sub 消息作为用于调用触发器的事件。
    • 订阅:选择要订阅作为触发器事件的 Pub/Sub 主题。您会在下拉菜单中看到项目中的所有现有主题。

    • 来源:选择要在触发器运行时构建的代码库。

    • 修订版本:选择要在触发器运行时构建的分支或标记。

      • 分支:输入调用构建所基于的分支的名称。
      • 标记:输入调用构建所基于的标记的名称。
    • 配置:选择构建配置文件(位于远程代码库),或创建要用于构建的内嵌构建配置文件。

      • 类型:选择要用于构建的配置类型。
        • Cloud Build 配置文件(yaml 或 json):为您的配置使用构建配置文件。
        • Dockerfile:为您的配置使用 Dockerfile
        • Buildpack:为您的配置使用 buildpack
      • 位置:为您的配置指定位置。

        • 代码库:如果您的配置文件位于远程代码库中,请提供构建配置文件的位置、Dockerfile 目录或 buildpack 目录。如果您的构建配置类型是 Dockerfile 或 buildpack,则需要为生成的映像提供名称,还需要视情况提供构建的超时时间。提供了 Dockerfile 或 buildpack 映像名称后,您会看到您的构建将执行的 docker buildpack 命令的预览。
        • Buildpack 环境变量(可选):如果您选择了 buildpacks 作为配置类型,请点击添加软件包环境变量以指定 buildpack 环境变量和值。如需详细了解 buildpack 环境变量,请参阅环境变量
        • 内嵌:如果您选择了 Cloud Build 配置文件(yaml 或 json)作为配置选项,则可以指定内嵌构建配置。点击打开编辑器,使用 YAML 或 JSON 语法在 Google Cloud Console 中编写您的构建配置文件。点击完成以保存您的构建配置。

    • 替代变量(可选):如果您选择了构建配置文件作为构建配置选项,则您可以选择使用此字段来定义特定于触发器的替代变量

      在此示例中,我们想要在新二进制文件上传到存储分区后监控其部署。如需获取此数据,我们可以使用载荷绑定创建替代变量。

      指定以下变量和值:

      变量名称 变量值
      _EVENT_TYPE $(body.message.attributes.eventType)
      _BUCKET_ID $(body.message.attributes.bucketId)
      _OBJECT_ID $(body.message.attributes.objectId)

      body.message 引用发布者发布并由订阅者使用的 PubSubMessage。如需查看 Pub/Sub 通知载荷的更多示例,请参阅通知示例

    • 过滤条件(可选):您可以在触发器中创建过滤条件,以通过对替代变量指定过滤条件确定触发器是否会执行构建来响应传入的载荷。过滤条件表达式求得的值必须为 true,才能执行构建。

      在包含多个消息的主题上设置 Pub/Sub 触发器时,我们建议使用过滤条件。过滤器可用于精确控制为响应传入的 Pub/Sub 消息而执行的构建。如需了解在未设置过滤条件的情况下设置触发器的相关风险,请参阅与未过滤的触发器有关的风险

      我们想要触发器在新二进制文件部署到特定存储分区时执行构建,因此可以使用“==”运算符来检查是否完全匹配。如果您想要按正则表达式进行匹配,则还可以使用“matches”关键字。

      指定以下内容作为过滤条件:

      • _EVENT_TYPE == OBJECT_FINALIZE
      • _OBJECT_ID^<object-id>$ 匹配
      • _BUCKET_ID^<bucket-id>$ 匹配
  1. 点击创建以创建构建触发器
  2. .

gcloud

如需在 Cloud Storage 中创建构建触发器来侦听具有特定事件类型的构建事件,请执行以下操作:

  1. 打开一个终端窗口。
  2. 运行 gcloud alpha 命令,在项目中创建一个构建触发器。在以下示例中,触发器配置为通过与推送到现有存储分区的新二进制文件关联的 Cloud Storage 事件响应构建:

     gcloud alpha builds triggers create pubsub \
       --name=TRIGGER_NAME \
       --topic=projects/PROJECT_ID/topics/TOPIC_NAME \
       --build-config=BUILD_CONFIG \ # or --inline-config=INLINE_BUILD_CONFIG
       --substitutions=\
         _EVENT_TYPE='$(body.message.attributes.eventType)'
         _BUCKET_ID='$(body.message.attributes.bucketId)'
         _OBJECT_ID='$(body.message.attributes.objectId)'
       --filter='_EVENT_TYPE == "OBJECT_FINALIZE" && _OBJECT_ID.matches("<object-id>") && _BUCKET_ID.matches("<bucket-id>")'
       --repo=REPO_NAME
       --tag=TAG_NAME  # or --branch=BRANCH_NAME
    

    其中:

    • TRIGGER_NAME 是触发器的名称。
    • PROJECT_ID 是您的 Cloud 项目的 ID。
    • TOPIC_NAME 是您订阅的 Pub/Sub 主题的名称。
    • BUILD_CONFIG 是构建配置文件的路径。
    • INLINE_BUILD_CONFIG 是内嵌构建配置文件的路径。
    • REPO_NAME 是调用构建所基于的源代码库的名称。
    • 如果您想要将触发器设置为基于标记构建,则 TAG_NAME 是您的标记的名称。
    • 如果您想要将触发器设置为基于分支构建,则 BRANCH_NAME 是您的分支的名称。

与未过滤的触发器有关的风险

如果您尚未对 Pub/Sub 触发器配置过滤条件,并且触发器修改了工件或对象,导致无意中将新消息发布到触发器正侦听的主题,则触发器最终可能会调用无限数量的构建。例如,如果触发器执行以下操作,则触发器可能会调用无限数量的构建:

  • 指向 gcr 主题。
  • gcr 中创建任何映像或标记。
  • 指向存储分区中特定对象的 gcs 主题并修改该对象。

如果遇到无限循环,您可以删除触发器或将触发器更新为指向单独的主题,以避免为调用的每个构建支付额外费用。

使用 CEL 过滤构建事件

Cloud Build 在构建资源中列出的字段上搭配使用 CEL 与变量 build,以便访问与构建事件关联的字段,例如触发器 ID、图片列表或替换值。您可以使用 filter 字符串,通过构建资源中列出的任何字段,来过滤通构建配置文件中的构建事件。如需查找与您的字段关联的具体语法,请参阅 cloudbuild.proto 文件。

按触发器 ID 过滤

要按触发器 ID 过滤,请使用 build.build_trigger_idfilter 字段中指定触发器 ID 的值,其中 trigger-id 是字符串形式的触发器 ID:

filter: build.build_trigger_id == trigger-id

按状态过滤

要按状态过滤,请使用 build.statusfilter 字段中指定要过滤的构建状态。

以下示例展示了如何使用 filter 字段过滤状态为 SUCCESS 的构建事件:

filter: build.status == Build.Status.SUCCESS

您也可以过滤具有不同状态的构建。以下示例展示了如何使用 filter 字段过滤状态为 SUCCESSFAILURETIMEOUT 的构建事件:

filter: build.status in [Build.Status.SUCCESS, Build.Status.FAILURE, Build.Status.TIMEOUT]

要查看您可以作为过滤依据的其他状态值,请参阅“构建资源参考”下的状态

按标记过滤

要按标记过滤,请使用 build.tagsfilter 字段中指定标记的值,其中 tag-name 是标记的名称:

filter: tag-name in build.tags

您可以使用 size 根据构建事件中指定的标记数量进行过滤。在以下示例中,filter 字段会过滤仅指定了两个标记且其中一个标记指定为 v1 的构建事件:

filter: size(build.tags) == 2 && "v1" in build.tags

按图片过滤

要按图片过滤,请使用 build.imagesfilter 字段中指定图片的值,其中 image-name 是 Container Registry 中列出的图片的全名,例如 gcr.io/example/image-one

filter: image-name in build.images

在以下示例中,filter 会过滤将 gcr.io/example/image-onegcr.io/example/image-two 指定为图片名称的构建事件:

filter: "gcr.io/example/image-one" in build.images || "gcr.io/example/image-two" in build.images

按时间过滤

您可以在 filter 字段中指定以下某个选项,以根据构建的创建时间、开始时间或结束时间过滤构建事件:build.create_timebuild.start_timebuild.finish_time

在以下示例中,filter 字段会使用 timestamp 来过滤创建构建的请求时间为 2020 年 7 月 20 日上午 6:00 的构建事件。

filter: build.create_time == timestamp("2020-07-20:T06:00:00Z")

您还可以按时间比较过滤构建事件。在以下示例中,filter 字段会使用 timestamp 过滤开始时间介于 2020 年 7 月 20 日上午 6:00 到 2020 年 7 月 30 日上午 6:00 之间的构建事件。

filter: timestamp("2020-07-20:T06:00:00Z") >= build.start_time && build.start_time <= timestamp("2020-07-30:T06:00:00Z")

如需详细了解 CEL 中的时区表示方式,请参阅时区的语言定义。

要按构建的持续时间进行过滤,您可以使用 duration 比较时间戳。 在以下示例中,filter 字段会使用 duration 过滤包含至少运行了五分钟的构建的构建事件:

filter: build.finish_time - build.start_time >= duration("5m")

按替换过滤

您可以使用 build.substitutionsfilter 字段中指定替换变量,从而按替换进行过滤。在以下示例中,filter 字段会列出包含替代变量 substitution-variable 的构建,并检查 substitution-variable 是否与指定的 substitution-value 匹配:

filter: build.substitutions[substitution-variable] == substitution-value

其中:

  • substitution-variable 是替代变量的名称。
  • substitution-value 是替代变量值的名称。

您还可以按默认替换变量值进行过滤。在下面的示例中,filter 字段列出分支名称为 master 的构建,以及代码库名称为 github.com/user/my-example-repo 的构建。默认替换变量 BRANCH_NAMEREPO_NAME 将作为密钥传递给 build.substitutions

filter: build.substitutions["BRANCH_NAME"] == "master" && build.substitutions["REPO_NAME"] == "github.com/user/my-example-repo"

如果要使用正则表达式过滤字符串,则可以使用内置的 matches 函数。在以下示例中,filter 字段过滤状态为 FAILURE 或 TIMEOUT 的构建,并且有一个构建替代变量 TAG_NAME,以及一个与正则表达式 v{DIGIT}.{DIGIT}.{3 DIGITS}) 匹配的值。

filter: build.status in [Build.Status.FAILURE, Build.Status.TIMEOUT] && build.substitutions["TAG_NAME"].matches("^v\\d{1}\\.\\d{1}\\.\\d{3}$")`

要查看默认替换值的列表,请参阅使用默认替换

后续步骤