搜索

2.8. 触发和修改构建

download PDF

以下小节概述了如何使用构建 hook 触发构建和修改构建。

2.8.1. 构建触发器

在定义 BuildConfig 时,您可以定义触发器来控制应该运行 BuildConfig 的环境。可用的构建触发器如下:

  • Webhook
  • 镜像更改
  • 配置更改

2.8.1.1. Webhook 触发器

Webhook 触发器通过发送请求到 OpenShift Container Platform API 端点来触发新构建。您可以使用 GitHub、GitLab、Bitbucket 或通用 Webhook 来定义这些触发器。

目前,OpenShift Container Platform Webhook 仅支持各种基于 Git 的源代码管理系统 (SCM) 的推送事件的类同版本。所有其他事件类型都会忽略。

处理推送事件时,OpenShift Container Platform control plane 主机(也称为 master 主机)确认事件内的分支引用是否与相应 BuildConfig 中的分支引用匹配。如果匹配,它会检查 OpenShift Container Platform 构建的 Webhook 事件中记录的确切提交引用。如果不匹配,则不触发构建。

注意

oc new-appoc new-build 会自动创建 GitHub 和通用 Webhook 触发器,但其他所需的 Webhook 触发器都必须手动添加。您可以通过设置触发器来手动添加触发器。

对于所有 Webhook,您必须使用名为 WebHookSecretKey 的键定义 secret,并且其值是调用 Webhook 时要提供的值。然后,Webhook 定义必须引用该 secret。secret可确保 URL 的唯一性,防止他人触发构建。键的值将与 Webhook 调用期间提供的 secret 进行比较。

例如,此处的 GitHub Webhook 具有对名为 mysecret 的 secret 的引用:

type: "GitHub"
github:
  secretReference:
    name: "mysecret"

该 secret 的定义如下。注意 secret 的值采用 base64 编码,如 Secret 对象的 data 字段所要求。

- kind: Secret
  apiVersion: v1
  metadata:
    name: mysecret
    creationTimestamp:
  data:
    WebHookSecretKey: c2VjcmV0dmFsdWUx
2.8.1.1.1. 使用 GitHub Webhook

当存储库更新时,GitHub Webhook 处理 GitHub 发出的调用。在定义触发器时,您必须指定一个 secret,它将是您在配置 Webhook 时提供给 GitHub 的 URL 的一部分。

GitHub Webhook 定义示例:

type: "GitHub"
github:
  secretReference:
    name: "mysecret"
注意

Webhook 触发器配置中使用的 secret 与在 GitHub UI 中配置 Webhook 时遇到的 secret 字段不同。前者使 Webhook URL 唯一且难以预测,后者是一个可选的字符串字段,用于创建正文的 HMAC 十六进制摘要,作为 X-Hub-Signature 标头来发送。

oc describe 命令将有效负载 URL 返回为 GitHub Webhook URL(请参阅“显示 Webhook URL”),其结构如下:

输出示例

https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github

先决条件

  • 从 GitHub 存储库创建 BuildConfig

流程

  1. 配置 GitHub Webhook:

    1. 从 GitHub 存储库创建 BuildConfig 后,运行以下命令:

      $ oc describe bc/<name-of-your-BuildConfig>

      这会生成一个 Webhook GitHub URL,如下所示:

      输出示例

      <https://api.starter-us-east-1.openshift.com:443/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github

    2. 从 GitHub Web 控制台将此 URL 剪切并粘贴到 GitHub 中。
    3. 在 GitHub 存储库中,从 Settings Webhooks 中选择 Add Webhook
    4. 将 URL 输出粘贴到 Payload URL 字段。
    5. Content Type 从 GitHub 默认的 application/x-www-form-urlencoded 更改为 application/json
    6. 点击 Add webhook

      您应该看到一条来自 GitHub 的消息,说明您的 Webhook 已配置成功。

      现在,每当您将更改推送到 GitHub 存储库时,新构建会自动启动,成功构建后也会启动新部署。

      注意

      Gogs 支持与 GitHub 相同的 Webhook 有效负载格式。因此,如果您使用的是 Gogs 服务器,也可以在 BuildConfig 中定义 GitHub Webhook 触发器,并由 Gogs 服务器触发它。

  2. 提供含有有效 JSON 内容的文件后,如 payload.json,您可以使用 curl 手动触发 Webhook:

    $ curl -H "X-GitHub-Event: push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github

    只有在 API 服务器没有适当签名的证书时,才需要 -k 参数。

