サポートコンソール開発者トライアルの開始お問い合わせ

第8章 ビルドのトリガーおよび変更

以下のセクションでは、ビルドフックを使用してビルドをトリガーし、ビルドを変更する方法に関する概要を説明します。

8.1. ビルドトリガー

BuildConfig の定義時に、BuildConfig を実行する必要のある状況を制御するトリガーを定義できます。以下のビルドトリガーを利用できます。

  • Webhook
  • イメージの変更
  • 設定の変更

8.1.1. Webhook のトリガー

Webhook のトリガーにより、要求を OpenShift Container Platform API エンドポイントに送信して新規ビルドをトリガーできます。GitHub、GitLab、Bitbucket または Generic webhook を使用してこれらのトリガーを定義できます。

OpenShift Container Platform の Webhook は現在、Git ベースのソースコード管理システム (SCM) システムのそれぞれのプッシュイベントの類似のバージョンのみをサポートしています。その他のイベントタイプはすべて無視されます。

プッシュイベントを処理する場合に、OpenShift Container Platform コントロールプレーンホストは、イベント内のブランチ参照が、対応の BuildConfig のブランチ参照と一致しているかどうを確認します。一致する場合には、OpenShift Container Platform ビルドの Webhook イベントに記載されているのと全く同じコミット参照がチェックアウトされます。一致しない場合には、ビルドはトリガーされません。

注記

oc new-app および oc new-build は GitHub および Generic Webhook トリガーを自動的に作成しますが、それ以外の Webhook トリガーが必要な場合には手動で追加する必要があります。トリガーを設定して、トリガーを手動で追加できます。

Webhook すべてに対して、WebHookSecretKey という名前のキーでシークレットと、Webook の呼び出し時に提供される値を定義する必要があります。webhook の定義で、このシークレットを参照する必要があります。このシークレットを使用することで URL が一意となり、他の URL でビルドがトリガーされないようにします。キーの値は、webhook の呼び出し時に渡されるシークレットと比較されます。

たとえば、mysecret という名前のシークレットを参照する GitHub webhook は以下のとおりです。 

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

次に、シークレットは以下のように定義します。シークレットの値は base64 エンコードされており、この値は Secret オブジェクトの data フィールドに必要である点に注意してください。 

- kind: Secret
  apiVersion: v1
  metadata:
    name: mysecret
    creationTimestamp:
  data:
    WebHookSecretKey: c2VjcmV0dmFsdWUx

8.1.1.1. GitHub Webhook の使用

GitHub webhook は、リポジトリーの更新時に GitHub からの呼び出しを処理します。トリガーを定義する際に、シークレットを指定する必要があります。このシークレットは、Webhook の設定時に GitHub に指定する URL に追加されます。

GitHub Webhook の定義例: 

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

Webhook トリガーの設定で使用されるシークレットは、GitHub UI で Webhook の設定時に表示される secret フィールドとは異なります。Webhook トリガー設定で使用するシークレットは、Webhook URL を一意にして推測ができないようにし、GitHub UI のシークレットは、任意の文字列フィールドで、このフィールドを使用して本体の HMAC hex ダイジェストを作成して、X-Hub-Signature ヘッダーとして送信します。

oc describe コマンドは、ペイロード URL を GitHub Webhook URL として返します (Webhook URL の表示を参照)。 ペイロード 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. Payload URL フィールドに、URL の出力を貼り付けます。
    5. Content Type を GitHub のデフォルト application/x-www-form-urlencoded から application/json に変更します。

    6. Add webhook をクリックします。

      webhook の設定が正常に完了したことを示す GitHub のメッセージが表示されます。

      これで変更を GitHub リポジトリーにプッシュする際に新しいビルドが自動的に起動し、ビルドに成功すると新しいデプロイメントが起動します。

      注記

      Gogs は、GitHub と同じ webhook のペイロード形式をサポートします。そのため、Gogs サーバーを使用する場合は、GitHub webhook トリガーを BuildConfig に定義すると、Gogs サーバー経由でもトリガーされます。

  2. payload.json などの有効な 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

    -k の引数は、API サーバーに正しく署名された証明書がない場合にのみ必要です。

注記

ビルドは、GitHub Webhook イベントからの ref 値が、BuildConfig リソースの source.git フィールドで指定された ref 値と一致する場合にのみトリガーされます。

関連情報

8.1.1.2. GitLab Webhook の使用

