第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
を作成します。
手順
GitHub Webhook を設定するには以下を実行します。
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
- GitHub の Web コンソールから、この URL を GitHub にカットアンドペーストします。
-
GitHub リポジトリーで、Settings
Webhooks から Add Webhook を選択します。 - Payload URL フィールドに、URL の出力を貼り付けます。
-
Content Type を GitHub のデフォルト
application/x-www-form-urlencoded
からapplication/json
に変更します。 Add webhook をクリックします。
webhook の設定が正常に完了したことを示す GitHub のメッセージが表示されます。
これで変更を GitHub リポジトリーにプッシュする際に新しいビルドが自動的に起動し、ビルドに成功すると新しいデプロイメントが起動します。
注記Gogs は、GitHub と同じ webhook のペイロード形式をサポートします。そのため、Gogs サーバーを使用する場合は、GitHub webhook トリガーを
BuildConfig
に定義すると、Gogs サーバー経由でもトリガーされます。
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
手順
GitLab Webhook を設定するには以下を実行します。
BuildConfig
を Webhook URL を取得するように記述します。$ oc describe bc <name>
-
Webhook URL をコピーします。
<secret>
はシークレットの値に置き換えます。 - GitLab の設定手順 に従い、GitLab リポジトリーの設定に Webhook URL を貼り付けます。
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
手順
Bitbucket Webhook を設定するには以下を実行します。
'BuildConfig' を記述して Webhook URL を取得します。
$ oc describe bc <name>
-
Webhook URL をコピーします。
<secret>
はシークレットの値に置き換えます。 - Bitbucket の設定手順 に従い、Bitbucket リポジトリーの設定に Webhook URL を貼り付けます。
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 が環境変数で渡させるようにします。
手順
呼び出し元を設定するには、呼び出しシステムに、ビルドの Generic Webhook エンドポイントの URL を指定します。
出力例
https://<openshift_api_host:port>/apis/build.openshift.io/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic
呼び出し元は、
POST
操作として Webhook を呼び出す必要があります。手動で 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
に設定して、この動作を有効にします。
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 コンテナーレジストリーに一意で識別可能なイメージがないためです。
手順
トリガーするアップストリームイメージを参照するように、
ImageStream
を定義します。kind: "ImageStream" apiVersion: "v1" metadata: name: "ruby-20-centos7"
この定義では、イメージストリームが
<system-registry>/<namespace>/ruby-20-centos7
に配置されているコンテナーイメージリポジトリーに紐付けられます。<system-registry>
は、OpenShift Container Platform で実行する名前がdocker-registry
のサービスとして定義されます。イメージストリームがビルドのベースイメージの場合には、ビルドストラテジーの
from
フィールドを設定して、ImageStream
を参照します。strategy: sourceStrategy: from: kind: "ImageStreamTag" name: "ruby-20-centos7:latest"
上記の例では、
sourceStrategy
の定義は、この namespace 内に配置されているruby-20-centos7
という名前のイメージストリームのlatest
タグを使用します。ImageStreams
を参照する 1 つまたは複数のトリガーでビルドを定義します。type: "ImageChange" 1 imageChange: {} type: "ImageChange" 2 imageChange: from: kind: "ImageStreamTag" name: "custom-image:latest"
ストラテジーイメージストリームにイメージ変更トリガーを使用する場合は、生成されたビルドに不変な 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 つまたは複数のビルドがトリガーされています。
手順
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`.
-
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