其他资源

2.8.1.1.2. 使用 GitLab Webhook

当存储库更新时,GitLab Webhook 处理 GitLab 发出的调用。与 GitHub 触发器一样,您必须指定一个 secret。以下示例是 BuildConfig 中的触发器定义 YAML:

type: "GitLab"
gitlab:
  secretReference:
    name: "mysecret"

oc describe 命令将有效负载 URL 返回为 GitLab Webhook URL,其结构如下:

输出示例

https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/gitlab

流程

  1. 配置 GitLab Webhook:

    1. 描述 BuildConfig 以获取 Webhook URL:

      $ oc describe bc <name>
    2. 复制 Webhook URL,将 <secret> 替换为您的 secret 值。
    3. 按照 GitLab 设置说明,将 Webhook URL 粘贴到 GitLab 存储库设置中。
  2. 提供含有有效 JSON 内容的文件后,如 payload.json,您可以使用 curl 手动触发 Webhook:

    $ curl -H "X-GitLab-Event: Push Hook" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/gitlab

    只有在 API 服务器没有适当签名的证书时,才需要 -k 参数。

2.8.1.1.3. 使用 Bitbucket Webhook

当存储库更新时,Bitbucket Webhook 处理 Bitbucket 发出的调用。与前面的触发器类似,您必须指定一个 secret。以下示例是 BuildConfig 中的触发器定义 YAML:

type: "Bitbucket"
bitbucket:
  secretReference:
    name: "mysecret"

oc describe 命令将有效负载 URL 返回为 Bitbucket Webhook URL,其结构如下:

输出示例

https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/bitbucket

流程

  1. 配置 Bitbucket Webhook:

    1. 描述 BuildConfig 以获取 Webhook URL:

      $ oc describe bc <name>
    2. 复制 Webhook URL,将 <secret> 替换为您的 secret 值。
    3. 按照 Bitbucket 设置说明,将 Webhook URL 粘贴到 Bitbucket 存储库设置中。
  2. 提供含有有效 JSON 内容的文件后,如 payload.json,您可以使用 curl 手动触发 Webhook:

    $ curl -H "X-Event-Key: repo:push" -H "Content-Type: application/json" -k -X POST --data-binary @payload.json https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/bitbucket

    只有在 API 服务器没有适当签名的证书时,才需要 -k 参数。

2.8.1.1.4. 使用通用 Webhook

通用 Webhook 可从能够发出 Web 请求的任何系统调用。与其他 Webhook一样,您必须指定一个 secret,该 secret 将成为调用者必须用于触发构建的 URL 的一部分。secret可确保 URL 的唯一性,防止他人触发构建。如下是 BuildConfig 中的示例触发器定义 YAML:

type: "Generic"
generic:
  secretReference:
    name: "mysecret"
  allowEnv: true 1
1
设置为 true,以允许通用 Webhook 传入环境变量。

流程

  1. 要设置调用者,请为调用系统提供构建的通用 Webhook 端点的 URL:

    输出示例

    https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic

    调用者必须以 POST 操作形式调用 Webhook。

  2. 要手动调用 Webhook,您可以使用 curl

    $ curl -X POST -k https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic

    HTTP 操作动词必须设置为 POST。指定了不安全 -k 标志以忽略证书验证。如果集群拥有正确签名的证书,则不需要此第二个标志。

    端点可以接受具有以下格式的可选有效负载:

    git:
      uri: "<url to git repository>"
      ref: "<optional git reference>"
      commit: "<commit hash identifying a specific git commit>"
      author:
        name: "<author name>"
        email: "<author e-mail>"
      committer:
        name: "<committer name>"
        email: "<committer e-mail>"
      message: "<commit message>"
    env: 1
       - name: "<variable name>"
         value: "<variable value>"
    1
    BuildConfig 环境变量类似,此处定义的环境变量也可供您的构建使用。如果这些变量与 BuildConfig 环境变量发生冲突,则以这些变量为准。默认情况下,Webhook 传递的环境变量将被忽略。在 Webhook 定义上将 allowEnv 字段设为 true 即可启用此行为。
  3. 要使用 curl 传递此有效负载,请在名为 payload_file.yaml 的文件中进行定义,再运行以下命令:

    $ curl -H "Content-Type: application/yaml" --data-binary @payload_file.yaml -X POST -k https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic

    参数与前一个示例相同,但添加了标头和 payload。-H 参数将 Content-Type 标头设置为 application/yamlapplication/json,具体取决于您的 payload 格式。--data-binary 参数用于通过 POST 请求发送带有换行符的二进制 payload。