GitLab Webhook は、リポジトリーの更新時の GitLab による呼び出しを処理します。GitHub トリガーでは、シークレットを指定する必要があります。以下の例は、BuildConfig 内のトリガー定義の YAML です。 

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

oc describe コマンドは、ペイロード URL を GitLab Webhook URL として返します。 ペイロード 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> はシークレットの値に置き換えます。
    3. GitLab の設定手順 に従い、GitLab リポジトリーの設定に Webhook URL を貼り付けます。

  2. payload.json などの有効な 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

    -k の引数は、API サーバーに正しく署名された証明書がない場合にのみ必要です。

8.1.1.3. Bitbucket Webhook の使用

Bitbucket webhook は、リポジトリーの更新時の Bitbucket による呼び出しを処理します。これまでのトリガーと同様に、シークレットを指定する必要があります。以下の例は、BuildConfig 内のトリガー定義の YAML です。 

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

oc describe コマンドは、ペイロード URL を Bitbucket Webhook URL として返します。ペイロード 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> はシークレットの値に置き換えます。
    3. Bitbucket の設定手順 に従い、Bitbucket リポジトリーの設定に Webhook URL を貼り付けます。

  2. payload.json などの有効な 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

    -k の引数は、API サーバーに正しく署名された証明書がない場合にのみ必要です。

8.1.1.4. Generic Webhook の使用

Generic Webhook は、Web 要求を実行できるシステムから呼び出されます。他の webhook と同様に、シークレットを指定する必要があります。このシークレットは、呼び出し元がビルドをトリガーするために使用する必要のある URL に追加されます。このシークレットを使用することで URL が一意となり、他の URL でビルドがトリガーされないようにします。以下の例は、BuildConfig 内のトリガー定義の YAML です。 

type: "Generic"
generic:
  secretReference:
    name: "mysecret"
  allowEnv: true 1
1
true に設定して、Generic Webhook が環境変数で渡させるようにします。

手順

  1. 呼び出し元を設定するには、呼び出しシステムに、ビルドの Generic 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 フラグを指定して、証明書の検証を無視します。クラスターに正しく署名された証明書がある場合には、2 つ目のフラグは必要ありません。

    エンドポイントは、以下の形式で任意のペイロードを受け入れることができます。 

    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

    引数は、ヘッダーとペイロードを追加した以前の例と同じです。-H の引数は、ペイロードの形式により Content-Type ヘッダーを application/yaml または application/json に設定します。--data-binary の引数を使用すると、POST 要求では、改行を削除せずにバイナリーペイロードを送信します。

注記

OpenShift Container Platform は、要求のペイロードが無効な場合でも (例: 無効なコンテンツタイプ、解析不可能または無効なコンテンツなど)、Generic Webhook 経由でビルドをトリガーできます。この動作は、後方互換性を確保するために継続されています。無効な要求ペイロードがある場合には、OpenShift Container Platform は、HTTP 200 OK 応答の一部として JSON 形式で警告を返します。

8.1.1.5. Webhook URL の表示

以下のコマンドを使用して、ビルド設定に関連する webhook URL を表示できます。コマンドが Webhook URL を表示しない場合、そのビルド設定に定義される Webhook トリガーはありません。

手順

  • BuildConfig に関連付けられた Webhook URL を表示するには、以下を実行します。 
$ oc describe bc <name>

8.1.2. イメージ変更トリガーの使用

開発者は、ベースイメージが変更するたびにビルドを自動的に実行するように設定できます。

イメージ変更のトリガーを使用すると、アップストリームイメージで新規バージョンが利用できるようになると、ビルドが自動的に呼び出されます。たとえば、RHEL イメージ上にビルドが設定されている場合に、RHEL のイメージが変更された時点でビルドの実行をトリガーできます。その結果、アプリケーションイメージは常に最新の RHEL ベースイメージ上で実行されるようになります。

注記

v1 コンテナーレジストリー のコンテナーイメージを参照するイメージストリームは、イメージストリームタグが利用できるようになった時点でビルドが 1 度だけトリガーされ、後続のイメージ更新ではトリガーされません。これは、v1 コンテナーレジストリーに一意で識別可能なイメージがないためです。

手順

  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 の定義は、この namespace 内に配置されている ruby-20-centos7 という名前のイメージストリームの latest タグを使用します。

  3. ImageStreams を参照する 1 つまたは複数のトリガーでビルドを定義します。 

    type: "ImageChange" 1
