第 8 章 触发和修改构建

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

8.1. 构建触发器

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

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

8.1.1. Webhook 触发器

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

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

处理推送事件时,OpenShift Container Platform 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

其他资源

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>/oapi/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/oapi/v1/namespaces/nsname/buildconfigs/bcname/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>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github

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

其他资源

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(请参阅“显示 Webhook URL”),其结构如下:

https://<openshift_api_host:port>/oapi/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>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/gitlab

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

其他资源

8.1.1.3. 使用 Bitbucket Webhook

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

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

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

https://<openshift_api_host:port>/oapi/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>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/bitbucket

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

其他资源

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>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic

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

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

    $ curl -X POST -k https://<openshift_api_host:port>/oapi/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>/oapi/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 响应的一部分。

8.1.1.5. 显示 Webhook URL

您可以使用以下命令来显示与 BuildConfig 关联的 Webhook URL。如果命令不显示任何 Webhook URL,则没有为该构建配置定义任何 Webhook 触发器。请参阅“设置触发器”来手动添加触发器。

流程

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

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 字段设置为指向该镜像流:

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

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

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

    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>。这将确保使用一致的镜像标签来执行构建,以方便再生。

其他资源

8.1.3. 配置更改触发器

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

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

  type: "ConfigChange"
注意

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

8.1.3.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 来查阅帮助文档