注意

即使出示了无效的请求 payload(例如,无效的内容类型,或者无法解析或无效的内容等),OpenShift Container Platform 也允许通用 Webhook 触发构建。保留此行为是为了向后兼容。如果出示无效的请求 payload,OpenShift Container Platform 将以 JSON 格式返回警告,作为其 HTTP 200 OK 响应的一部分。

2.8.1.1.5. 显示 Webhook URL

您可以使用以下命令来显示与构建配置关联的 Webhook URL。如果命令不显示任何 Webhook URL,则没有为该构建配置定义任何 Webhook 触发器。

流程

  • 显示与 BuildConfig 关联的任何 Webhook URL:
$ oc describe bc <name>

2.8.1.2. 使用镜像更改触发器

作为开发人员,您可以将构建配置为在每次基础镜像更改时自动运行。

当上游镜像有新版本可用时,您可以使用镜像更改触发器自动调用构建。例如,如果构建基于 RHEL 镜像,您可以触发该构建在 RHEL 镜像更改时运行。因此,应用程序镜像始终在最新的 RHEL 基础镜像上运行。

注意

指向 v1 容器 registry 中的容器镜像的镜像流仅在镜像流标签可用时触发一次构建,后续镜像更新时则不会触发。这是因为 v1 容器 registry 中缺少可唯一标识的镜像。

流程

  1. 定义指向您要用作触发器的上游镜像的 ImageStream

    kind: "ImageStream"
    apiVersion: "v1"
    metadata:
      name: "ruby-20-centos7"

    这将定义绑定到位于 <system-registry>/<namespace>/ruby-20-centos7 的容器镜像存储库的镜像流。<system-registry> 定义为 OpenShift Container Platform 中运行的名为 docker-registry 的服务。

  2. 如果镜像流是构建的基础镜像,请将构建策略中的 from 字段设置为指向 ImageStream

    strategy:
      sourceStrategy:
        from:
          kind: "ImageStreamTag"
          name: "ruby-20-centos7:latest"

    在这种情形中,sourceStrategy 定义将消耗此命名空间中名为 ruby-20-centos7 的镜像流的 latest 标签。

  3. 使用指向 ImageStreams 的一个或多个触发器定义构建:

    type: "ImageChange" 1
    imageChange: {}
    type: "ImageChange" 2
    imageChange:
      from:
        kind: "ImageStreamTag"
        name: "custom-image:latest"
    1
    监控构建策略的 from 字段中定义的 ImageStreamTag 的镜像更改触发器。此处的 imageChange 对象必须留空。
    2
    监控任意镜像流的镜像更改触发器。此时 imageChange 部分必须包含一个 from 字段,以引用要监控的 ImageStreamTag

将镜像更改触发器用于策略镜像流时,生成的构建会获得一个不可变 docker 标签,指向与该标签对应的最新镜像。在执行构建时,策略会使用此新镜像引用。

对于不引用策略镜像流的其他镜像更改触发器,系统会启动新构建,但不会使用唯一镜像引用来更新构建策略。

由于此示例具有策略的镜像更改触发器,因此生成的构建将是:

strategy:
  sourceStrategy:
    from:
      kind: "DockerImage"
      name: "172.30.17.3:5001/mynamespace/ruby-20-centos7:<immutableid>"

这将确保触发的构建使用刚才推送到存储库的新镜像,并且可以使用相同的输入随时重新运行构建。

您可以暂停镜像更改触发器,以便在构建开始之前对引用的镜像流进行多次更改。在将 ImageChangeTrigger 添加到 BuildConfig 时,您也可以将 paused 属性设为 true,以避免立即触发构建。

type: "ImageChange"
imageChange:
  from:
    kind: "ImageStreamTag"
    name: "custom-image:latest"
  paused: true

除了设置适用于所有 Strategy 类型的镜像字段外,自定义构建还需要检查 OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE 环境变量。如果不存在,则使用不可变镜像引用来创建它。如果存在,则使用不可变镜像引用进行更新。