imageChange: {}
type: "ImageChange" 2
imageChange:
  from:
    kind: "ImageStreamTag"
    name: "custom-image:latest"
    1
    ビルドストラテジーの from フィールドに定義されたように ImageStream および Tag を監視するイメージ変更トリガー。ここの 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 の例

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 つまたは複数のビルドがトリガーされています。

手順

  1. buildConfig.status.imageChangeTriggers で、最新のタイムスタンプを持つ lastTriggerTime を特定します。

    This ImageChangeTriggerStatus 

    Then you use the `name` and `namespace` from that build to find the corresponding image change trigger in `buildConfig.spec.triggers`.
  2. imageChangeTriggers でタイムスタンプを比較して最新のものを特定します。

イメージ変更のトリガー

ビルド設定で、buildConfig.spec.triggers はビルドトリガーポリシー (BuildTriggerPolicy) の配列です。

各 BuildTriggerPolicy には type フィールドと、ポインターフィールドのセットがあります。各ポインターフィールドは、type フィールドに許可される値の 1 つに対応します。そのため、BuildTriggerPolicy を 1 つのポインターフィールドのみに設定できます。

イメージ変更のトリガーの場合、type の値は ImageChange です。次に、imageChange フィールドは、以下のフィールドを持つ ImageChangeTrigger オブジェクトへのポインターです。

  • lastTriggeredImageID: このフィールドは例では提供されず、OpenShift Container Platform 4.8 で非推奨となり、今後のリリースでは無視されます。これには、最後のビルドがこの BuildConfig からトリガーされた際に ImageStreamTag の解決されたイメージ参照が含まれます。
  • paused: このフィールドは、この例では示されていませんが、この特定のイメージ変更トリガーを一時的に無効にするのに使用できます。
  • from: このフィールドを使用して、このイメージ変更トリガーを駆動する ImageStreamTag を参照します。このタイプは、コア Kubernetes タイプである OwnerReference です。

from フィールドには、注意フィールド kind があります。イメージ変更トリガーの場合、サポートされる値は ImageStreamTag のみです。 namespace: このフィールドを使用して ImageStreamTag の namespace を指定します。** name: このフィールドを使用して ImageStreamTag を指定します。

イメージ変更のトリガーのステータス

ビルド設定で、buildConfig.status.imageChangeTriggers は ImageChangeTriggerStatus 要素の配列です。それぞれの ImageChangeTriggerStatus 要素には、前述の例に示されている from、lastTriggeredImageID、および lastTriggerTime 要素が含まれます。

最新の lastTriggerTime を持つ ImageChangeTriggerStatus は、最新のビルドをトリガーしました。name および namespace を使用して、ビルドをトリガーした buildConfig.spec.triggers でイメージ変更トリガーを特定します。

lastTriggerTime は最新のタイムスタンプ記号で、最後のビルドの ImageChangeTriggerStatus を示します。この ImageChangeTriggerStatus には、ビルドをトリガーした buildConfig.spec.triggers のイメージ変更トリガーと同じ name および namespace があります。

関連情報

8.1.4. 設定変更のトリガー

設定変更トリガーにより、新規の BuildConfig が作成されるとすぐに、ビルドが自動的に起動されます。

以下の例は、BuildConfig 内のトリガー定義の YAML です。 

  type: "ConfigChange"
注記

設定変更のトリガーは新しい BuildConfig が作成された場合のみ機能します。今後のリリースでは、設定変更トリガーは、BuildConfig が更新されるたびにビルドを起動できるようになります。

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 のシークレットが再生成されます。

詳細情報は、以下を実行してヘルプドキュメントを参照してください。 

$ oc set triggers --help
Red Hat logoGithubRedditYoutubeTwitter

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

Red Hat をお使いのお客様が、信頼できるコンテンツが含まれている製品やサービスを活用することで、イノベーションを行い、目標を達成できるようにします。

多様性を受け入れるオープンソースの強化

Red Hat では、コード、ドキュメント、Web プロパティーにおける配慮に欠ける用語の置き換えに取り組んでいます。このような変更は、段階的に実施される予定です。詳細情報: Red Hat ブログ.

会社概要

Red Hat は、企業がコアとなるデータセンターからネットワークエッジに至るまで、各種プラットフォームや環境全体で作業を簡素化できるように、強化されたソリューションを提供しています。

© 2024 Red Hat, Inc.