Red Hat Training
A Red Hat training course is available for OpenShift Container Platform
第8章 ビルド
8.1. ビルドの仕組み
8.1.1. ビルドの概要
OpenShift Container Platform での「ビルド」とは、入力パラメーターをオブジェクトに変換するプロセスのことです。多くの場合に、ビルドを使用して、ソースコードを実行可能なコンテナーイメージに変換します。
ビルド設定 または BuildConfig
は、ビルドストラテジー と 1 つまたは複数のソースを特徴としています。ストラテジーは前述のプロセスを決定し、ソースは入力内容を提供します。
ビルドストラテジーには、以下が含まれます。
「ビルド入力」として指定できるソースは 6 種類あります。
ビルドストラテジーごとに、特定タイプのソースを検討するか、または無視するか、またはそのソースタイプの使用方法が決まります。バイナリーおよび Git のソースタイプは併用できません。Dockerfile とイメージは、そのまま単体で使用することも、2 つを併用することも、Git またはバイナリーと組み合わせることも可能です。バイナリーのソースタイプは、他のオプションと比べると「システムへの指定方法」という点が独特です。
8.1.2. BuildConfig の概要
ビルド設定は、単一のビルド定義と新規ビルドを作成するタイミングについての トリガーを記述します。ビルド設定は BuildConfig
で定義されます。BuildConfig は、新規インスタンスを作成するために API サーバーへの POST で使用可能な REST オブジェクトのことです。
OpenShift Container Platform を使用したアプリケーションの作成方法の選択に応じて Web コンソールまたは CLI のいずれを使用している場合でも、BuildConfig
は通常自動的に作成され、いつでも編集できます。BuildConfig
を構成する部分や利用可能なオプションを理解しておくと、後に設定を手動で調整する場合に役立ちます。
以下の BuildConfig
の例では、コンテナーイメージのタグやソースコードが変更されるたびに新規ビルドが作成されます。
BuildConfig のオブジェクト定義
kind: "BuildConfig" apiVersion: "v1" metadata: name: "ruby-sample-build" 1 spec: runPolicy: "Serial" 2 triggers: 3 - type: "GitHub" github: secret: "secret101" - type: "Generic" generic: secret: "secret101" - type: "ImageChange" source: 4 git: uri: "https://github.com/openshift/ruby-hello-world" strategy: 5 sourceStrategy: from: kind: "ImageStreamTag" name: "ruby-20-centos7:latest" output: 6 to: kind: "ImageStreamTag" name: "origin-ruby-sample:latest" postCommit: 7 script: "bundle exec rake test"
- 1
- この仕様は、ruby-sample-build という名前の新規の
BuildConfig
を作成します。 - 2
runPolicy
フィールドは、このビルド設定に基づいて作成されたビルドを同時に実行できるかどうかを制御します。デフォルトの値はSerial
です。これは新規ビルドが同時にではなく、順番に実行されることを意味します。- 3
- 新規ビルドを作成する トリガー の一覧を指定できます。
- 4
source
セクションでは、ビルドのソースを定義します。ソースの種類は入力の主なソースを決定し、Git
(コードのリポジトリーの場所を参照)、Dockerfile
(インラインの Dockerfile からビルド) またはBinary
(バイナリーペイロードを受け入れる) のいずれかとなっています。複数のソースを一度に指定できます。詳細は、各ソースタイプのドキュメントを参照してください。- 5
strategy
セクションでは、ビルドの実行に使用するビルドストラテジーを記述します。ここではSource
、Docker
またはCustom
ストラテジーを指定できます。上記の例では、Source-To-Image がアプリケーションのビルドに使用するruby-20-centos7
コンテナーイメージを使用します。- 6
- コンテナーイメージが正常にビルドされた後に、これは
output
セクションで記述されているリポジトリーにプッシュされます。 - 7
postCommit
セクションは、オプションで ビルドフック を定義します。
8.2. 基本的なビルド操作
8.2.1. ビルドの開始
以下のコマンドを使用して、現在のプロジェクトに既存のビルド設定から新規ビルドを手動で起動します。
$ oc start-build <buildconfig_name>
--from-build
フラグを使用してビルドを再度実行します。
$ oc start-build --from-build=<build_name>
--follow
フラグを指定して、stdout のビルドのログをストリームします。
$ oc start-build <buildconfig_name> --follow
--env
フラグを指定して、ビルドに任意の環境変数を設定します。
$ oc start-build <buildconfig_name> --env=<key>=<value>
Git ソースプルまたは Dockerfile に依存してビルドするのではなく、ソースを直接プッシュしてビルドを開始することも可能です。ソースには、Git または SVN の作業ディレクトリーの内容、デプロイする事前に構築済みバイナリーアーティファクトまたは単一ファイルのいずれかを選択できます。これは、start-build
コマンドに以下のオプションのいずれかを指定して実行できます。
オプション | 説明 |
---|---|
|
アーカイブし、ビルドのバイナリー入力として使用するディレクトリーを指定します。 |
|
単一ファイルを指定します。これはビルドソースで唯一のファイルでなければなりません。このファイルは、元のファイルと同じファイル名で空のディレクトリーのルートに置いてください。 |
|
ビルドのバイナリー入力として使用するローカルリポジトリーへのパスを指定します。 |
以下のオプションをビルドに直接指定した場合には、コンテンツはビルドにストリームされ、現在のビルドソースの設定が上書きされます。
バイナリー入力からトリガーされたビルドは、サーバー上にソースを保存しないため、ベースイメージの変更でビルドが再度トリガーされた場合には、ビルド設定で指定されたソースが使用されます。
たとえば、以下のコマンドは、タグ v2
からのアーカイブとしてローカルの Git リポジトリーのコンテンツを送信し、ビルドを開始します。
$ oc start-build hello-world --from-repo=../hello-world --commit=v2
8.2.2. ビルドの中止
Web コンソールまたは以下の CLI コマンドを使用して、ビルドを手動でキャンセルします。
$ oc cancel-build <build_name>
複数のビルドを同時にキャンセルします。
$ oc cancel-build <build1_name> <build2_name> <build3_name>
ビルド設定から作成されたビルドすべてをキャンセルします。
$ oc cancel-build bc/<buildconfig_name>
特定の状態にあるビルドをすべてキャンセルします (例: new または pending)。この際、他の状態のビルドは無視されます。
$ oc cancel-build bc/<buildconfig_name> --state=<state>
8.2.3. BuildConfig の削除
以下のコマンドで BuildConfig
を削除します。
$ oc delete bc <BuildConfigName>
これにより、この BuildConfig
でインスタンス化されたビルドがすべて削除されます。ビルドを削除しない場合には、--cascade=false
フラグを指定します。
$ oc delete --cascade=false bc <BuildConfigName>
8.2.4. ビルドの詳細表示
web コンソールまたは oc describe
CLI コマンドを使用して、ビルドの詳細を表示できます。
$ oc describe build <build_name>
これにより、以下のような情報が表示されます。
- ビルドソース
- ビルドストラテジー
- 出力先
- 宛先レジストリーのイメージのダイジェスト
- ビルドの作成方法
ビルドが Docker
または Source
ストラテジーを使用する場合、oc describe
出力には、コミット ID、作成者、コミットしたユーザー、メッセージなどのビルドに使用するソースのリビジョンの情報が含まれます。
8.2.5. ビルドログへのアクセス
Web コンソールまたは CLI を使用してビルドログにアクセスできます。
ビルドを直接使用してログをストリームするには、以下を実行します。
$ oc logs -f build/<build_name>
ビルド設定の最新ビルドのログをストリームするには、以下を実行します。
$ oc logs -f bc/<buildconfig_name>
ビルド設定で指定されているバージョンのビルドに関するログを返すには、以下を実行します。
$ oc logs --version=<number> bc/<buildconfig_name>
ログの詳細レベル
詳細の出力を有効にするには、BuildConfig
内の sourceStrategy
または dockerStrategy
の一部として BUILD_LOGLEVEL
環境変数を指定します。
sourceStrategy:
...
env:
- name: "BUILD_LOGLEVEL"
value: "2" 1
- 1
- この値を任意のログレベルに調整します。
プラットフォームの管理者は、BuildDefaults
受付コントローラーの env/BUILD_LOGLEVEL
を設定して、OpenShift Container Platform インスタンス全体のデフォルトのビルドの詳細レベルを設定できます。このデフォルトは、指定の BuildConfig
で BUILD_LOGLEVEL
を指定することで上書きできます。コマンドラインで --build-loglevel
を oc start-build
に渡すことで、バイナリー以外のビルドについて優先順位の高い上書きを指定することができます。
ソースビルドで利用できるログレベルは以下のとおりです。
レベル 0 |
assemble スクリプトを実行してコンテナーからの出力とすべてのエラーを生成します。これはデフォルトの設定です。 |
レベル 1 |
実行したプロセスに関する基本情報を生成します。 |
レベル 2 |
実行したプロセスに関する詳細情報を生成します。 |
レベル 3 |
実行したプロセスに関する詳細情報と、アーカイブコンテンツの一覧を生成します。 |
レベル 4 |
現時点ではレベル 3 と同じ情報を生成します。 |
レベル 5 |
これまでのレベルで記載したすべての内容と docker のプッシュメッセージを提供します。 |
8.3. ビルド入力
8.3.1. ビルド入力の仕組み
ビルド入力 は、ビルドが動作するために必要なソースコンテンツを提供します。OpenShift Cotainer Platform では複数の方法でソースを提供します。以下に優先順に記載します。
異なる入力を単一のビルドにまとめることができます。インラインの Dockerfile が優先されるため、別の入力で指定される Dockerfile という名前の他のファイルは上書きされます。バイナリー (ローカル) 入力および Git リポジトリーは併用できません。
入力シークレットは、ビルド時に使用される特定のリソースや認証情報をビルドで生成される最終アプリケーションイメージで使用不可にする必要がある場合や、Secret
リソースで定義される値を使用する必要がある場合に役立ちます。外部アーティファクトは、他のビルド入力タイプのいずれとして利用できない別のファイルをプルする場合に使用できます。
ビルドが実行されるたびに、以下が行われます。
- 作業ディレクトリーが作成され、すべての入力内容がその作業ディレクトリーに配置されます。たとえば、入力 Git リポジトリーのクローンはこの作業ディレクトリーに作成され、入力イメージから指定されたファイルはターゲットのパスを使用してこの作業ディレクトリーにコピーされます。
-
ビルドプロセスによりディレクトリーが
contextDir
に変更されます (定義されている場合)。 - インライン Dockerfile がある場合は、現在のディレクトリーに書き込まれます。
-
現在の作業ディレクトリーにある内容が Dockerfile、カスタムビルダーのロジック、または assemble スクリプトが参照するビルドプロセスに提供されます。つまり、ビルドでは
contextDir
内にない入力コンテンツは無視されます。
以下のソース定義の例には、複数の入力タイプと、入力タイプの統合方法の説明が含まれています。それぞれの入力タイプの定義方法に関する詳細は、各入力タイプについての個別のセクションを参照してください。
source: git: uri: https://github.com/openshift/ruby-hello-world.git 1 images: - from: kind: ImageStreamTag name: myinputimage:latest namespace: mynamespace paths: - destinationDir: app/dir/injected/dir 2 sourcePath: /usr/lib/somefile.jar contextDir: "app/dir" 3 dockerfile: "FROM centos:7\nRUN yum install -y httpd" 4
8.3.2. Dockerfile のソース
dockerfile
の値が指定されると、このフィールドの内容は、Dockerfile という名前のファイルとしてディスクに書き込まれます。これは、他の入力ソースが処理された後に実行されるので、入力ソースリポジトリーの root ディレクトリーに Dockerfile が含まれる場合は、これはこの内容で上書きされます。
このフィールドの一般的な用途は、Dockerfile
を「Docker ストラテジー」ビルドに渡すことです。
ソースの定義は BuildConfig
の spec
セクションに含まれます。
source:
dockerfile: "FROM centos:7\nRUN yum install -y httpd" 1
- 1
dockerfile
フィールドには、ビルドされるインライン Dockerfile が含まれます。
8.3.3. イメージソース
追加のファイルは、イメージを使用してビルドプロセスに渡すことができます。入力イメージは From
および To
イメージターゲットが定義されるのと同じ方法で参照されます。つまり、コンテナーイメージと「イメージストリームタグ」の両方を参照できます。イメージと合わせて、1 つまたは複数のパスのペアを指定して、ファイルまたはディレクトリーのパスを示し、イメージと宛先をコピーしてビルドコンテキストに配置する必要があります。
ソースパスは、指定したイメージ内の絶対パスで指定してください。宛先は、相対ディレクトリーパスでなければなりません。ビルド時に、イメージは読み込まれ、指定のファイルおよびディレクトリーはビルドプロセスのコンテキストディレクトリーにコピーされます。これは、ソースリポジトリーのコンテンツ (ある場合) のクローンが作成されるディレクトリーと同じです。ソースパスの末尾は /. であり、ディレクトリーのコンテンツがコピーされますが、ディレクトリー自体は宛先で作成されません。
イメージのインプットは、BuildConfig
の source
の定義で指定します。
source: git: uri: https://github.com/openshift/ruby-hello-world.git images: 1 - from: 2 kind: ImageStreamTag name: myinputimage:latest namespace: mynamespace paths: 3 - destinationDir: injected/dir 4 sourcePath: /usr/lib/somefile.jar 5 - from: kind: ImageStreamTag name: myotherinputimage:latest namespace: myothernamespace pullSecret: mysecret 6 paths: - destinationDir: injected/dir sourcePath: /usr/lib/somefile.jar
この機能は、カスタムストラテジー を使用したビルドではサポートされません。
8.3.4. git ソース
指定されている場合には、ソースコードが指定先の場所からフェッチされます。
インラインの Dockerfile がサポートされる場合には、git リポジトリー contextDir
内にあるDockerfile (ある場合) が上書きされます。
ソースの定義は BuildConfig
の spec
セクションに含まれます。
source: git: 1 uri: "https://github.com/openshift/ruby-hello-world" ref: "master" contextDir: "app/dir" 2 dockerfile: "FROM openshift/ruby-22-centos7\nUSER example" 3
- 1
git
フィールドには、ソースコードのリモート git リポジトリーへの URI が含まれます。オプションで、ref
フィールドを指定して特定の git 参照をチェックアウトします。SHA1 タグまたはブランチ名は、ref
として有効です。- 2
contextDir
フィールドでは、ビルドがアプリケーションのソースコードを検索する、ソースコードのリポジトリー内のデフォルトの場所を上書きできます。アプリケーションがサブディレクトリーに存在する場合には、このフィールドを使用してデフォルトの場所 (root フォルダー) を上書きすることができます。- 3
- オプションの
dockerfile
フィールドがある場合は、Dockerfile を含む文字列を指定してください。この文字列は、ソースリポジトリーに存在する可能性のある Dockerfile を上書きします。
ref
フィールドにプル要求が記載されている場合には、システムは git fetch
操作を使用して FETCH_HEAD
をチェックアウトします。
ref
の値が指定されていない場合は、OpenShift Container Platform はシャロークローン (--depth=1
) を実行します。この場合、デフォルトのブランチ (通常は master
) での最新のコミットに関連するファイルのみがダウンロードされます。これにより、リポジトリーのダウンロード時間が短縮されます (詳細のコミット履歴はありません)。指定リポジトリーのデフォルトのブランチで完全な git clone
を実行するには、ref
をデフォルトのブランチ名に設定します (例: master
)。
8.3.4.1. プロキシーの使用
プロキシー経由でのみ Git リポジトリーにアクセスできる場合には、BuildConfig
の source
セクションで使用するプロキシーを定義できます。HTTP および HTTPS プロキシーの両方を設定できますが、いずれのフィールドもオプションです。プロキシーを使用すべきでないドメインは、NoProxy フィールドで指定することも可能です。
これを機能させるには、ソース URI で HTTP または HTTPS プロトコルを使用する必要があります。
source: git: uri: "https://github.com/openshift/ruby-hello-world" httpProxy: http://proxy.example.com httpsProxy: https://proxy.example.com noProxy: somedomain.com, otherdomain.com
クラスター管理者は「Ansible を使用した Git クローン用のグローバルプロキシーの設定」を実行することもできます。
Pipeline ストラテジーのビルドの場合には、現在 Jenkins の Git プラグインに制約があるので、Git プラグインを使用する Git の操作では BuildConfig
に定義された HTTP または HTTPS プロキシーは使用されません。Git プラグインは、Jenkins UI の Plugin Manager パネルで設定されたプロキシーのみを使用します。どのジョブであっても、Jenkins 内の git のすべての対話にはこのプロキシーが使用されます。Jenkins UI でのプロキシーの設定方法については、JenkinsBehindProxy を参照してください。
8.3.4.2. ソースクローンのシークレット
ビルダー Pod には、ビルドのソースとして定義された git リポジトリーへのアクセスが必要です。ソースクローンのシークレットは、ビルダー Pod に対し、プライベートリポジトリーや自己署名証明書または信頼されていない SSL 証明書が設定されたリポジトリーなどの通常アクセスできないリポジトリーへのアクセスを提供するために使用されます。
以下は、サポートされているソースクローンのシークレット設定です。
個別のニーズに対応すべく、これらの設定を 組み合わせて 使用することも可能です。
ビルドは builder サービスアカウントで実行されます。この builder アカウントには、使用するソースクローンのシークレットに対するアクセスが必要です。以下のコマンドを使用してアクセスを付与できます。
$ oc secrets link builder mysecret
シークレットを参照しているサービスアカウントにのみにシークレットを制限することはデフォルトで無効にされています。つまり、serviceAccountConfig.limitSecretReferences
がマスター設定ファイルで false
(デフォルト設定) に設定されている場合は、サービスにシークレットをリンクする必要はありません。
8.3.4.2.1. ソースクローンシークレットのビルド設定への自動追加
BuildConfig
が作成されると、OpenShift Container Platform は自動的にソースクローンのシークレット参照を生成します。この動作により、追加の設定なしに、作成される Builds
が参照される Secret
に保存された認証情報を自動的に使用して、リモート git リポジトリーへの認証を行います。
この機能を使用するには、git リポジトリーの認証情報を含む Secret
が BuildConfig
が後に作成される namespace になければなりません。この Secret
には、プレフィックスbuild.openshift.io/source-secret-match-uri-
で開始するアノテーション 1 つ以上含まれている必要もあります。これらの各アノテーションの値には、以下で定義される URI パターンを指定します。ソースクローンのシークレット参照なしに BuildConfig
が作成され、git ソースの URI が Secret
アノテーションの URI パターンと一致する場合に、OpenShift Container Platform はその Secret
への参照を BuildConfig
に自動的に挿入します。
URI パターンには以下を含める必要があります。
-
有効なスキーム (
*://
、git://
、http://
、https://
またはssh://
) -
ホスト (
*
または、有効なホスト名、オプションで*.
が先頭に指定された IP アドレス) -
パス (
/*
または、/
の後に*
などの文字が後に続く文字列)
上記のいずれの場合でも、*
文字はワイルドカードと見なされます。
URI パターンは、RFC3986 に準拠する Git ソースの URI と一致する必要があります。URI パターンのにユーザー名 (またはパスワード) のコンポーネントを含ないようにしてください。
たとえば、git リポジトリーの URL に ssh://git@bitbucket.atlassian.com:7999/ATLASSIAN/jira.git
を使用する場合に、ソースのシークレットは ssh://bitbucket.atlassian.com:7999/*
として指定する必要があります (ssh://git@bitbucket.atlassian.com:7999/*
ではありません)。
$ oc annotate secret mysecret \ 'build.openshift.io/source-secret-match-uri-1=ssh://bitbucket.atlassian.com:7999/*'
複数の Secrets
が特定の BuildConfig
の Git URI と一致する場合は、OpenShift Container Platform は一致する文字列が一番長いシークレットを選択します。これは、以下の例のように基本的な上書きを許可します。
以下の部分的な例では、ソースクローンのシークレットの一部が 2 つ表示されています。1 つ目は、HTTPS がアクセスする mycorp.com
ドメイン内のサーバーに一致しており、2 つ目は mydev1.mycorp.com
および mydev2.mycorp.com
のサーバーへのアクセスを上書きします。
kind: Secret apiVersion: v1 metadata: name: matches-all-corporate-servers-https-only annotations: build.openshift.io/source-secret-match-uri-1: https://*.mycorp.com/* data: ... kind: Secret apiVersion: v1 metadata: name: override-for-my-dev-servers-https-only annotations: build.openshift.io/source-secret-match-uri-1: https://mydev1.mycorp.com/* build.openshift.io/source-secret-match-uri-2: https://mydev2.mycorp.com/* data: ...
以下のコマンドを使用して、build.openshift.io/source-secret-match-uri-
アノテーションを既存のシークレットに追加します。
$ oc annotate secret mysecret \ 'build.openshift.io/source-secret-match-uri-1=https://*.mycorp.com/*'
8.3.4.2.2. ソースクローンシークレットの手動による追加
ソースクローンのシークレットは、ビルド設定に手動で追加できます。これは、sourceSecret
フィールドを BuildConfig
内の source
セクションに追加して、これを作成した secret
の名前に設定して実行できます (この例では basicsecret
)。
apiVersion: "v1" kind: "BuildConfig" metadata: name: "sample-build" spec: output: to: kind: "ImageStreamTag" name: "sample-image:latest" source: git: uri: "https://github.com/user/app.git" sourceSecret: name: "basicsecret" strategy: sourceStrategy: from: kind: "ImageStreamTag" name: "python-33-centos7:latest"
oc set build-secret
コマンドを使用して、既存のビルド設定にソースクローンのシークレットを設定することも可能です。
$ oc set build-secret --source bc/sample-build basicsecret
「BuildConfig でのシークレットの定義」では、このトピックについて詳しく説明しています。
8.3.4.2.3. .gitconfig ファイル
アプリケーションのクローンが .gitconfig ファイルに依存する場合、そのファイルが含まれるシークレットを作成してからこれをビルダーサービスアカウントに追加し、BuildConfig
に追加できます。
.gitconfig ファイルからシークレットを作成するには、以下を実行します。
$ oc create secret generic <secret_name> --from-file=<path/to/.gitconfig>
.gitconfig ファイルの http
セクションが sslVerify=false
に設定されている場合は、SSL 認証をオフにすることができます。
[http] sslVerify=false
8.3.4.2.4. セキュアな git 用の .gitconfig ファイル
Git サーバーが 2-way SSL、ユーザー名とパスワードでセキュリティー保護されている場合には、ソースビルドに証明書ファイルを追加して、.gitconfig ファイルに証明書ファイルへの参照を追加する必要があります。
- client.crt、cacert.crt および client.key ファイルを「アプリケーションのソースコード」の /var/run/secrets/openshift.io/source/ フォルダーに追加します。
サーバーの .gitconfig ファイルに、以下の例のように
[http]
セクションを追加します。# cat .gitconfig [user] name = <name> email = <email> [http] sslVerify = false sslCert = /var/run/secrets/openshift.io/source/client.crt sslKey = /var/run/secrets/openshift.io/source/client.key sslCaInfo = /var/run/secrets/openshift.io/source/cacert.crt
シークレットを作成します。
$ oc create secret generic <secret_name> \ --from-literal=username=<user_name> \ 1 --from-literal=password=<password> \ 2 --from-file=.gitconfig=.gitconfig \ --from-file=client.crt=/var/run/secrets/openshift.io/source/client.crt \ --from-file=cacert.crt=/var/run/secrets/openshift.io/source/cacert.crt \ --from-file=client.key=/var/run/secrets/openshift.io/source/client.key
パスワードを再度入力しないでいいように、ビルド内に S2I イメージを指定するようにしてください。ただし、リポジトリーをクローンできない場合には、ビルドをプロモートするためにユーザー名とパスワードを指定する必要があります。
8.3.4.2.5. Basic 認証
Basic 認証では、SCM サーバーに対して認証する場合に --username
と --password
の組み合わせ、または token
が必要です。
secret
を先に作成してから、プライベートリポジトリーにアクセスするためのユーザー名とパスワードを使用してください。
$ oc create secret generic <secret_name> \ --from-literal=username=<user_name> \ --from-literal=password=<password> \ --type=kubernetes.io/basic-auth
トークンで Basic 認証のシークレットを作成するには、以下を実行します。
$ oc create secret generic <secret_name> \ --from-literal=password=<token> \ --type=kubernetes.io/basic-auth
8.3.4.2.6. SSH キー認証
SSH キーベースの認証では、プライベート SSH キーが必要です。
リポジトリーのキーは通常 $HOME/.ssh/ ディレクトリーにあり、デフォルトで id_dsa.pub
、id_ecdsa.pub
、id_ed25519.pub
または id_rsa.pub
という名前が付けられています。以下のコマンドで、SSH キーの認証情報を生成します。
$ ssh-keygen -t rsa -C "your_email@example.com"
SSH キーのパスフレーズを作成すると、OpenShift Container Platform でビルドができなくなります。パスフレーズを求めるプロンプトが出されても、ブランクのままにします。
パブリックキーと、それに対応するプライベートキーのファイルが 2 つ作成されます (id_dsa
、id_ecdsa
、id_ed25519
または id_rsa
のいずれか)。これらが両方設定されたら、パブリックキーのアップロード方法についてソースコントロール管理 (SCM) システムのマニュアルを参照してください。プライベートキーは、プライベートリポジトリーにアクセスするために使用されます。
SSHキーを使用してプライベートリポジトリーにアクセスする前に、シークレットを作成します。
$ oc create secret generic <secret_name> \ --from-file=ssh-privatekey=<path/to/ssh/private/key> \ --type=kubernetes.io/ssh-auth
8.3.4.2.7. 信頼された証明局
git clone
の操作時に信頼される TLS 認証局のセットは OpenShift Container Platform インフラストラクチャーイメージにビルドされます。Git サーバーが自己署名の証明書を使用するか、イメージで信頼されていない認証局により署名された証明書を使用する場合には、その証明書が含まれるシークレットを作成するか、TLS 検証を無効にしてください。
CA 証明書
のシークレットを作成した場合に、OpenShift Container Platform はその証明書を使用して、git clone
操作時に Git サーバーにアクセスします。存在する TLS 証明書をどれでも受け入れてしまう Git の SSL 検証の無効化に比べ、この方法を使用するとセキュリティーが高くなります。
以下のプロセスの 1 つを完了します。
CA 証明書ファイルでシークレットを作成する (推奨)
CA が中間証明局を使用する場合には、ca.crt ファイルにすべての CA の証明書を統合します。以下のコマンドを実行してください。
$ cat intermediateCA.crt intermediateCA.crt rootCA.crt > ca.crt
シークレットを作成します。
$ oc create secret generic mycert --from-file=ca.crt=</path/to/file> 1
- 1
- 鍵の名前には ca.crt を使用する必要があります。
git TLS 検証を無効にします。
ビルド設定の適切なストラテジーセクションで
GIT_SSL_NO_VERIFY
環境変数をtrue
に設定します。BuildConfig
環境変数を管理するには、oc set env
コマンドを使用できます。
8.3.4.2.8. 組み合わせ
ここでは、特定のニーズに対応するために上記の方法を組み合わせてソースクローンのシークレットを作成する方法についての例を紹介します。
.gitconfig ファイルで SSH ベースの認証シークレットを作成するには、以下を実行します。
$ oc create secret generic <secret_name> \ --from-file=ssh-privatekey=<path/to/ssh/private/key> \ --from-file=<path/to/.gitconfig> \ --type=kubernetes.io/ssh-auth
.gitconfig ファイルと CA 証明書を組み合わせてシークレットを作成するには、以下を実行します。
$ oc create secret generic <secret_name> \ --from-file=ca.crt=<path/to/certificate> \ --from-file=<path/to/.gitconfig>
CA 証明書ファイルで Basic 認証のシークレットを作成するには、以下を実行します。
$ oc create secret generic <secret_name> \ --from-literal=username=<user_name> \ --from-literal=password=<password> \ --from-file=ca-cert=</path/to/file> \ --type=kubernetes.io/basic-auth
.gitconfig ファイルで Basic 認証のシークレットを作成するには、以下を実行します。
$ oc create secret generic <secret_name> \ --from-literal=username=<user_name> \ --from-literal=password=<password> \ --from-file=</path/to/.gitconfig> \ --type=kubernetes.io/basic-auth
.gitconfig ファイルと CA 証明書ファイルを合わせて Basic 認証シークレットを作成するには、以下を実行します。
$ oc create secret generic <secret_name> \ --from-literal=username=<user_name> \ --from-literal=password=<password> \ --from-file=</path/to/.gitconfig> \ --from-file=ca-cert=</path/to/file> \ --type=kubernetes.io/basic-auth
8.3.5. バイナリー (ローカル) ソース
ローカルのファイルシステムからビルダーにコンテンツをストリーミングする方法は、Binary
タイプのビルドと呼ばれています。このビルドに対する BuildConfig.spec.source.type
の対応の値は Binary
です。
このソースタイプは、oc start-build
の使用方法に基づき使用される点で独特です。
バイナリータイプのビルドでは、ローカルファイルシステムからコンテンツをストリーミングする必要があります。そのため、バイナリーファイルが提供されないので、バイナリータイプのビルドを自動的にトリガーすること (例: イメージの変更トリガーなど) はできません。同様に、Web コンソールからバイナリータイプのビルドを起動できません。
バイナリービルドを使用するには、以下のオプションのいずれかを指定して oc start-build
を呼び出します。
-
--from-file
: 指定したファイルのコンテンツはバイナリーストリームとしてビルダーに送信されます。ファイルに URL を指定することもできます。次に、ビルダーはそのデータをビルドコンテキストの上に、同じ名前のファイルに保存します。 -
--from-dir
および--from-repo
: コンテンツはアーカイブされて、バイナリーストリームとしてバイナリーに送信され、ビルダーはビルドコンテキストディレクトリー内にアーカイブのコンテンツを展開します。--from-dir
を使用すると、展開するアーカイブの URL を指定することも可能です。 -
--from-archive
: 指定したアーカイブはビルダーに送信され、ビルドコンテキストディレクトリーに展開されます。このオプションは--from-dir
と同様に動作しますが、このオプションの引数がディレクトリーの場合には常に、まずアーカイブがホストに作成されます。
上記のそれぞれの例では、以下のようになります。
-
BuildConfig
にBinary
のソースタイプが定義されている場合には、これは事実上無視され、クライアントが送信する内容に置き換えられます。 -
BuildConfig
にGit
のソースタイプが定義されている場合には、Binary
とGit
は併用できないので、動的に無効にされます。この場合、ビルダーに渡されるバイナリーストリームのデータが優先されます。
ファイル名ではなく、HTTP または HTTPS スキーマを使用する URL を --from-file
や --from-archive
に渡すことができます。--from-file
で URL を指定すると、ビルダーイメージのファイル名は Web サーバーが送信する Content-Disposition
ヘッダーか、ヘッダーがない場合には URL パスの最後のコンポーネントによって決定されます。認証形式はどれもサポートされておらず、カスタムのTLS 証明書を使用したり、証明書の検証を無効にしたりできません。
oc new-build --binary=true
を使用すると、バイナリービルドに関連する制約が実施されるようになります。作成される BuildConfig
のソースタイプは Binary
になります。つまり、この BuildConfig
のビルドを実行するための唯一の有効な方法は、--from
オプションのいずれかを指定して oc start-build
を使用し、必須のバイナリーデータを提供する方法になります。
dockerfile
および contextDir
のソースオプションは、バイナリービルドに関して特別な意味を持ちます。
dockerfile
はバイナリービルドソースと合わせて使用できます。dockerfile
を使用し、バイナリーストリームがアーカイブの場合には、そのコンテンツはアーカイブにある Dockerfile の代わりとして機能します。dockerfile
が --from-file
の引数と合わせて使用されている場合には、ファイルの引数は dockerfile
となり、dockerfile
の値はバイナリーストリームの値に置き換わります。
バイナリーストリームが展開されたアーカイブのコンテンツをカプセル化する場合には、contextDir
フィールドの値はアーカイブ内のサブディレクトリーと見なされます。有効な場合には、ビルド前にビルダーがサブディレクトリーに切り替わります。
8.3.6. 入力シークレット
シナリオによっては、ビルド操作で、依存するリソースにアクセスするための認証情報が必要になる場合がありますが、この認証情報がビルドが生成する最終的なアプリケーションイメージで利用可能になるのは適切ではありません。この目的の場合は、入力シークレット を定義することができます。
たとえば、Node.js アプリケーションのビルド時に、Node.js モジュールのプライベートミラーを設定できます。プライベートミラーからモジュールをダウンロードするには、URL、ユーザー名、パスワードを含む、ビルド用の .npmrc のカスタムファイルを提供する必要があります。セキュリティーの理由上、アプリケーションイメージで認証情報を公開しないようにしてください。
以下の例は Node.js について説明していますが、/etc/ssl/certs ディレクトリー、API キーまたはトークン、ラインセンスファイルなどに SSL 証明書を追加する場合に同じアプローチを使用できます。
8.3.6.1. 入力シークレットの追加
既存の BuildConfig
に入力シークレットを追加するには、以下を行います。
シークレットがない場合は作成します。
$ oc create secret generic secret-npmrc \ --from-file=.npmrc=<path/to/.npmrc>
これにより、secret-npmrc という名前の新しいシークレットが作成されます。これには、~/.npmrc ファイルの base64 でエンコードされたコンテンツが含まれます。
既存の
BuildConfig
のsource
セクションにシークレットを追加します。source: git: uri: https://github.com/openshift/nodejs-ex.git secrets: - secret: name: secret-npmrc
新しい BuildConfig
にシークレットを追加するには、以下のコマンドを実行します。
$ oc new-build \ openshift/nodejs-010-centos7~https://github.com/openshift/nodejs-ex.git \ --build-secret secret-npmrc
ビルド時に、.npmrc ファイルはソースコードが配置されているディレクトリーにコピーされます。OpenShift Container Platform の S2I ビルダーイメージでは、これはイメージの作業ディレクトリーで、Dockerfile の WORKDIR
の指示を使用して設定されます。別のディレクトリーを指定するには、シークレットの定義に destinationDir
を追加します。
source: git: uri: https://github.com/openshift/nodejs-ex.git secrets: - secret: name: secret-npmrc destinationDir: /etc
新規の BuildConfig
を作成時に、宛先のディレクトリーを指定することも可能です。
$ oc new-build \ openshift/nodejs-010-centos7~https://github.com/openshift/nodejs-ex.git \ --build-secret “secret-npmrc:/etc”
いずれの場合も、.npmrc ファイルがビルド環境の /etc ディレクトリーに追加されます。「Docker ストラテジー」の場合は、宛先のディレクトリーは相対パスでなければならない点に注意してください。
8.3.6.2. Source-to-Image ストラテジー
Source
ストラテジーを使用すると、定義された入力シークレットはすべて、適切な destinationDir
にコピーされます。destinationDir
を空にすると、シークレットはビルダーイメージの作業ディレクトリーに配置されます。
destinationDir
が相対バスの場合に同じルールが使用されます。シークレットは、イメージの作業ディレクトリーに対する相対的なパスに配置されます。destinationDir
が存在しない場合には、エラーが発生します。コピーのプロセス時にディレクトリーのパスは作成されません。
現在、これらのシークレットが指定されたファイルには全ユーザーに書き込み権限が割り当てられており (0666
のパーミッション)、assemble スクリプトの実行後には、サイズが 0 になるように切り捨てられます。つまり、シークレットファイルは作成されたイメージ内に存在はしますが、セキュリティーの関係上、空になります。
8.3.6.3. Docker ストラテジー
Docker
ストラテジーを使用すると、Dockerfile で ADD
および COPY
の命令 を使用してコンテナーイメージに定義されたすべての入力シークレットを追加できます。
シークレットの destinationDir
を指定しない場合は、ファイルは、Dockerfile が配置されているのと同じディレクトリーにコピーされます。相対パスを destinationDir
として指定する場合は、シークレットは、Dockerfile と相対的なディレクトリーにコピーされます。これにより、ビルド時に使用するコンテキストディレクトリーの一部として、Docker ビルド操作でシークレットファイルが利用できるようになります。
例8.1 シークレットデータを参照する Dockerfile の例
FROM centos/ruby-22-centos7 USER root ADD ./secret-dir /secrets COPY ./secret2 / # Create a shell script that will output secrets when the image is run RUN echo '#!/bin/sh' > /secret_report.sh RUN echo '(test -f /secrets/secret1 && echo -n "secret1=" && cat /secrets/secret1)' >> /secret_report.sh RUN echo '(test -f /secret2 && echo -n "relative-secret2=" && cat /secret2)' >> /secret_report.sh RUN chmod 755 /secret_report.sh CMD ["/bin/sh", "-c", "/secret_report.sh"]
通常はシークレットがイメージから実行するコンテナーに存在しないように、入力シークレットを最終的なアプリケーションイメージから削除する必要がありますが、シークレットは、追加した階層にあるイメージ自体に存在し続けます。Dockerfile 自体で、削除を行う必要があります。
8.3.6.4. カスタムストラテジー
Custom
ストラテジーを使用する場合、定義された入力シークレットはすべて、/var/run/secrets/openshift.io/build ディレクトリー内のビルダーコンテナーで入手できます。カスタムのビルドイメージは、これらのシークレットを適切に使用する必要があります。また、Custom
ストラテジーを使用すると、カスタムストラテジーのオプション で記載されているようにシークレットを定義できます。
既存のストラテジーのシークレットと入力シークレットには技術的な違いはありませんが、ビルダーイメージはそれぞれのシークレットを区別し、ビルドのユースケースに基づいて、異なる方法で使用する場合があります。
入力シークレットは常に /var/run/secrets/openshift.io/build ディレクトリーにマウントされます。そうでない場合には、ビルダーが完全なビルドオブジェクトを含む $BUILD
環境変数を分析できます。
8.3.7. 外部アーティファクトの使用
ソースリポジトリーにバイナリーファイルを保存することは推奨していません。そのため、ビルドプロセス中に追加のファイル (Java .jar の依存関係など) をプルするビルドを定義する必要がある場合があります。この方法は、使用するビルドストラテジーにより異なります。
Source
ビルドストラテジーの場合は、assemble スクリプトに、適切なシェルコマンドを設定する必要があります。
.s2i/bin/assemble ファイル
#!/bin/sh APP_VERSION=1.0 wget http://repository.example.com/app/app-$APP_VERSION.jar -O app.jar
.s2i/bin/run ファイル
#!/bin/sh exec java -jar app.jar
Source ビルドが使用する assemble および run スクリプトを制御する方法に関する情報は、「ビルダーイメージスクリプトの上書き」を参照してください。
Docker
ビルドストラテジーの場合は、Dockerfile を変更して、RUN
命令 を指定してシェルコマンドを呼び出す必要があります。
Dockerfile の抜粋
FROM jboss/base-jdk:8 ENV APP_VERSION 1.0 RUN wget http://repository.example.com/app/app-$APP_VERSION.jar -O app.jar EXPOSE 8080 CMD [ "java", "-jar", "app.jar" ]
実際には、ファイルの場所の環境変数を使用し、Dockerfile または assemble スクリプトを更新するのではなく、BuildConfig
で定義した環境変数で、ダウンロードする固有ファイルをカスタマイズすることができます。
環境変数の定義には複数の方法があり、いずれかの方法を選択できます。
- .s2i/environment ファイルの使用 (ソースビルドストラテジーのみ)
-
BuildConfig
での設定 -
「
oc start-build --env
を使用した明示的な指定」 (手動でトリガーされるビルドのみ)
8.3.8. プライベートレジストリーでの Docker 認証情報の使用
プライベートの Docker レジストリーの有効な認証情報を指定して、.docker/config.json ファイルでビルドを提供できます。これにより、プライベートの Docker レジストリーにアウトプットイメージをプッシュしたり、認証を必要とするプライベートの Docker レジストリーからビルダーイメージをプルすることができます。
OpenShift Container Platform Docker レジストリーでは、OpenShift Container Platform が自動的にシークレットを生成するので、この作業は必要ありません。
デフォルトでは、.docker/config.json ファイルはホームディレクトリーにあり、以下の形式となっています。
auths: https://index.docker.io/v1/: 1 auth: "YWRfbGzhcGU6R2labnRib21ifTE=" 2 email: "user@example.com" 3
このファイルに複数の Docker レジストリーを定義できます。または docker login
コマンドを実行して、このファイルに認証エントリーを追加することも可能です。ファイルが存在しない場合には作成されます。
Kubernetes では Secret
オブジェクトが提供され、これを使用して設定とパスワードを保存することができます。
ローカルの .docker/config.json ファイルからシークレットを作成します。
$ oc create secret generic dockerhub \ --from-file=.dockerconfigjson=<path/to/.docker/config.json> \ --type=kubernetes.io/dockerconfigjson
このコマンドにより、
dockerhub
という名前のシークレットの JSON 仕様が生成され、オブジェクトが作成されます。シークレットが作成されたら、これをビルダーサービスアカウントに追加します。ビルドは
builder
ロールで実行されるので、以下のコマンドでシークレットへのアクセスを設定する必要があります。$ oc secrets link builder dockerhub
pushSecret
フィールドをBuildConfig
のoutput
セクションに追加し、作成したsecret
の名前 (上記の例では、dockerhub
) に設定します。spec: output: to: kind: "DockerImage" name: "private.registry.com/org/private-image:latest" pushSecret: name: "dockerhub"
oc set build-secret
コマンドを使用して、ビルド設定にプッシュするシークレットを設定します。$ oc set build-secret --push bc/sample-build dockerhub
ビルドストラテジー定義に含まれる
pullSecret
を指定して、プライベートの Docker レジストリーからビルダーコンテナーイメージをプルします。strategy: sourceStrategy: from: kind: "DockerImage" name: "docker.io/user/private_repository" pullSecret: name: "dockerhub"
oc set build-secret
コマンドを使用して、ビルド設定にプルするシークレットを設定します。$ oc set build-secret --pull bc/sample-build dockerhub
以下の例では、ソールビルドに pullSecret
を使用しますが、Docker とカスタムビルドにも該当します。
8.4. ビルド出力
8.4.1. ビルド出力の概要
Docker
または Source
ストラテジーを使用するビルドにより、新しいコンテナーイメージが作成されます。このイメージは、Build
仕様の output
セクションで指定されているコンテナーイメージのレジストリーにプッシュされます。
出力の種類が ImageStreamTag
の場合は、イメージが統合された OpenShift Container Platform レジストリーにプッシュされ、指定のイメージストリームにタグ付けされます。出力が DockerImage
タイプの場合は、出力参照の名前が Docker のプッシュ仕様として仕様されます。この仕様にレジストリーが含まれる場合もありますが、レジストリーが指定されていない場合は、DockerHub にデフォルト設定されます。ビルド仕様の出力セクションが空の場合には、ビルドの最後にイメージはプッシュされません。
ImageStreamTag への出力
spec: output: to: kind: "ImageStreamTag" name: "sample-image:latest"
Docker のプッシュ仕様への出力
spec: output: to: kind: "DockerImage" name: "my-registry.mycompany.com:5000/myimages/myimage:tag"
8.4.2. アウトプットイメージの環境変数
Docker
および Source
ストラテジービルドは、以下の環境変数をアウトプットイメージに設定します。
変数 | 説明 |
---|---|
|
ビルドの名前 |
|
ビルドの namespace |
|
ビルドのソース URL |
|
ビルドで使用する git 参照 |
|
ビルドで使用するソースコミット |
さらに、Source
または Docker
ストラテジーオプションで設定されるユーザー定義の環境変数は、アウトプットイメージの環境変数一覧にも含まれます。
8.4.3. アウトプットイメージのラベル
Docker
および Source
ビルドは、以下のラベルをアウトプットイメージに設定します。
ラベル | 説明 |
---|---|
|
ビルドで使用するソースコミットの作者 |
|
ビルドで使用するソースコミットの日付 |
|
ビルドで使用するソースコミットのハッシュ |
|
ビルドで使用するソースコミットのメッセージ |
|
ソースに指定するブランチまたは参照 |
|
ビルドのソース URL |
BuildConfig.spec.output.imageLabels
フィールドを使用して、カスタムラベルの一覧を指定することも可能です。このラベルは、BuildConfig
の各イメージビルドに適用されます。
ビルドイメージに適用されるカスタムラベル
spec: output: to: kind: "ImageStreamTag" name: "my-image:latest" imageLabels: - name: "vendor" value: "MyCompany" - name: "authoritative-source-url" value: "registry.mycompany.com"
8.4.4. アウトプットイメージのダイジェスト
ビルドイメージは、ダイジェスト で一意に識別して、後に現在のタグとは無関係にこれを使用して ダイジェスト別にイメージをプル することができます。
Docker
および Source
ビルドは、イメージがレジストリーにプッシュされた後に Build.status.output.to.imageDigest
にダイジェストを保存します。このダイジェストはレジストリーで処理されるので、レジストリーがダイジェストを返さない場合や、ビルダーイメージで形式が認識されない場合など、存在しないことがあります。
レジストリーへのプッシュに成功した後のビルドイメージのダイジェスト
status: output: to: imageDigest: sha256:29f5d56d12684887bdfa50dcd29fc31eea4aaf4ad3bec43daf19026a7ce69912
8.4.5. プライベートレジストリーでの Docker 認証情報の使用
シークレットを使用して認証情報を指定することで、プライベートの Docker レジストリーにイメージをプッシュすることができます。方法については、「ビルド入力」を参照してください。
8.5. ビルドストラテジーのオプション
8.5.1. Source-to-Image ストラテジーのオプション
以下は、「S2I ビルドストラテジー」に固有のオプションです。
8.5.1.1. 強制プル
ビルド設定で指定したビルドイメージがノードでローカルに利用できる場合には、デフォルトではそのイメージが使用されます。ただし、ローカルイメージを上書きして、イメージストリームが参照するレジストリーからイメージを更新する場合には、forcePull
フラグを true に設定して BuildConfig
を作成します。
strategy: sourceStrategy: from: kind: "ImageStreamTag" name: "builder-image:latest" 1 forcePull: true 2
8.5.1.2. 増分ビルド
S2I は増分ビルドを実行できるので、以前にビルドされたイメージからのアーティファクトが再利用されます。増分ビルドを作成するには、ストラテジー定義に以下の変更を加えて、BuildConfig
を作成します。
strategy: sourceStrategy: from: kind: "ImageStreamTag" name: "incremental-image:latest" 1 incremental: true 2
増分ビルドをサポートするビルダーイメージを作成する方法に関する説明は、「S2I 要件」を参照してください。
8.5.1.3. ビルダーイメージのスクリプトの上書き
ビルダーイメージが提供する assemble、run および save-artifacts の「S2I スクリプト」は、以下 2 種類のいずれかの方法で上書きできます。
- アプリケーションのソースリポジトリーの .s2i/bin ディレクトリーに assemble, run および/または save-artifacts スクリプトを指定します。
- 以下のように、ストラテジー定義の一部として、スクリプトを含むディレクトリーの URL を指定します。
strategy:
sourceStrategy:
from:
kind: "ImageStreamTag"
name: "builder-image:latest"
scripts: "http://somehost.com/scripts_directory" 1
- 1
- このパスに、run, assemble および save-artifacts が追加されます。一部または全スクリプトがある場合、そのスクリプトが、イメージに指定された同じ名前のスクリプトの代わりに使用されます。
scripts
URL に配置されているファイルは、ソースリポジトリーの .s2i/bin に配置されているファイルよりも優先されます。S2I スクリプトがどのように使用されるかについては、「S2I 要件」のトピックおよび S2I ドキュメント を参照してください。
8.5.1.4. 環境変数
「ソースビルド」のプロセスと作成されるイメージで環境変数を利用できるようにする方法は 2 種類 (環境ファイル および BuildConfig 環境 の値) あります。指定の変数は、ビルドプロセス中と、アウトプットイメージに表示されます。
8.5.1.4.1. 環境ファイル
ソースビルドでは、ソースリポジトリーの .s2i/environment ファイルに指定することで、アプリケーション内に環境の値 (1 行に 1 つ) を設定できます。このファイルで指定された環境変数は、ビルドプロセスとアウトプットイメージに存在します。サポートされる環境変数の完全な一覧は、各イメージの「ドキュメント」にあります。
ソースリポジトリーに .s2i/environment ファイルを渡すと、S2I はビルド時にこのファイルを読み取ります。これにより assemble スクリプトがこれらの変数を使用できるので、ビルドの動作をカスタマイズできます。
たとえば、Rails アプリケーションのアセットのコンパイルを無効にする場合には、.s2i/environment ファイルに DISABLE_ASSET_COMPILATION=true
を追加して、ビルド時にアセットのコンパイルがスキップされるようにします。
ビルド以外に、指定の環境変数も実行中のアプリケーション自体で利用できます。たとえば、.s2i/environment ファイルに RAILS_ENV=development
を追加して、Rails アプリケーションが production
ではなく development
モードで起動できるようにします。
8.5.1.4.2. BuildConfig 環境
環境変数を BuildConfig
の sourceStrategy
定義に追加できます。ここに定義されている環境変数は、assemble スクリプトの実行時に表示され、アウトプットイメージで定義されるので、run スクリプトやアプリケーションコードでも利用できるようになります。
Rails アプリケーションのアセットコンパイルを無効にする例:
sourceStrategy: ... env: - name: "DISABLE_ASSET_COMPILATION" value: "true"
ビルド環境 のセクションには、詳細な説明があります。
oc set env
コマンドで、BuildConfig
に定義した環境変数を管理することも可能です。
8.5.1.5. Web コンソールを使用したシークレットの追加
プライベートリポジトリーにアクセスできるようにビルド設定にシークレットを追加するには、以下を実行します。
- 新規の OpenShift Container Platform プロジェクトを作成します。
- プライベートのソースコードリポジトリーにアクセスするための認証情報が含まれる シークレットを作成 します。
- 「Source-to-Image (S2I) ビルド設定」を作成します。
-
ビルド設定のエディターページや、「web コンソール」の fromimage ページの
create app from builder image
ページで ソースシークレット を設定します。 - Save ボタンをクリックします。
8.5.1.5.1. プルおよびプッシュの有効化
プライベートレジストリーにプルできるようにするには、ビルド設定に Pull Secret
を設定し、プッシュを有効にするには Push Secret
を設定します。
8.5.1.6. ソースファイルの無視
Source to image は .s2iignore
ファイルをサポートします。このファイルには、無視すべきファイルパターンの一覧が含まれます。.s2iignore
ファイルにあるパターンと一致する、さまざまな 入力ソース で提供されているように、ビルドの作業ディレクトリーにあるファイルは assemble
スクリプトでは利用できません。
.s2iignore
ファイル形式に関する詳細は、source-to-image ドキュメント を参照してください。
8.5.2. Docker ストラテジーのオプション
以下は、「Docker ビルドストラテジー」に固有のオプションです。
8.5.2.1. FROM イメージ
Dockerfile の FROM
命令は、BuildConfig
の from
に置き換えられます。
strategy: dockerStrategy: from: kind: "ImageStreamTag" name: "debian:latest"
8.5.2.2. Dockerfile パス
デフォルトでは Docker ビルドは BuildConfig.spec.source.contextDir
フィールドで指定されたコンテキストのルートに配置されている Dockerfile (名前付きの Dockerfile) を使用します。
dockerfilePath
フィールドでは、異なるパスを使用して Dockerfile の場所 (BuildConfig.spec.source.contextDir
フィールドへの相対パス) を特定します。デフォルトの Dockerfile (例: MyDockerfile) とは異なる名前や、サブディレクトリーにある Dockerfile へのパス (例: dockerfiles/app1/Dockerfile) などを単純に設定できます。
strategy: dockerStrategy: dockerfilePath: dockerfiles/app1/Dockerfile
8.5.2.3. キャッシュなし
Docker ビルドは通常、ビルドを実行するホスト上のキャッシュ階層を再利用します。noCache
オプションを true に設定すると、ビルドがキャッシュ階層を無視して、Dockerfile のすべての手順を再実行します。
strategy: dockerStrategy: noCache: true
8.5.2.4. 強制プル
ビルド設定で指定したビルドイメージがノードでローカルに利用できる場合には、デフォルトではそのイメージが使用されます。ただし、ローカルイメージを上書きして、イメージストリームが参照するレジストリーからイメージを更新する場合には、forcePull
フラグを true に設定して BuildConfig
を作成します。
strategy:
dockerStrategy:
forcePull: true 1
- 1
- このフラグがあると、ローカルのビルダーイメージが無視され、イメージストリームが参照するレジストリーから新しいバージョンがプルされます。
forcePull
を false に設定すると、デフォルトの動作として、ローカルに保存されたイメージが使用されます。
8.5.2.5. 環境変数
「Docker ビルド」 ロセスと作成されたイメージで環境変数を利用できるようにするには、BuildConfig
の dockerStrategy
の定義に環境変数を追加します。
ここに定義した環境変数は、Dockerfile 内で後に参照できるように、単一の ENV
Dockerfile 命令として FROM
命令の直後に挿入されます。
変数はビルド時に定義され、アウトプットイメージに残るため、そのイメージを実行するコンテナーにも存在します。
たとえば、ビルドやランタイム時にカスタムの HTTP プロキシーを定義するには以下を設定します。
dockerStrategy: ... env: - name: "HTTP_PROXY" value: "http://myproxy.net:5187/"
クラスター管理者は、「Ansible を使用したグローバルなビルド設定」を実行できます。
oc set env
コマンドで、BuildConfig
に定義した環境変数を管理することも可能です。
8.5.2.6. Web コンソールを使用したシークレットの追加
プライベートリポジトリーにアクセスできるように、ビルド設定にシークレットを追加するには、以下を実行します。
- 新規の OpenShift Container Platform プロジェクトを作成します。
- プライベートのソースコードリポジトリーにアクセスするための認証情報が含まれる シークレットを作成 します。
- 「docker のビルド設定」を作成します。
- ビルド設定のエディターページまたは、「web コンソール」の fromimage ページで、ソースシークレット を設定します。
- Save ボタンをクリックします。
8.5.2.7. Docker ビルド引数
Docker ビルドの引数 を設定するには、以下のように BuildArgs
配列にエントリーを追加します。これは、BuildConfig
の dockerStrategy
定義の中にあります。
dockerStrategy: ... buildArgs: - name: "foo" value: "bar"
ビルドの引数は、ビルドが開始された時点で Docker に渡されます。
8.5.2.7.1. プルおよびプッシュの有効化
プライベートレジストリーにプルできるようにするには、ビルド設定に Pull Secret
を設定し、プッシュを有効にするには Push Secret
を設定します。
8.5.3. カスタムストラテジーのオプション
以下は、「カスタムビルドストラテジー」に固有のオプションです。
8.5.3.1. FROM イメージ
customStrategy.from
セクションを使用して、カスタムビルドに使用するイメージを指定します。
strategy: customStrategy: from: kind: "DockerImage" name: "openshift/sti-image-builder"
8.5.3.2. Docker ソケットの公開
コンテナー内から Docker コマンドを実行して、コンテナーイメージをビルドできるようにするには、アクセス可能なソケットにビルドコンテナーをバインドする必要があります。これには、exposeDockerSocket
オプションを true に設定します。
strategy: customStrategy: exposeDockerSocket: true
8.5.3.3. シークレット
source と images の secrets に加え、カスタムストラテジーを使用すると、任意のシークレット一覧をビルダー pod に追加できます。
各シークレットは、特定の場所にマウントできます。
strategy: customStrategy: secrets: - secretSource: 1 name: "secret1" mountPath: "/tmp/secret1" 2 - secretSource: name: "secret2" mountPath: "/tmp/secret2"
8.5.3.3.1. Web コンソールを使用したシークレットの追加
プライベートリポジトリーにアクセスできるようにビルド設定にシークレットを追加するには、以下を実行します。
- 新規の OpenShift Container Platform プロジェクトを作成します。
- プライベートのソースコードリポジトリーにアクセスするための認証情報が含まれる シークレットを作成 します。
- 「docker のビルド設定」を作成します。
- ビルド設定のエディターページまたは、「web コンソール」の fromimage ページで、ソースシークレット を設定します。
- Save ボタンをクリックします。
8.5.3.3.2. プルおよびプッシュの有効化
プライベートレジストリーにプルできるようにするには、ビルド設定に Pull Secret
を設定し、プッシュを有効にするには Push Secret
を設定します。
8.5.3.4. 強制プル
ビルド Pod を設定する場合に、ビルドコントローラーはデフォルトで、ビルド設定で指定したイメージがローカルで使用できるかどうかを確認します。ローカルで利用できる場合にはそのイメージが使用されます。ただし、ローカルイメージを上書きして、イメージストリームが参照するレジストリーからイメージを更新する場合には、forcePull
フラグを true に設定して BuildConfig
を作成します。
strategy:
customStrategy:
forcePull: true 1
- 1
- このフラグがあると、ローカルのビルダーイメージが無視され、イメージストリームが参照するレジストリーから新しいバージョンがプルされます。
forcePull
を false に設定すると、デフォルトの動作として、ローカルに保存されたイメージが使用されます。
8.5.3.5. 環境変数
「カスタムビルド」のプロセスで環境変数を利用できるようにするには、環境変数を BuildConfig
の customStrategy
定義に追加します。
ここに定義された環境変数は、カスタムビルドを実行する Pod に渡されます。
たとえば、ビルド時にカスタムの HTTP プロキシーを定義するには以下を設定します。
customStrategy: ... env: - name: "HTTP_PROXY" value: "http://myproxy.net:5187/"
クラスター管理者は、「Ansible を使用したグローバルなビルド設定」を実行できます。
oc set env
コマンドで、BuildConfig
に定義した環境変数を管理することも可能です。
8.5.4. Pipeline ストラテジーのオプション
以下は、「Pipeline ビルドストラテジー」に固有のオプションです。
8.5.4.1. Jenkinsfile の提供
Jenkinsfile は、以下の 2 つの方法のどちらかで提供できます。
- ビルド設定に Jenkinsfile を埋め込む
- Jenkinsfile を含む git リポジトリーへの参照をビルド設定に追加する
埋め込み定義
kind: "BuildConfig" apiVersion: "v1" metadata: name: "sample-pipeline" spec: strategy: jenkinsPipelineStrategy: jenkinsfile: |- node('agent') { stage 'build' openshiftBuild(buildConfig: 'ruby-sample-build', showBuildLogs: 'true') stage 'deploy' openshiftDeploy(deploymentConfig: 'frontend') }
git リポジトリーへの参照
kind: "BuildConfig"
apiVersion: "v1"
metadata:
name: "sample-pipeline"
spec:
source:
git:
uri: "https://github.com/openshift/ruby-hello-world"
strategy:
jenkinsPipelineStrategy:
jenkinsfilePath: some/repo/dir/filename 1
- 1
- オプションの
jenkinsfilePath
フィールドは、ソースcontextDir
との関連で使用するファイルの名前を指定します。contextDir
が省略される場合、デフォルトはリポジトリーの root に設定されます。jenkinsfilePath
が省略される場合、デフォルトは Jenkinsfile に設定されます。
8.5.4.2. 環境変数
「Pipeline ビルド」のプロセスで環境変数を利用できるようにするには、環境変数を BuildConfig
の jenkinsPipelineStrategy
定義に追加します。
定義した後に、環境変数は BuildConfig
に関連する Jenkins ジョブのパラメーターとして設定されます。
以下に例を示します。
jenkinsPipelineStrategy: ... env: - name: "FOO" value: "BAR"
oc set env
コマンドで、BuildConfig
に定義した環境変数を管理することも可能です。
8.5.4.2.1. BuildConfig 環境変数と Jenkins ジョブパラメーター間のマッピング
Pipeline ストラテジーの BuildConfig
への変更に従い、Jenkins ジョブが作成/更新されると、BuildConfig
の環境変数は Jenkins ジョブパラメーターの定義にマッピングされます。Jenkins ジョブパラメーター定義のデフォルト値は、関連する環境変数の現在の値になります。
Jenkins ジョブの初回作成後に、パラメーターを Jenkins コンソールからジョブに追加できます。パラメーター名は、BuildConfig
の環境変数名とは異なります。上記の Jenkins ジョブ用にビルドを開始すると、これらのパラメーターが使用されます。
Jenkins ジョブのビルドを開始する方法により、パラメーターの設定方法が決まります。oc start-build
で開始された場合には、BuildConfig
の環境変数が対応するジョブインスタンスに設定するパラメーターになります。Jenkins コンソールからパラメーターのデフォルト値に変更を加えても無視され、BuildConfig
の値が優先されます。
oc start-build -e
で開始すると、-e
オプションで指定した環境変数の値が優先されます。また、BuildConfig
に記載されていない環境変数を指定した場合には、Jenkins ジョブのパラメーター定義として追加されます。また、Jenkins コンソールから環境変数に対応するパラメーターに対して変更を加えても無視され、BuildConfig
と oc start-build -e
で指定した値が優先されます。
Jenkins コンソールで Jenkins ジョブを開始した場合には、ジョブのビルドを開始する操作の一環として、Jenkins コンソールを使用してパラメーターの設定を制御できます。
8.6. ビルド環境
8.6.1. 概要
Pod 環境と同様に、ビルドの環境変数は、Downward API を使用して他のリソース/変数に対する参照として定義できますが、以下に記載の例外があります。
oc set env
コマンドで、BuildConfig
に定義した環境変数を管理することも可能です。
8.6.2. 環境変数としてのビルドフィールドの使用
ビルドオブジェクトの情報は、値を取得するフィールドの JsonPath
に、fieldPath
環境変数のソースを設定することで挿入できます。
env: - name: FIELDREF_ENV valueFrom: fieldRef: fieldPath: metadata.name
Jenkins Pipeline ストラテジーは、環境変数の valueFrom
構文をサポートしません。
8.6.3. 環境変数としてのコンテナーリソースの使用
参照はコンテナーの作成前に解決されるため、ビルド環境変数の valueFrom
を使用したコンテナーリソースの参照はサポートされません。
8.6.4. 環境変数としてのシークレットの使用
valueFrom
構文を使用して、シークレットからの鍵の値を環境変数として利用できます。
apiVersion: v1 kind: BuildConfig metadata: name: secret-example-bc spec: strategy: sourceStrategy: env: - name: MYVAL valueFrom: secretKeyRef: key: myval name: mysecret
8.7. ビルドのトリガー
8.7.1. ビルドトリガーの概要
BuildConfig
の定義時に、BuildConfig
を実行する必要のある状況を制御するトリガーを定義できます。以下のビルドトリガーを利用できます。
8.7.2. Webhook のトリガー
Webhook のトリガーにより、要求を OpenShift Container Platform API エンドポイントに送信して新規ビルドをトリガーできます。GitHub、GitLab、Bitbucket または Generic webhook を使用して、Webhook トリガーを定義できます。
OpenShift Container Platform の webhook は現在、Git ベースのソースコード管理システム (SCM) のそれぞれのプッシュイベントに似たイベントタイプのみサポートしており、その他のイベントタイプは無視されます。
プッシュイベントを処理する場合に、イベント内のブランチ参照が、対応の BuildConfig
のブランチ参照と一致しているかどうか確認されます。一致する場合には、webhook イベントに記載されているのと全く同じコミット参照が、OpenShift Container Platform ビルド用にチェックアウトされます。一致しない場合には、ビルドはトリガーされません。
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: c2VjcmV0dmFsdWUx
8.7.2.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 は以下のような構成です。
http://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/github
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 & Services から 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.7.2.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 は以下のような構成です。
http://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/gitlab
GitLab Webhook を設定するには以下を実行します。
ビルド設定を記述して、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.7.2.3. Bitbucket Webhook
Bitbucket webhook リポジトリーの更新時の Bitbucket による呼び出しを処理します。これまでのトリガーと同様に、secret
を指定する必要があります。以下の例は、BuildConfig
内のトリガー定義の YAML です。
type: "Bitbucket" bitbucket: secretReference: name: "mysecret"
oc describe
コマンドは、ペイロード URL を Bitbucket Webhook URL として返します (「Webhook URL の表示 参照)。ペイロード URL は以下のような構成です。
http://<openshift_api_host:port>/oapi/v1/namespaces/<namespace>/buildconfigs/<name>/webhooks/<secret>/bitbucket
Bitbucket Webhook を設定するには以下を実行します。
ビルド設定を記述して、webhook URL を取得します。
$ oc describe bc <name>
-
webhook URL をコピーします。
<secret>
はシークレットの値に置き換えます。 - Follow the 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.7.2.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 を指定します。
http://<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 verb は 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.7.2.5. Webhook URL の表示
以下のコマンドを使用して、ビルド設定に関連する webhook URL を表示します。
$ oc describe bc <name>
上記のコマンドで webhook URL が表示されない場合には、対象のビルド設定に webhook トリガーが定義されていないことになります。トリガーの設定 を参照して、トリガーを手動で追加してください。
8.7.3. イメージ変更のトリガー
イメージ変更のトリガーを使用すると、アップストリームで新規バージョンが利用できるようになるとビルドが自動的に呼び出されます。たとえば、RHEL イメージ上にビルドが設定されている場合には、RHEL のイメージが変更された時点でビルドの実行をトリガーできます。その結果、アプリケーションイメージは常に最新の RHEL ベースイメージ上で実行されるようになります。
イメージ変更のトリガーを設定するには、以下のアクションを実行する必要があります。
トリガーするアップストリームイメージを参照するように、
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>"
これにより、トリガーされたビルドは、リポジトリーにプッシュされたばかりの新しいイメージを使用して、ビルドが同じインプットでいつでも再実行できるようにします。
カスタムビルドの場合、すべての Strategy
タイプにイメージフィールドを設定するだけでなく、OPENSHIFT_CUSTOM_BUILD_BASE_IMAGE
の環境変数もチェックされます。この環境変数が存在しない場合は、不変のイメージ参照で作成されます。存在する場合には、この不変のイメージ参照で更新されます。
ビルドが webhook トリガーまたは手動の要求でトリガーされた場合に、作成されるビルドは、Strategy
が参照する ImageStream
から解決する <immutableid>
を使用します。これにより、簡単に再現できるように、一貫性のあるイメージタグを使用してビルドが実行されるようになります。
v1 Docker レジストリー のコンテナーイメージを参照するイメージストリームは、「イメージストリームタグ」が利用できるようになった時点でビルドが 1 度だけトリガーされ、後続のイメージ更新ではトリガーされません。これは、v1 Docker レジストリーに一意で識別可能なイメージがないためです。
8.7.4. 設定変更のトリガー
設定変更のトリガーは、BuildConfig
がされると同時に自動的にビルドが呼び出されます。以下の例は、BuildConfig
内のトリガー定義の YAML です。
type: "ConfigChange"
設定変更のトリガーは新しい BuildConfig
が作成された場合のみ機能します。今後のリリースでは、設定変更トリガーは、BuildConfig
が更新されるたびにビルドを起動できるようになります。
8.7.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
のヘルプドキュメントを参照してください。
8.8. ビルドフック
8.8.1. ビルドフックの概要
ビルドフックを使用すると、ビルドプロセスに動作を挿入できます。
BuildConfig
オブジェクトの postCommit
フィールドにより、ビルドアウトプットイメージを実行する一時的なコンテナー内でコマンドが実行します。イメージの最後の層がコミットされた直後、かつイメージがレジストリーにプッシュされる前に、フックが実行されます。
現在の作業ディレクトリーは、イメージの WORKDIR
に設定され、コンテナーイメージのデフォルトの作業ディレクトリーになります。多くのイメージでは、ここにソースコードが配置されます。
ゼロ以外の終了コードが返された場合、一時コンテナーの起動に失敗した場合には、フックが失敗します。フックが失敗すると、ビルドに失敗とマークされ、このイメージはレジストリーにプッシュされません。失敗の理由は、ビルドログを参照して検証できます。
ビルドフックは、ビルドが完了とマークされ、イメージがレジストリーに公開される前に、単体テストを実行してイメージを検証するために使用できます。すべてのテストに合格し、テストランナーにより終了コード 0 が返されると、ビルドは成功とマークされます。テストに失敗すると、ビルドは失敗とマークされます。すべての場合で、ビルドログには、テストランナーの出力が含まれるので、失敗したテストを特定するのに使用できます。
postCommit
フックは、テストの実行だけでなく、他のコマンドにも使用できます。一時的なコンテナーで実行されるので、フックによる変更は永続されず、フックの実行は最終的なイメージには影響がありません。この動作はさまざまな用途がありますが、テストの依存関係をインストールして使用でき、この依存関係は自動的に破棄されるので、最終イメージには残りません。
8.8.2. コミット後のビルドフックの設定
ビルド後のフックを設定する方法は複数あります。以下の例に出てくるすべての形式は同等で、bundle exec rake test --verbose
を実行します。
シェルスクリプト:
postCommit: script: "bundle exec rake test --verbose"
script
の値は、/bin/sh -ic
で実行するシェルスクリプトです。上記のように単体テストを実行する場合など、シェルスクリプトがビルドフックの実行に適している場合に、これを使用します。イメージのエントリーポイントを制御するか、イメージに/bin/sh
がない場合に、command
and/orargs
を使用します。注記CentOS や RHEL イメージでの作業を改善するために、追加で
-i
フラッグが導入されましたが、今後のリリースで削除される可能性があります。イメージエントリーポイントとしてのコマンド:
postCommit: command: ["/bin/bash", "-c", "bundle exec rake test --verbose"]
この形式では
command
は、実行するコマンドで、Dockerfile 参照 に記載されている、実行形式のイメージエントリーポイントを上書きします。Command は、イメージに/bin/sh
がない、またはシェルを使用しない場合に必要です。他の場合は、script
を使用するほうが便利でしょう。デフォルトのエントリーポイントに渡す引数:
postCommit: args: ["bundle", "exec", "rake", "test", "--verbose"]
この形式では、
args
はイメージのデフォルトエントリーポイントに渡される引数一覧です。イメージのエントリーポイントは、引数を処理できる必要があります。引数を指定したシェルスクリプト:
postCommit: script: "bundle exec rake test $1" args: ["--verbose"]
引数を渡す必要があるが、シェルスクリプトで正しく引用するのが困難な場合に、この形式を使用します。上記の
script
では、$0
は "/bin/sh" で、$1
、$2
などはargs
の位置引数となります。引数のあるコマンド:
postCommit: command: ["bundle", "exec", "rake", "test"] args: ["--verbose"]
この形式は
command
に引数を追加するのと同じです。
script
と command
を同時に指定すると、無効なビルドフックが作成されてしまいます。
8.8.2.1. CLI の使用
oc set build-hook
コマンドを使用して、ビルド設定のビルドフックを設定することができます。
コミット後のビルドフックとしてコマンドを設定します。
$ oc set build-hook bc/mybc \ --post-commit \ --command \ -- bundle exec rake test --verbose
コミット後のビルドフックとしてスクリプトを設定します。
$ oc set build-hook bc/mybc --post-commit --script="bundle exec rake test --verbose"
8.9. ビルド実行ポリシー
8.9.1. ビルド実行ポリシーの概要
ビルド実行ポリシーでは、ビルド設定から作成されるビルドを実行する順番を記述します。これには、Build
の spec
セクションにある runPolicy
フィールドの値を変更してください。
既存のビルド設定の runPolicy
値を変更することも可能です。
-
Parallel
からSerial
やSerialLatestOnly
に変更して、この設定から新規ビルドをトリガーすると、新しいビルドは並列ビルドすべてが完了するまで待機します。これは、順次ビルドは、一度に 1 つしか実行できないためです。 -
Serial
をSerialLatestOnly
に変更して、新規ビルドをトリガーすると、現在実行中のビルドと直近で作成されたビルド以外には、キューにある既存のビルドがすべてキャンセルされます。最新のビルドが次に実行されます。
8.9.2. 順次実行ポリシー
runPolicy
フィールドを Serial
に設定すると、Build
ビルドから作成される新しいビルドはすべて 順次実行になります。つまり、1 度に実行されるビルドは 1 つだけで、新しいビルドは、前のビルドが完了するまで待機します。このポリシーを使用すると、一貫性があり、予測可能なビルドが出力されます。これは、デフォルトの runPolicy
です。
Serial
ポリシーで sample-build 設定から 3 つのビルドをトリガーすると以下のようになります。
NAME TYPE FROM STATUS STARTED DURATION sample-build-1 Source Git@e79d887 Running 13 seconds ago 13s sample-build-2 Source Git New sample-build-3 Source Git New
sample-build-1 ビルドが完了すると、sample-build-2 ビルドが実行されます。
NAME TYPE FROM STATUS STARTED DURATION sample-build-1 Source Git@e79d887 Completed 43 seconds ago 34s sample-build-2 Source Git@1aa381b Running 2 seconds ago 2s sample-build-3 Source Git New
8.9.3. SerialLatestOnly 実行ポリシー
runPolicy
フィールドを SerialLatestOnly
に設定すると、Serial
実行ポリシーと同様に、Build
設定から作成される新規ビルドすべてが順次実行されます。相違点は、現在実行中のビルドの完了後に、実行される次のビルドが作成される最新ビルドになるという点です。言い換えると、キューに入っているビルドはスキップされるので、これらの実行を待機しないということです。スキップされたビルドは Cancelled としてマークされます。このポリシーは、反復的な開発を迅速に行う場合に使用できます。
SerialLatestOnly
ポリシーで sample-build 設定から 3 つのビルドをトリガーすると以下のようになります。
NAME TYPE FROM STATUS STARTED DURATION sample-build-1 Source Git@e79d887 Running 13 seconds ago 13s sample-build-2 Source Git Cancelled sample-build-3 Source Git New
sample-build-2 のビルドはキャンセル (スキップ) され、sample-build-1 の完了後に、sample-build-3 ビルドが次のビルドとして実行されます。
NAME TYPE FROM STATUS STARTED DURATION sample-build-1 Source Git@e79d887 Completed 43 seconds ago 34s sample-build-2 Source Git Cancelled sample-build-3 Source Git@1aa381b Running 2 seconds ago 2s
8.9.4. 並列実行ポリシー
runPolicy
フィールドを Parallel
に設定すると、Build
設定から作成される新規ビルドはすべて並列で実行されます。この設定では、最初に作成されるビルドが完了するのが最後になる可能性があり、最新のイメージで生成され、プッシュされたコンテナーイメージが先に完了してしまい、置き換わる可能性があるので、結果が予想できません。
ビルドの完了する順番が問題とはならない場合には、並列実行ポリシーを使用してください。
Parallel
ポリシーで sample-build 設定から 3 つのビルドをトリガーすると、3 つのビルドが同時に実行されます。
NAME TYPE FROM STATUS STARTED DURATION sample-build-1 Source Git@e79d887 Running 13 seconds ago 13s sample-build-2 Source Git@a76d881 Running 15 seconds ago 3s sample-build-3 Source Git@689d111 Running 17 seconds ago 3s
完了する順番は保証されません。
NAME TYPE FROM STATUS STARTED DURATION sample-build-1 Source Git@e79d887 Running 13 seconds ago 13s sample-build-2 Source Git@a76d881 Running 15 seconds ago 3s sample-build-3 Source Git@689d111 Completed 17 seconds ago 5s
8.10. 高度なビルド操作
8.10.1. ビルドリソースの設定
デフォルトでは、ビルドは、メモリーや CPU など、バインドされていないリソースを使用して Pod により完了されます。プロジェクトのデフォルトのコンテナー制限に、リソースの制限を指定すると、これらのリソースを制限できます。
ビルド設定の一部にリソース制限を指定して、リソースの使用を制限することも可能です。以下の例では、resources
、cpu
および memory
の各パラメーターはオプションです。
apiVersion: "v1" kind: "BuildConfig" metadata: name: "sample-build" spec: resources: limits: cpu: "100m" 1 memory: "256Mi" 2
ただし、「クォータ」がプロジェクトに定義されている場合には、以下の 2 つの項目のいずれかが必要です。
適用されない場合は、クォータ基準を満たさないために失敗したというメッセージが出され、ビルド Pod の作成は失敗します。
8.10.2. 最長期間の設定
BuildConfig
の定義時に、completionDeadlineSeconds
フィールドを設定して最長期間を定義できます。このフィールドは秒単位で指定し、デフォルトでは何も設定されていません。設定されていない場合は、最長期間は有効ではありません。
最長期間はビルドの Pod がシステムにスケジュールされた時点から計算され、ビルダーイメージをプルするのに必要な時間など、ジョブが有効である期間を定義します。指定したタイムアウトに達すると、ジョブは OpenShift Container Platform により終了されます。
以下の例は BuildConfig
の一部で、completionDeadlineSeconds
フィールドを 30 分に指定しています。
spec: completionDeadlineSeconds: 1800
この設定は、Pipeline ストラテジーオプションではサポートされていません。
8.10.3. 特定のノードへのビルドの割り当て
ビルドは、ビルド設定の nodeSelector
フィールドにラベルを指定して、特定のノード上で実行するようにターゲットを設定できます。nodeSelector
の値は、ビルド Pod のスケジュール時の node
ラベルに一致するキー/値のペアに指定してください。
apiVersion: "v1"
kind: "BuildConfig"
metadata:
name: "sample-build"
spec:
nodeSelector:1
key1: value1
key2: value2
- 1
- このビルド設定に関連するビルドは、
key1=value2
とkey2=value2
ラベルが指定されたノードでのみ実行されます。
nodeSelector
の値は、クラスター全体のデフォルトでも制御でき、値を上書きできます。ビルド設定で nodeSelector
キー/値ペアが定義されておらず、nodeSelector:{}
が明示的に空になるように定義されていない場合にのみ、デフォルト値が適用されます。値を上書きすると、キーごとにビルド設定の値が置き換えられます。
詳細情報は、「グローバルビルドのデフォルト設定および上書きの設定」を参照してください。
指定の NodeSelector
がこれらのラベルが指定されているノードに一致しない場合には、ビルドは Pending
の状態が無限に続きます。
8.10.4. チェーンビルド
コンパイル言語 (Go、C、C++、Java など) の場合には、アプリケーションイメージにコンパイルに必要な依存関係を追加すると、イメージのサイズが増加したり、悪用される可能性のある脆弱性が発生したりする可能性があります。
これらの問題を回避するには、2 つのビルドをチェーンでつなげることができます。1 つ目のビルドでコンパイルしたアーティファクトを作成し、2 つ目のビルドで、アーティファクトを実行する別のイメージにそのアーティファクトを配置します。「Source-to-Image」ビルドは「Docker」ビルドと組み合わせて、アーティファクトをコンパイルし、別のランタイムイメージに配置します。
この例では、Source-to-Image ビルドと Docker ビルドをチェーンでつないでいますが、1 つ目のビルドは、任意のアーティファクトを含むイメージを生成するストラテジーを使用し、2 つ目のビルドは、イメージからの入力コンテンツを使用可能なストラテジーを使用できます。
最初のビルドは、アプリケーションソースを取得して、WAR ファイルを含むイメージを作成します。このイメージは、artifact-image
イメージストリームにプッシュされます。アウトプットアーティファクトのパスは、使用する Source-to-Image ビルダーの assemble スクリプトにより異なります。この場合、/wildfly/standalone/deployments/ROOT.war に出力されます。
apiVersion: v1 kind: BuildConfig metadata: name: artifact-build spec: output: to: kind: ImageStreamTag name: artifact-image:latest source: git: uri: https://github.com/openshift/openshift-jee-sample.git type: Git strategy: sourceStrategy: from: kind: ImageStreamTag name: wildfly:10.1 namespace: openshift type: Source
2 つ目のビルドは、1 つ目のビルドからのアウトプットイメージ内にある WAR ファイルへのパスが指定されている「イメージソース」を使用します。インライン Dockerfile は、その WAR ファイルをランタイムイメージにコピーします。
apiVersion: v1 kind: BuildConfig metadata: name: image-build spec: output: to: kind: ImageStreamTag name: image-build:latest source: type: Dockerfile dockerfile: |- FROM jee-runtime:latest COPY ROOT.war /deployments/ROOT.war images: - from: 1 kind: ImageStreamTag name: artifact-image:latest paths: 2 - sourcePath: /wildfly/standalone/deployments/ROOT.war destinationDir: "." strategy: dockerStrategy: from: 3 kind: ImageStreamTag name: jee-runtime:latest type: Docker triggers: - imageChange: {} type: ImageChange
この設定の結果、2 番目のビルドのアウトプットイメージに、WAR ファイルの作成に必要なビルドツールを含める必要がなくなります。また、この 2 番目のビルドには「イメージ変更のトリガー」が含まれているので、1 番目のビルドがバイナリーアーティファクトで新規イメージを実行して作成するたびに、2 番目のビルドが自動的に、そのアーティファクトを含むランタイムイメージを生成するためにトリガーされます。そのため、どちらのビルドも、ステージが 2 つある単一ビルドのように振る舞います。
8.10.5. ビルドのプルーニング
デフォルトでは、ライフサイクルが完了したビルドは、無限に永続します。以下のビルド設定例にあるように、successfulBuildsHistoryLimit
または failedBuildsHistoryLimit
を正の整数に指定すると、以前のビルドを保持する数を制限することができます。
apiVersion: "v1" kind: "BuildConfig" metadata: name: "sample-build" spec: successfulBuildsHistoryLimit: 2 1 failedBuildsHistoryLimit: 2 2
ビルドプルーニングは、以下のアクションによりトリガーされます。
- ビルド設定が更新された場合
- ビルドのライフサイクルが完了した場合
ビルドは、作成時のタイムスタンプで分類され、一番古いビルドが先にプルーニングされます。
管理者は、「'oc adm' オブジェクトのプルーニングコマンド」を使用して、ビルドを手動でプルーニングできます。
8.11. ビルドのトラブルシューティング
8.11.1. 拒否されたリソースへのアクセス要求
- 問題
ビルドが以下のエラーで失敗します。
requested access to the resource is denied
- 解決策
プロジェクトに設定されている イメージのクォータ のいずれからの上限を超えています。現在のクォータを確認して、適用されている制限数と、使用中のストレージを確認してください。
$ oc describe quota