如果因为 Webhook 触发器或手动请求而触发构建,则创建的构建将使用从 Strategy 引用的 ImageStream 解析而来的 <immutableid>。这将确保使用一致的镜像标签来执行构建,以方便再生。

其他资源

2.8.1.3. 识别构建的镜像更改触发器

作为开发人员,如果您有镜像更改触发器,您可以识别启动了上一次构建的镜像更改。这对于调试或故障排除构建非常有用。

BuildConfig示例

apiVersion: build.openshift.io/v1
kind: BuildConfig
metadata:
  name: bc-ict-example
  namespace: bc-ict-example-namespace
spec:

# ...

  triggers:
  - imageChange:
      from:
        kind: ImageStreamTag
        name: input:latest
        namespace: bc-ict-example-namespace
  - imageChange:
      from:
        kind: ImageStreamTag
        name: input2:latest
        namespace: bc-ict-example-namespace
    type: ImageChange
status:
  imageChangeTriggers:
  - from:
      name: input:latest
      namespace: bc-ict-example-namespace
    lastTriggerTime: "2021-06-30T13:47:53Z"
    lastTriggeredImageID: image-registry.openshift-image-registry.svc:5000/bc-ict-example-namespace/input@sha256:0f88ffbeb9d25525720bfa3524cb1bf0908b7f791057cf1acfae917b11266a69
  - from:
      name: input2:latest
      namespace: bc-ict-example-namespace
    lastTriggeredImageID:  image-registry.openshift-image-registry.svc:5000/bc-ict-example-namespace/input2@sha256:0f88ffbeb9d25525720bfa3524cb2ce0908b7f791057cf1acfae917b11266a69

  lastVersion: 1

注意

本例省略了与镜像更改触发器无关的元素。

先决条件

  • 您已配置了多个镜像更改触发器。这些触发器已触发一个或多个构建。

流程

  1. buildConfig.status.imageChangeTriggers 中,标识具有最新时间戳的 lastTriggerTime

    这个 ImageChangeTriggerStatus

    Then you use the `name` and `namespace` from that build to find the corresponding image change trigger in `buildConfig.spec.triggers`.
  2. UnderimageChangeTriggers 下,比较时间戳以标识最新的

镜像更改触发器

在构建配置中,buildConfig.spec.triggers 是构建触发器策略 BuildTriggerPolicy 的数组。

每个 BuildTriggerPolicy 都有 type 字段和指针字段。每个指针字段对应于 type 字段允许的值之一。因此,您只能将 BuildTriggerPolicy 设置为一个指针字段。

对于镜像更改触发器,type 的值为 ImageChange。然后,imageChange 字段是指向 ImageChangeTrigger 对象的指针,其具有以下字段:

  • lastTriggeredImageID:此字段在 OpenShift Container Platform 4.8 中已弃用,并将在以后的发行版本中被忽略。它包含从此 BuildConfig 触发最后一次构建时的 ImageStreamTag 的已解析镜像引用。
  • paused:您可以使用此字段(示例中未显示)暂时禁用此特定镜像更改触发器。
  • from:您使用此字段引用驱动此镜像更改触发器的 ImageStreamTag。其类型是核心 Kubernetes 类型 OwnerReference

from 字段有以下备注字段: kind: 对于镜像更改触发器,唯一支持的值是 ImageStreamTag namespace:您可以使用此字段指定 ImageStreamTag 的命名空间。** name :您可以使用此字段指定 ImageStreamTag

镜像更改触发器状态

在构建配置中,buildConfig.status.imageChangeTriggersImageChangeTriggerStatus 元素的数组。每个 ImageChangeTriggerStatus 元素都包含上例中所示的 fromlastTriggeredImageIDlastTriggerTime 元素。

具有最新 lastTriggerTimeImageChangeTriggerStatus 触发了最新的构建。您可以使用其 namenamespace 来识别触发构建的 buildConfig.spec.triggers 中的镜像更改触发器。

带有最新时间戳的 lastTriggerTime 表示最后一个构建的 ImageChangeTriggerStatus。此 ImageChangeTriggerStatusnamenamespace 与触发构建的 buildConfig.spec.triggers 中的镜像更改触发器相同。

其他资源

2.8.1.4. 配置更改触发器

通过配置更改触发器,您可以在创建新 BuildConfig 时立即自动调用构建。

