第8章 ビルドのトリガーおよび変更
以下のセクションでは、ビルドフックを使用してビルドをトリガーし、ビルドを変更する方法についての概要を説明します。
8.1. ビルドトリガー
BuildConfig の定義時に、BuildConfig を実行する必要のある状況を制御するトリガーを定義できます。以下のビルドトリガーを利用できます。
- Webhook
- イメージの変更
- 設定の変更
8.1.1. Webhook のトリガー
Webhook のトリガーにより、要求を OpenShift Container Platform API エンドポイントに送信して新規ビルドをトリガーできます。GitHub、GitLab、Bitbucket または Generic webhook を使用して、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 という名前のキーで、Secret と、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: c2VjcmV0dmFsdWUx8.1.1.1. GitHub Webhook の使用
GitHub webhook は 、リポジトリーの更新時に GitHub からの呼び出しを処理します。トリガーを定義するときに、secret を定義してください。 このシークレットは、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>/oapi/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/oapi/v1/namespaces/nsname/buildconfigs/bcname/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>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github
-kの引数は、API サーバーに正しく署名された証明書がない場合にのみ必要です。
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 の表示を参照)。 ペイロード URL は以下のように設定されます。
https://<openshift_api_host:port>/oapi/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>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/gitlab
-kの引数は、API サーバーに正しく署名された証明書がない場合にのみ必要です。
追加リソース
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 の表示を参照)。 ペイロード URL は以下のように設定されます。
https://<openshift_api_host:port>/oapi/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>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/bitbucket
-kの引数は、API サーバーに正しく署名された証明書がない場合にのみ必要です。
追加リソース
8.1.1.4. Generic Webhook の使用
Generic Webhook は、Web 要求を実行できるシステムから呼び出されます。他の webhook と同様に、シークレットを指定する必要があります。このシークレットを使用することで 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>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/generic
呼び出し元は、
POST操作として Webhook を呼び出す必要があります。手動で Webhook を呼び出すには、
curlを使用します。$ curl -X POST -k https://<openshift_api_host:port>/oapi/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>/oapi/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 の表示
以下のコマンドを使用して、BuildConfig に関連付けられた Webhook URL を表示します。コマンドが Webhook URL を表示しない場合、そのビルド設定に定義される Webhook トリガーはありません。トリガーを手動で追加するには、トリガーの設定を参照してください。
手順
-
BuildConfigに関連付けられた Webhook URL を表示するには、以下を実行します。
$ oc describe bc <name>
8.1.2. イメージ変更トリガーの使用
イメージ変更のトリガーを使用すると、アップストリームで新規バージョンが利用できるようになるとビルドが自動的に呼び出されます。たとえば、RHEL イメージ上にビルドが設定されている場合には、RHEL のイメージが変更された時点でビルドの実行をトリガーできます。その結果、アプリケーションイメージは常に最新の RHEL ベースイメージ上で実行されるようになります。
v1 コンテナーレジストリー のコンテナーイメージを参照するイメージストリームは、イメージストリームタグが利用できるようになった時点でビルドが度だけトリガーされ、後続のイメージ更新ではトリガーされません。これは、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 フィールドを設定して、イメージストリームを参照します。
strategy: sourceStrategy: from: kind: "ImageStreamTag" name: "ruby-20-centos7:latest"上記の例では、
sourceStrategyの定義は、この namespace 内に配置されているruby-20-centos7という名前のイメージストリームのlatestタグを使用します。イメージストリームを参照する 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 が作成されるとすぐに、ビルドが自動的に起動されます。
以下の例は、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 のシークレットが再生成されます。
詳細情報は、oc set triggers --help のヘルプドキュメントを参照してください。