如下是 BuildConfig 中的示例触发器定义 YAML:

  type: "ConfigChange"
注意

配置更改触发器目前仅在创建新 BuildConfig 时运作。在未来的版本中,配置更改触发器也可以在每当 BuildConfig 更新时启动构建。

2.8.1.4.1. 手动设置触发器

您可以使用 oc set triggers 在构建配置中添加和移除触发器。

流程

  • 要在构建配置上设置 GitHub Webhook 触发器,请使用:

    $ oc set triggers bc <name> --from-github
  • 要设置镜像更改触发器,请使用:

    $ oc set triggers bc <name> --from-image='<image>'
  • 要移除触发器,请添加 --remove

    $ oc set triggers bc <name> --from-bitbucket --remove
注意

如果 Webhook 触发器已存在,再次添加它会重新生成 Webhook secret。

如需更多信息,请查阅帮助文档

$ oc set triggers --help

2.8.2. 构建 hook

通过构建 hook,可以将行为注入到构建过程中。

BuildConfig 对象的 postCommit 字段在运行构建输出镜像的临时容器内执行命令。Hook 的执行时间是紧接在提交镜像的最后一层后,并且在镜像推送到 registry 之前。

当前工作目录设置为镜像的 WORKDIR,即容器镜像的默认工作目录。对于大多数镜像,这是源代码所处的位置。

如果脚本或命令返回非零退出代码,或者启动临时容器失败,则 hook 将失败。当 hook 失败时,它会将构建标记为失败,并且镜像也不会推送到 registry。可以通过查看构建日志来检查失败的原因。

构建 hook 可用于运行单元测试,以在构建标记为完成并在 registry 中提供镜像之前验证镜像。如果所有测试都通过并且测试运行器返回退出代码 0,则构建标记为成功。如果有任何测试失败,则构建标记为失败。在所有情况下,构建日志将包含测试运行器的输出,这可用于识别失败的测试。

postCommit hook 不仅限于运行测试,也可用于运行其他命令。由于它在临时容器内运行,因此 hook 所做的更改不会持久存在;也就是说,hook 执行无法对最终镜像造成影响。除了其他用途外,也可借助此行为来安装和使用会自动丢弃并且不出现在最终镜像中的测试依赖项。

2.8.2.1. 配置提交后构建 hook

配置提交后构建 hook 的方法有多种。以下示例中所有形式具有同等作用,也都执行 bundle exec rake test --verbose

流程

  • Shell 脚本:

    postCommit:
      script: "bundle exec rake test --verbose"

    script 值是通过 /bin/sh -ic 执行的 shell 脚本。当 shell 脚本适合执行构建 hook 时可使用此选项。例如,用于运行前文所述的单元测试。若要控制镜像入口点,或者如果镜像没有 /bin/sh,可使用 command 和/或 args

    注意

    引入的额外 -i 标志用于改进搭配 CentOS 和 RHEL 镜像时的体验,未来的发行版中可能会剔除。

  • 命令作为镜像入口点:

    postCommit:
      command: ["/bin/bash", "-c", "bundle exec rake test --verbose"]

    在这种形式中,command 是要运行的命令,它会覆盖 exec 形式中的镜像入口点,如 Dockerfile 引用中所述。如果镜像没有 /bin/sh,或者您不想使用 shell,则需要这样做。在所有其他情形中,使用 script 可能更为方便。

  • 命令带有参数:

    postCommit:
      command: ["bundle", "exec", "rake", "test"]
      args: ["--verbose"]

    这种形式相当于将参数附加到 command

注意

同时提供 scriptcommand 会产生无效的构建 hook。

2.8.2.2. 使用 CLI 设置提交后构建 hook

oc set build-hook 命令可用于为构建配置设置构建 hook。

流程

  1. 将命令设置为提交后构建 hook:

    $ oc set build-hook bc/mybc \
        --post-commit \
        --command \
        -- bundle exec rake test --verbose
  2. 将脚本设置为提交后构建 hook:

    $ oc set build-hook bc/mybc --post-commit --script="bundle exec rake test --verbose"
Red Hat logoGithubRedditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务,以及可以信赖的内容,帮助红帽用户创新并实现他们的目标。

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情,请参阅红帽博客.

關於紅帽

我们提供强化的解决方案,使企业能够更轻松地跨平台和环境(从核心数据中心到网络边缘)工作。

© 2024 Red Hat, Inc.