設定
第1章 Builds の設定
Build
カスタムリソース (CR) は、ソース、ビルドストラテジー、パラメーター値、出力、保持パラメーター、およびビルドを設定するボリュームを定義するのに役立ちます。Build
リソースは namespace 内で使用できます。
ビルドを設定するには、Build
リソース YAML ファイルを作成して OpenShift Container Platform クラスターに適用します。
1.1. build の設定可能なフィールド
Build
カスタムリソース (CR) では次のフィールドを使用できます。
フィールド | 存在 | 説明 |
---|---|---|
| 必須 |
リソースの API バージョンを指定します (例: |
| 必須 |
リソースのタイプを指定します (例: |
| 必須 |
カスタムリソース定義インスタンスを識別するメタデータ ( |
| 必須 | Git リポジトリーやソースバンドルイメージなど、ソースコードの場所を示します。 |
| 必須 |
|
| 必須 | 生成されたイメージがプッシュされる場所を示します。 |
| 必須 | コンテナーレジストリーにアクセスするための既存のシークレットを示します。 |
| 任意 | ビルドストラテジーで定義されたパラメーターの値を指定するための名前と値のリストを示します。 |
| 任意 |
カスタムタイムアウトを定義します。デフォルト値は 10 分です。このフィールドの値は、 |
| 任意 | 出力イメージにアノテーションを付けるために使用できるキーと値のペアのリストを示します。 |
| 任意 | 出力イメージのラベル付けに使用できるキーと値のペアのリストを示します。 |
| 任意 | ビルドコンテナーに渡すことができる追加の環境変数を定義します。使用可能な変数は、ビルドストラテジーで使用されるツールによって異なります。 |
| 任意 | 失敗したビルド実行が存在できる期間を指定します。 |
| 任意 | 成功したビルド実行が存続できる期間を指定します。 |
| 任意 | 失敗したビルド実行が存続できる数を指定します。 |
| 任意 | 成功したビルド実行が存続できる数を指定します。 |
1.2. ソース定義
次のフィールドの値を設定することで、Build
カスタムリソース (CR) でビルドのソース情報を設定できます。
-
source.git.url
: Git リポジトリーで利用可能なイメージのソースの場所を定義します。 -
source.git.cloneSecret
: プライベート Git リポジトリーの SSH 秘密鍵を含む namespace 内のシークレットを参照します。 -
source.git.revision
: ソース Git リポジトリーから選択する特定のリビジョンを定義します。たとえば、コミット、タグ、ブランチ名などです。このフィールドのデフォルトは、Git リポジトリーのデフォルトブランチです。 -
source.contextDir
: ルートフォルダーにソースコードが存在しないリポジトリーのコンテキストパスを指定します。
ビルドコントローラーは、イメージをプルするために指定した Git リポジトリーが存在するかどうかを自動検証しません。検証する必要がある場合は、次の例に示すように、build.shipwright.io/verify.repository
アノテーションの値を true
に設定します。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build annotations: build.shipwright.io/verify.repository: "true" spec: source: git: url: https://github.com/shipwright-io/sample-go contextDir: docker-build
ビルドコントローラーは、以下のシナリオで Git リポジトリーの存在を検証します。
- HTTP または HTTPS プロトコルでエンドポイント URL を使用する場合。
-
git@
などの SSH プロトコルを定義しているが、source.git.cloneSecret
などの参照シークレットを定義していない場合。
以下の例は、異なるソース入力セットでビルドを設定する方法を示しています。
例: 認証情報を使用したビルドの設定
次の例に示すように、認証情報を指定してソースを使用してビルドを設定できます。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-build spec: source: git: url: https://github.com/sclorg/nodejs-ex cloneSecret: source-repository-credentials
例: コンテキストパスを使用したビルドの設定
次の例に示すように、Git リポジトリー内のコンテキストパスを指定するソースを使用してビルドを設定できます。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-custom-context-dockerfile spec: source: git: url: https://github.com/userjohn/npm-simple contextDir: docker-build
例: タグを使用したビルドの設定
次の例に示すように、Git リポジトリーのタグ v.0.1.0
を指定するソースを使用してビルドを設定できます。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build spec: source: git: url: https://github.com/shipwright-io/sample-go revision: v0.1.0
例: 環境変数を使用したビルドの設定
次の例に示すように、環境変数を指定するビルドを設定することもできます。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build spec: source: git: url: https://github.com/shipwright-io/sample-go contextDir: docker-build env: - name: <example_var_1> value: "<example_value_1>" - name: <example_var_2> value: "<example_value_2>"
1.3. ストラテジー定義
Build
CR でビルドのストラテジーを設定できます。以下のビルドストラテジーを使用できます。
-
buildah
-
source-to-image
ビルドストラテジーを設定するには、次の例に示すように、Build
CR で spec.strategy.name
フィールドと spec.strategy.kind
フィールドを定義します。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-build spec: strategy: name: buildah kind: ClusterBuildStrategy
1.4. ビルドのパラメーター値の定義
Build
CR でビルドストラテジーパラメーターの値を指定できます。パラメーター値を指定することで、ビルドストラテジーのステップがどのように機能するかを制御できます。BuildRun
リソースの値を上書きすることもできます。
すべてのパラメーターに、値を直接指定するか、config map またはシークレットの参照キーを使用して指定する必要があります。
ビルドストラテジーのステップでパラメーターを使用すると、config map とシークレットの使用が制限されます。config map とシークレットは、パラメーターがコマンド、引数、または環境変数で使用されている場合にのみ使用できます。
Build
CR で paramValues
フィールドを使用する場合は、次のシナリオを避けてください。
-
BuildStrategy
CR で定義されているspec.parameters
の 1 つと一致しないspec.paramValues
名を指定する。 -
Shipwright 予約パラメーターと競合する
spec.paramValues
名を指定する。このようなパラメーターには、BUILDER_IMAGE
、CONTEXT_DIR
、およびshp-
で始まるすべての名前などが含まれます。
また、Build
CR の paramValues
フィールドを定義する前に、ストラテジーの内容を確認してください。
1.4.1. パラメーター値を定義する設定例
以下の例は、ビルドストラテジーでパラメーターを定義し、Build
CR を使用して、このようなパラメーターに値を割り当てる方法を示しています。Build
CR に含まれる array
タイプのパラメーターに値を割り当てることもできます。
例: ClusterBuildStrategy
CR でのパラメーターの定義
以下の例は、複数のパラメーターを定義する ClusterBuildStrategy
CR を示しています。
apiVersion: shipwright.io/v1beta1 kind: ClusterBuildStrategy metadata: name: buildah spec: parameters: - name: build-args description: "The values for the args in the Dockerfile. Values must be in the format KEY=VALUE." type: array defaults: [] # ... - name: storage-driver description: "The storage driver to use, such as 'overlay' or 'vfs'." type: string default: "vfs" # ... steps: # ...
例: Build
CR のパラメーターへの値の割り当て
上記の ClusterBuildStrategy
CR は storage-driver
パラメーターを定義しており、次の例に示すように、Build
CR で storage-driver
パラメーターの値を指定できます。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: <your_build> namespace: <your_namespace> spec: paramValues: - name: storage-driver value: "overlay" strategy: name: buildah kind: ClusterBuildStrategy output: # ...
例: パラメーターを一元的に制御する ConfigMap
CR の作成
storage-driver
パラメーターを複数のビルドに使用し、その使用法を一元的に制御する場合は、次の例に示すように、ConfigMap
CR を作成できます。
apiVersion: v1 kind: ConfigMap metadata: name: buildah-configuration namespace: <your_namespace> data: storage-driver: overlay
以下の例のように、作成された ConfigMap
CR を Build
CR のパラメーター値として使用できます。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: <your_build> namespace: <your_namespace> spec: paramValues: - name: storage-driver configMapValue: name: buildah-configuration key: storage-driver strategy: name: buildah kind: ClusterBuildStrategy output: # ...
例: Build
CR の array
型のパラメーターに値を割り当てる
array
型のパラメーターに値を代入できます。buildah
ストラテジーを使用する場合は、registries-search
パラメーターを定義して、特定のレジストリー内のイメージを検索できます。次の例は、registries-search
配列パラメーターに値を割り当てる方法を示しています。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: <your_build> namespace: <your_namespace> spec: paramValues: - name: storage-driver configMapValue: name: buildah-configuration key: storage-driver - name: registries-search values: - value: registry.redhat.io strategy: name: buildah kind: ClusterBuildStrategy output: # ...
例: Build
CR でのシークレットの参照
以下の例のように、registries-block
配列パラメーターのシークレットを参照できます。
apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
name: <your_build>
namespace: <your_namespace>
spec:
paramValues:
- name: storage-driver
configMapValue:
name: buildah-configuration
key: storage-driver
- name: registries-block
values:
- secretValue: 1
name: registry-configuration
key: reg-blocked
strategy:
name: buildah
kind: ClusterBuildStrategy
output:
# ...
- 1
- この値はシークレットを参照します。
1.5. Builder または Dockerfile の定義
Build
CR では、spec.paramValues
フィールドを使用して、出力イメージを構築するためのツールを含むイメージを指定できます。次の例では、Build
CR で Dockerfile
イメージを指定します。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-golang-build spec: source: git: url: https://github.com/shipwright-io/sample-go contextDir: docker-build strategy: name: buildah kind: ClusterBuildStrategy paramValues: - name: dockerfile value: Dockerfile
以下の例のように、Builder
イメージを Build
CR の source-to-image
ビルドストラテジーの一部として使用することもできます。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: s2i-nodejs-build spec: source: git: url: https://github.com/shipwright-io/sample-nodejs contextDir: source-build/ strategy: name: source-to-image kind: ClusterBuildStrategy paramValues: - name: builder-image value: docker.io/centos/nodejs-10-centos7
1.6. 出力定義
Build
CR では、イメージをプッシュする出力の場所を指定できます。出力場所として外部プライベートレジストリーを使用する場合は、イメージにアクセスするためのシークレットを指定する必要があります。出力イメージのアノテーションとラベルを指定することもできます。
アノテーションまたはラベルを指定すると、出力イメージが 2 回プッシュされます。最初のプッシュはビルドストラテジーから行われ、2 番目のプッシュではイメージ設定を変更してアノテーションとラベルを追加します。
以下の例では、イメージがプッシュされるパブリックレジストリーを定義します。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: s2i-nodejs-build spec: source: git: url: https://github.com/shipwright-io/sample-nodejs contextDir: source-build/ strategy: name: source-to-image kind: ClusterBuildStrategy paramValues: - name: builder-image value: docker.io/centos/nodejs-10-centos7 output: image: image-registry.openshift-image-registry.svc:5000/build-examples/nodejs-ex
以下の例では、イメージがプッシュされるプライベートレジストリーを定義します。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: s2i-nodejs-build spec: source: git: url: https://github.com/shipwright-io/sample-nodejs contextDir: source-build/ strategy: name: source-to-image kind: ClusterBuildStrategy paramValues: - name: builder-image value: docker.io/centos/nodejs-10-centos7 output: image: us.icr.io/source-to-image-build/nodejs-ex pushSecret: icr-knbuild
以下の例では、イメージのアノテーションおよびラベルを定義します。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: s2i-nodejs-build spec: source: git: url: https://github.com/shipwright-io/sample-nodejs contextDir: source-build/ strategy: name: source-to-image kind: ClusterBuildStrategy paramValues: - name: builder-image value: docker.io/centos/nodejs-10-centos7 output: image: us.icr.io/source-to-image-build/nodejs-ex pushSecret: icr-knbuild annotations: "org.opencontainers.image.source": "https://github.com/org/repo" "org.opencontainers.image.url": "https://my-company.com/images" labels: "maintainer": "team@my-company.com" "description": "This is my cool image"
1.7. ビルドの保持パラメーター定義
以下の目的で保持パラメーターを定義できます。
- 完了したビルド実行が存続できる期間を指定する
- ビルドに対して存在できる成功または失敗したビルド実行の数を指定する
保持パラメーターは、BuildRun
インスタンスまたはリソースを自動的にクリーンアップする方法を提供します。Build
CR では、以下の保持パラメーターの値を設定できます。
-
Retention.succeededLimit
: ビルドに対して存在できる、成功したビルド実行の数を定義します。 -
Retention.failedLimit
: ビルドに対して存在できる、失敗したビルド実行の数を定義します。 -
retention.ttlAfterFailed
: 失敗したビルド実行が存在できる期間を指定します。 -
Retention.ttlAfterSucceeded
: 成功したビルド実行が存在できる期間を指定します。
次の例は、Build
CR での保持パラメーターの使用方法を示しています。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: build-retention-ttl spec: source: git: url: "https://github.com/shipwright-io/sample-go" contextDir: docker-build strategy: kind: ClusterBuildStrategy name: buildah output: # ... retention: ttlAfterFailed: 30m ttlAfterSucceeded: 1h failedLimit: 10 succeededLimit: 20 # ...
Retention.failedLimit
および Retention.succeededLimit
パラメーターの値を変更すると、それらの変更がビルドに適用されるとすぐに、新しい制限が適用されます。ただし、retention.ttlAfterFailed
パラメーターと Retention.ttlAfterSucceeded
パラメーターの値を変更すると、新しい保持期間は新しいビルドの実行時にのみ適用されます。以前のビルド実行は、以前の保持期間に従います。BuildRun
および Build
CR の両方で保持期間を定義している場合は、BuildRun
CR で定義された保持期間が優先されます。
1.8. ビルドのボリューム定義
ボリュームは Build
CR で定義できます。定義されたボリュームは、BuildStrategy
リソースで指定されたボリュームをオーバーライドします。ボリュームがオーバーライドされていないと、ビルドの実行が失敗します。
次の例は、Build
CR の volumes
フィールドの使用法を示しています。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: <build_name> spec: source: git: url: https://github.com/example/url strategy: name: buildah kind: ClusterBuildStrategy paramValues: - name: dockerfile value: Dockerfile output: image: registry/namespace/image:latest volumes: - name: <your_volume_name> configMap: name: <your_configmap_name>
第2章 ビルドストラテジーの設定
BuildStrategy
または ClusterBuildStrategy
カスタムリソース (CR) は、ストラテジパラメーター、システムパラメーター、ステップリソース定義、アノテーション、ボリュームを定義してビルドストラテジーを設定するのに役立ちます。BuildStrategy
リソースは namespace 内で、ClusterBuildStrategy
リソースはクラスター全体で使用できます。
ビルドストラテジーを設定するには、BuildStrategy
または ClusterBuildStrategy
リソース YAML ファイルを作成し、OpenShift Container Platform クラスターに適用します。
2.1. ストラテジーパラメーターの定義
BuildStrategy
または ClusterBuildStrategy
カスタムリソース (CR) でストラテジーパラメーターを定義し、Build
または BuildRun
CR でそれらのパラメーターの値を設定または変更できます。ビルドストラテジーの作成時に、ビルド時にストラテジーのパラメーターを設定したり、変更したりすることも可能です。
ストラテジーのパラメーターを定義する前に、以下の点を考慮してください。
-
ビルドストラテジー CR の
spec.parameters
フィールドでパラメーターのリストを定義します。各リスト項目には、配列型の名前、説明、型、およびオプションのデフォルト値が含まれます。デフォルト値が設定されていない場合は、Build
またはBuildRun
CR で値を定義する必要があります。 -
ビルドストラテジーの
spec.steps
フィールドで、string または array 型のパラメーターを定義します。 $(params.your-parameter-name)
構文を使用して、文字列型のパラメーターを指定します。ストラテジーを参照するBuild
またはBuildRun
CR にyour-parameter-name
パラメーターの値を設定できます。必要に応じて、以下の文字列パラメーターを定義できます。表2.1 文字列パラメーター パラメーター 説明 image
このパラメーターを使用して、
golang:$(params.go-version)
などのカスタムタグを定義します。args
このパラメーターを使用して、データを builder コマンドに渡します。
env
このパラメーターを使用して、環境変数の値を指定します。
$(params.your-array-parameter-name[*])
構文を使用して、配列型のパラメーターを指定します。配列の指定後、引数またはコマンドで使用できます。配列内の各項目に、引数が設定されます。以下の例では、ビルドストラテジーのspec.steps
フィールドに array パラメーターを使用します。apiVersion: shipwright.io/v1beta1 kind: ClusterBuildStrategy metadata: name: <cluster_build_strategy_name> # ... spec: parameters: - name: tool-args description: Parameters for the tool type: array steps: - name: a-step command: - some-tool args: - --tool-args - $(params.tool-args[*])
-
パラメーター値を単純な文字列として、または config map またはシークレットのキーへの参照として指定します。パラメーターは、
spec.steps
フィールドのcommand
セクション、args
セクション、またはenv
セクションで定義されている場合にのみ、設定マップまたはシークレット値を使用します。
2.2. システムパラメーターの定義
ビルドストラテジーのステップを定義するときにシステムパラメーターを使用して、システム情報、または Build
または BuildRun
カスタムリソース (CR) 内のユーザー定義情報にアクセスできます。システムパラメーターは、build run controller によってランタイム時に定義されているため、設定または変更できません。
ビルドストラテジーの定義に以下のシステムパラメーターを定義できます。
パラメーター | 説明 |
---|---|
| ソースコードが含まれるディレクトリーへの絶対パスを示します。 |
|
ソースコードのコンテキストディレクトリーへの絶対パスを示します。 |
|
|
2.3. ステップリソースの定義
ビルドストラテジーのすべてのステップに対して CPU、メモリー、ディスク使用量に課せられる制限などのリソースの定義を含めることができます。ステップが複数あるストラテジーの場合、ステップによっては他のステップよりも多くのリソースが必要になる場合があります。ストラテジー管理者は、各ステップに最適なリソース値を定義できます。
たとえば、同じステップで異なる名前とステップリソースを含むストラテジーをクラスターにインストールできるため、ユーザーはより小さいまたはより大きいリソース要件でビルドを作成できます。
2.3.1. さまざまなリソースを使用したストラテジー
リソースに異なる制限を指定して、同じストラテジーの複数のタイプを定義します。次の例では、リソースに対して小および中程度の制限が定義された同じ buildah
ストラテジーを使用します。これらの例では、ストラテジー管理者がステップリソースの定義をより詳細に制御できるようになります。
2.3.1.1. 制限の少ないビルダーストラテジー
次の例に示すように、buildah
ストラテジーに制限の小さいリソースストラテジーを指定して spec.steps[].resources
フィールドを定義します。
例: 制限が小さい buildah
ストラテジー
apiVersion: shipwright.io/v1beta1 kind: ClusterBuildStrategy metadata: name: buildah-small spec: steps: - name: build-and-push image: quay.io/containers/buildah:v1.31.0 workingDir: $(params.shp-source-root) securityContext: capabilities: add: - "SETFCAP" command: - /bin/bash args: - -c - | set -euo pipefail # Parse parameters # ... # That's the separator between the shell script and its args - -- - --context - $(params.shp-source-context) - --dockerfile - $(build.dockerfile) - --image - $(params.shp-output-image) - --build-args - $(params.build-args[*]) - --registries-block - $(params.registries-block[*]) - --registries-insecure - $(params.registries-insecure[*]) - --registries-search - $(params.registries-search[*]) resources: limits: cpu: 250m memory: 65Mi requests: cpu: 250m memory: 65Mi parameters: - name: build-args description: "The values for the args in the Dockerfile. Values must be in the format KEY=VALUE." type: array defaults: [] # ...
2.3.1.2. 制限が中程度の Buildah ストラテジー
次の例に示すように、buildah
ストラテジーに制限が中程度のリソースストラテジーを指定して spec.steps[].resources
フィールドを定義します。
例: 制限が中程度の buildah
ストラテジー
apiVersion: shipwright.io/v1beta1 kind: ClusterBuildStrategy metadata: name: buildah-medium spec: steps: - name: build-and-push image: quay.io/containers/buildah:v1.31.0 workingDir: $(params.shp-source-root) securityContext: capabilities: add: - "SETFCAP" command: - /bin/bash args: - -c - | set -euo pipefail # Parse parameters # ... # That's the separator between the shell script and its args - -- - --context - $(params.shp-source-context) - --dockerfile - $(build.dockerfile) - --image - $(params.shp-output-image) - --build-args - $(params.build-args[*]) - --registries-block - $(params.registries-block[*]) - --registries-insecure - $(params.registries-insecure[*]) - --registries-search - $(params.registries-search[*]) resources: limits: cpu: 500m memory: 1Gi requests: cpu: 500m memory: 1Gi parameters: - name: build-args description: "The values for the args in the Dockerfile. Values must be in the format KEY=VALUE." type: array defaults: [] # ...
ストラテジーのリソース定義を設定した後、次の例に示すように、Build
CR でストラテジーを参照する必要があります。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: buildah-medium spec: source: git: url: https://github.com/shipwright-io/sample-go contextDir: docker-build strategy: name: buildah-medium kind: ClusterBuildStrategy # ...
2.3.2. Tekton パイプラインのリソース管理
ビルドコントローラーは Tekton パイプラインコントローラーと連携して、ストラテジー手順を実行する Pod をスケジュールできるようにします。実行時に、ビルドコントローラーは Tekton TaskRun
リソースを作成し、TaskRun
リソースは特定の namespace に新しい Pod を作成します。次に、この Pod はすべてのストラテジーステップを順番に実行してイメージを構築します。
2.4. アノテーション定義
他の Kubernetes オブジェクトと同様に、ビルドストラテジーまたはクラスタービルドストラテジーのアノテーションを定義できます。ビルドストラテジーは、まずアノテーションを TaskRun
リソースに伝播します。次に、Tekton がそのアノテーションを Pod に伝播します。
アノテーションは、以下の目的で使用できます。
-
Pod が使用できるネットワーク帯域幅を制限する。
kubernetes.io/ingress-bandwidth
およびkubernetes.io/egress-bandwidth
アノテーションが Kubernetes ネットワークトラフィックシェーピング機能で定義されています。 -
コンテナーの AppArmor プロファイルを定義する。
container.apparmor.security.beta.kubernetes.io/<container_name>
が使用されます。
以下の例では、ビルドストラテジーでのアノテーションの使用方法を示しています。
apiVersion: shipwright.io/v1beta1 kind: ClusterBuildStrategy metadata: name: <cluster_build_strategy_name> annotations: container.apparmor.security.beta.kubernetes.io/step-build-and-push: unconfined container.seccomp.security.alpha.kubernetes.io/step-build-and-push: unconfined spec: # ...
以下のアノテーションは伝播されません。
-
kubectl.kubernetes.io/last-applied-configuration
-
clusterbuildstrategy.shipwright.io/*
-
buildstrategy.shipwright.io/*
-
build.shipwright.io/*
-
buildrun.shipwright.io/*
ストラテジー管理者は、ポリシーエンジンを使用してアノテーションの使用をさらに制限できます。
2.5. 文字列パラメーターの安全な参照
文字列パラメーターは、BuildStrategy
または ClusterBuildStrategy
カスタムリソース (CR) で環境変数、引数、またはイメージを定義するときに使用されます。ビルドストラテジーのステップでは、$(params.your-parameter-name)
構文を使用して文字列パラメーターを参照できます。
ビルドストラテジーステップで $(params.your-parameter-name)
構文を使用して、システムパラメーターとストラテジーパラメーターを参照することもできます。
Pod では、すべての $(params.your-parameter-name)
変数が実際の文字列に置き換えられます。ただし、インラインスクリプトを使用して引数内の文字列パラメーターを参照する場合は注意が必要です。たとえば、スクリプトで定義された引数にパラメーター値を安全に渡すには、次のいずれかの方法を選択できます。
- 環境変数の使用
- 引数の使用
例: 文字列パラメーターの環境変数への参照
文字列パラメーターをスクリプト内で直接使用する代わりに、環境変数に渡すことができます。環境変数を引用符で囲むことにより、コマンドインジェクションの脆弱性を回避できます。このアプローチは、buildah
などのストラテジーに使用できます。以下の例では、スクリプト内の環境変数を使用して文字列パラメーターを参照します。
apiVersion: shipwright.io/v1beta1 kind: BuildStrategy metadata: name: sample-strategy spec: parameters: - name: sample-parameter description: A sample parameter type: string steps: - name: sample-step env: - name: PARAM_SAMPLE_PARAMETER value: $(params.sample-parameter) command: - /bin/bash args: - -c - | set -euo pipefail some-tool --sample-argument "${PARAM_SAMPLE_PARAMETER}"
例: 引数への文字列パラメーターの参照
文字列パラメーターをスクリプト内で定義した引数に渡すことができます。適切なシェル引用符を使用すると、コマンドインジェクションを回避できます。このアプローチは、buildah
などのストラテジーに使用できます。以下の例では、スクリプト内で定義した引数を使用して、文字列パラメーターを参照します。
apiVersion: shipwright.io/v1beta1 kind: BuildStrategy metadata: name: sample-strategy spec: parameters: - name: sample-parameter description: A sample parameter type: string steps: - name: sample-step command: - /bin/bash args: - -c - | set -euo pipefail SAMPLE_PARAMETER="$1" some-tool --sample-argument "${SAMPLE_PARAMETER}" - -- - $(params.sample-parameter)
2.6. システム結果の定義
ビルドストラテジーによって作成されたイメージのサイズとダイジェストを結果ファイルのセットに保存できます。BuildRun
リソースが失敗した場合のデバッグ用にエラーの詳細を保存することもできます。次の結果パラメーターを BuildStrategy
または ClusterBuildStrategy
CR に定義できます。
パラメーター | 説明 |
---|---|
| イメージのダイジェストを保存するファイルへのパスを示します。 |
| イメージの圧縮サイズを格納するファイルへのパスを示します。 |
| エラーの理由を格納するファイルへのパスを示します。 |
| エラーメッセージを格納するファイルへのパスを示します。 |
以下の例は、BuildRun
CR の .status.output
フィールドのイメージのサイズとダイジェストを示しています。
apiVersion: shipwright.io/v1beta1 kind: BuildRun # ... status: # ... output: digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53 size: 1989004 # ...
以下の例は、BuildRun
CR の .status.failureDetails
フィールドのエラーの理由とメッセージを示しています。
apiVersion: shipwright.io/v1beta1 kind: BuildRun # ... status: # ... failureDetails: location: container: step-source-default pod: baran-build-buildrun-gzmv5-b7wbf-pod-bbpqr message: The source repository does not exist, or you have insufficient permission to access it. reason: GitRemotePrivate
2.7. ボリュームとボリュームマウントの定義
ビルドストラテジーには、ボリュームとボリュームマウントの定義が含まれます。ビルドストラテジーで定義されたボリュームは、通常の volumeSource
タイプをすべてサポートします。ビルドのステップでは、ボリュームマウントを作成することでボリュームを参照します。
ビルドのステップで定義されたボリュームマウントを使用すると、BuildStrategy
、Build
、または BuildRun
リソースで定義されたボリュームにアクセスできるようになります。
ビルドストラテジーのボリュームでは、overridable
のブール型フラグが使用されます。このフラグは、デフォルトで false
に設定されます。Build
または BuildRun
リソースが、BuildStrategy
リソースで定義されたボリュームをオーバーライドしようとすると、overridable
フラグのデフォルト値が false
であるため失敗します。
次の例は、ボリューム
および volumeMounts
フィールドを定義する BuildStrategy
リソースを示しています。
apiVersion: shipwright.io/v1beta1 kind: BuildStrategy metadata: name: buildah spec: steps: - name: build image: quay.io/containers/buildah:v1.23.3 # ... volumeMounts: - name: varlibcontainers mountPath: /var/lib/containers volumes: - name: varlibcontainers overridable: true emptyDir: {}
第3章 ビルド実行の設定
BuildRun
カスタムリソース (CR) は、ビルド参照、ビルド仕様、パラメーター値、サービスアカウント、出力、保持パラメーター、およびボリュームを定義してビルド実行を設定するのに役立ちます。BuildRun
リソースは namespace 内で使用できます。
ビルド実行を設定するには、BuildRun
リソース YAML ファイルを作成して OpenShift Container Platform クラスターに適用します。
3.1. ビルド実行の設定可能なフィールド
BuildRun
カスタムリソース (CR) では次のフィールドを使用できます。
フィールド | 存在 | 説明 |
---|---|---|
| 必須 |
リソースの API バージョンを指定します。たとえば、 |
| 必須 |
リソースの型を指定します。たとえば、 |
| 必須 |
カスタムリソース定義インスタンスを識別するメタデータを示します。たとえば、 |
| 任意 |
使用する既存の |
| 任意 |
使用する組み込み |
| 任意 | イメージのビルド時に使用するサービスアカウントを示します。 |
| 任意 |
カスタムタイムアウトを定義します。このフィールドの値は、 |
| 任意 |
ビルドストラテジーで定義されたパラメーターの値を指定するための名前と値のリストを示します。パラメーター値は、 |
| 任意 |
生成されたイメージのプッシュ先のカスタムの場所を示します。このフィールドの値は、 |
| 任意 |
コンテナーレジストリーにアクセスするための既存のシークレットを示します。このシークレットは、 |
| 任意 |
ビルドコンテナーに渡すことができる追加の環境変数を定義します。このフィールド値は、 |
spec.build.name
フィールドと spec.build.spec
フィールドは相互排他的であるため、同じ CR 内で一緒に使用できません。
3.2. ビルド参照定義
BuildRun
リソースの spec.build.name
フィールドを設定して、ビルドするイメージを示す Build
リソースを参照できます。以下の例は、spec.build.name
フィールドを設定する BuildRun
CR を示しています。
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build
3.3. ビルド仕様の定義
spec.build.spec
フィールドを使用して、完全なビルド仕様を BuildRun
リソースに埋め込むことができます。仕様を埋め込むことで、専用の Build
カスタムリソースを作成および維持することなく、イメージをビルドできます。以下の例は、spec.build.spec
フィールドを設定する BuildRun
CR を示しています。
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: standalone-buildrun spec: build: spec: source: git: url: https://github.com/shipwright-io/sample-go.git contextDir: source-build strategy: kind: ClusterBuildStrategy name: buildah output: image: <path_to_image>
spec.build.name
フィールドと spec.build.spec
フィールドは相互排他的であるため、同じ CR 内で一緒に使用できません。
3.4. ビルド実行のパラメーター値定義
BuildRun
CR でビルドストラテジーパラメーターの値を指定できます。Build
リソースでも同じ名前で定義されているパラメーターの値を指定した場合は、BuildRun
リソースで定義されている値が優先されます。
次の例では、BuildRun
リソースの cache
パラメーターの値が、Build
リソースで定義されている cache
パラメーターの値をオーバーライドします。
apiVersion: shipwright.io/v1beta1 kind: Build metadata: name: <your_build> namespace: <your_namespace> spec: paramValues: - name: cache value: disabled strategy: name: <your_strategy> kind: ClusterBuildStrategy source: # ... output: # ...
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: <your_buildrun> namespace: <your_namespace> spec: build: name: <your_build> paramValues: - name: cache value: registry
3.5. サービスアカウント定義
BuildRun
リソースでサービスアカウントを定義できます。次の例に示すように、サービスアカウントは、Build
リソースで参照されるすべてのシークレットをホストします。
apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
name: buildah-buildrun
spec:
build:
name: buildah-build
serviceAccount: pipeline 1
- 1
spec.serviceAccount
フィールドの値を".generate"
に設定して、実行時にサービスアカウントを生成することもできます。生成されたサービスアカウントの名前は、BuildRun
リソースの名前に対応します。
サービスアカウントを定義せず、namespace に pipeline
サービスアカウントが存在する場合、BuildRun
リソースはそのアカウントを使用します。それ以外の場合、BuildRun
リソースは default
サービスアカウントを使用します。
3.6. ビルド実行の保持パラメーター定義
完了したビルド実行が BuildRun
リソース内に存在できる期間を指定できます。保持パラメーターは、BuildRun
インスタンスを自動的にクリーンアップする方法を提供します。BuildRun
CR で次の保持パラメーターの値を設定できます。
-
Retention.ttlAfterFailed
: 失敗したビルド実行が存在できる期間を指定します -
Retention.ttlAfterSucceeded
: 成功したビルド実行が存在できる期間を指定します。
次の例は、BuildRun
CR で保持パラメーターを定義する方法を示しています。
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buidrun-retention-ttl spec: build: name: build-retention-ttl retention: ttlAfterFailed: 10m ttlAfterSucceeded: 10m
BuildRun
と Build
CR の両方で保持パラメーターを定義した場合、BuildRun
CR で定義された値は、Build
CR で定義された保持パラメーターの値をオーバーライドします。
3.7. ビルド実行のボリューム定義
BuildRun
CR でボリュームを定義できます。定義されたボリュームは、BuildStrategy
リソースで指定されたボリュームをオーバーライドします。ボリュームがオーバーライドされていないと、ビルドの実行が失敗します。
Build
リソースと BuildRun
リソースが同じボリュームをオーバーライドすると、BuildRun
リソースに定義されているボリュームが使用されます。
次の例は、volumes
フィールドを使用する BuildRun
CR を示しています。
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: <buildrun_name> spec: build: name: <build_name> volumes: - name: <volume_name> configMap: name: <configmap_name>
3.8. 環境変数の定義
必要に応じて、BuildRun
CR で環境変数を使用できます。次の例は、環境変数を定義する方法を示しています。
例: 環境変数を使用した BuildRun
リソースの定義
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build env: - name: <example_var_1> value: "<example_value_1>" - name: <example_var_2> value: "<example_value_2>"
次の例は、Kubernetes downward API を使用して Pod を環境変数として公開する BuildRun
リソースを示しています。
例: Pod を環境変数として公開するための BuildRun
リソースの定義
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build env: - name: <pod_name> valueFrom: fieldRef: fieldPath: metadata.name
次の例は、Kubernetes Downward API を使用してコンテナーを環境変数として公開する BuildRun
リソースを示しています。
例: コンテナーを環境変数として公開するための BuildRun
リソースの定義
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: build: name: buildah-build env: - name: MEMORY_LIMIT valueFrom: resourceFieldRef: containerName: <my_container> resource: limits.memory
3.9. ビルド実行ステータス
次の例に示すように、イメージの構築ステータスが変化するたびに、BuildRun
リソースが更新されます。
例: ステータスが不明な BuildRun
$ oc get buildrun buildah-buildrun-mp99r NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME buildah-buildrun-mp99r Unknown Unknown 1s
例: ステータスが True の BuildRun
$ oc get buildrun buildah-buildrun-mp99r NAME SUCCEEDED REASON STARTTIME COMPLETIONTIME buildah-buildrun-mp99r True Succeeded 29m 20m
BuildRun
リソースは、status.conditions
フィールドにステータス関連の情報を保存します。たとえば、Succeeded
タイプの条件は、リソースが操作を正常に完了したことを示します。status.conditions
フィールドには、ステータス、理由、および BuildRun
リソースのメッセージなどの重要な情報が含まれます。
3.9.1. ビルド実行ステータスの説明
BuildRun
カスタムリソース (CR) は、イメージ構築プロセス中にステータスが異なる可能性があります。次の表は、ビルド実行のさまざまなステータスを示しています。
Status | 原因 | 説明 |
---|---|---|
|
|
|
|
|
|
|
| ユーザーがビルド実行のキャンセルを要求しました。この要求は build run controller をトリガーし、関連するタスクの実行をキャンセルするリクエストを作成します。このステータスが存在する場合、キャンセルはまだ処理中です。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 参照されたクラスタースコープのストラテジーがクラスター内に見つかりませんでした。 |
|
| 参照された namespace スコープのストラテジーがクラスター内に見つかりませんでした。 |
|
|
|
|
|
|
|
|
|
|
|
デフォルトのないビルドストラテジーで定義されている一部のパラメーターに値が指定されていません。 |
|
| システムパラメーターの値が指定されましたが、これは許可されません。 |
|
| ビルドストラテジーで定義されていないパラメーターの値が指定されました。 |
|
| ビルドストラテジーパラメーターに間違ったタイプの値が指定されました。たとえば、ビルドストラテジーでパラメーターが配列または文字列として定義されている場合は、それに応じて値のセットまたは直接値を指定する必要があります。 |
|
|
パラメーターの値に、 |
|
|
配列パラメーターの値内の項目に、 |
|
|
パラメーターの値に、 |
|
|
パラメーターの値に、 |
|
| 参照されたサービスアカウントがクラスター内に見つかりませんでした。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
定義された |
|
|
定義された |
|
| ビルド実行 Pod が、実行されていたノードからエビクトされました。 |
3.9.2. 失敗したビルドの実行
ビルドの実行が失敗した場合は、BuildRun
CR の status.failureDetails
フィールドをチェックして、Pod またはコンテナー内で失敗が発生した正確なポイントを特定できます。status.failureDetails
フィールドにはエラーメッセージと失敗の理由が含まれます。失敗のメッセージと理由がビルドストラテジーで定義されている場合にのみ表示されます。
次の例は、失敗したビルド実行を示しています。
# ... status: # ... failureDetails: location: container: step-source-default pod: baran-build-buildrun-gzmv5-b7wbf-pod-bbpqr message: The source repository does not exist, or you have insufficient permission to access it. reason: GitRemotePrivate
status.failureDetails
フィールドには、Git に関連するすべての操作のエラーの詳細も表示されます。
3.9.3. ステップ結果のビルド実行ステータス
BuildRun
リソースの実行が完了すると、.status
フィールドには、build run controller によって生成されたステップから出力された .status.taskResults
の結果が含まれます。結果には、イメージのビルドに使用されたイメージダイジェストまたはソースコードのコミット SHA が含まれます。BuildRun
リソースでは、.status.sources
フィールドにソースステップの実行の結果が、.status.output
フィールドに出力ステップの実行の結果が含まれます。
次の例は、Git ソースのステップ結果を含む BuildRun
リソースを示しています。
例: Git ソースのステップ結果を含む BuildRun
リソース
# ... status: buildSpec: # ... output: digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53 size: 1989004 sources: - name: default git: commitAuthor: xxx xxxxxx commitSha: f25822b85021d02059c9ac8a211ef3804ea8fdde branchName: main
次の例は、ローカルソースコードのステップ結果を含む BuildRun
リソースを示しています。
例: ローカルソースコードのステップ結果を含む BuildRun
リソース
# ... status: buildSpec: # ... output: digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53 size: 1989004 sources: - name: default bundle: digest: sha256:0f5e2070b534f9b880ed093a537626e3c7fdd28d5328a8d6df8d29cd3da760c7
出力イメージのダイジェストとサイズは、ビルドストラテジーで定義されている場合にのみ表示されます。
3.9.4. ビルドのスナップショット
既存のタスク実行が対象となるビルド実行に含まれている場合、ビルド実行を調整するたびに、BuildRun
リソースのステータスの buildSpec
フィールドが更新されます。
この更新中に、Build
リソースのスナップショットが生成され、BuildRun
リソースの status.buildSpec
フィールドに埋め込まれます。このため、buildSpec
フィールドには、特定のイメージのビルドを実行するために使用されていた元の Build
仕様の正確なコピーが含まれます。ビルドスナップショットを使用すると、元の Build
リソース設定を確認できます。
3.10. ビルド実行と Tekton タスクの関係
BuildRun
リソースは、イメージ構築のタスクを Tekton TaskRun
リソースに委任します。Tekton TaskRun リソースは、タスクが完了するかタスクでエラーが発生するまで、すべてのステップを実行します。
ビルド実行の調整中に、build run controller は新規の TaskRun
リソースを生成します。コントローラーは、TaskRun
リソースにビルド実行に必要なステップを組み込みます。埋め込みのステップは、ビルドストラテジーで定義されます。
3.11. ビルド実行のキャンセル
アクティブな BuildRun
インスタンスをキャンセルするには、その状態を BuildRunCanceled
に設定します。BuildRun
インスタンスをキャンセルすると、基になる TaskRun
リソースもキャンセル済みとしてマークされます。
次の例は、BuildRun
リソースのキャンセルされたビルド実行を示しています。
apiVersion: shipwright.io/v1beta1 kind: BuildRun metadata: name: buildah-buildrun spec: # [...] state: "BuildRunCanceled"
3.12. ビルド実行の自動削除
ビルド実行を自動的に削除するには、build
または buildrun
仕様に次の保持パラメーターを追加します。
buildrun
TTL パラメーター: ビルド実行が完了してから定義された期間のみ存在するようにします。-
buildrun.spec.retention.ttlAfterFailed
: 指定された時間が経過して、ビルド実行に失敗した場合、ビルド実行は削除されます。 -
buildrun.spec.retention.ttlAfterSucceeded
: 指定された時間が経過して、ビルド実行に成功した場合、ビルド実行は削除されます。
-
build
TTL パラメーター: ビルドのビルド実行が、完了してから定義された期間のみ存在するようにします。-
build.spec.retention.ttlAfterFailed
: 指定された時間が経過して、ビルドの実行が失敗した場合、ビルド実行は削除されます。 -
build.spec.retention.ttlAfterSucceeded
: 指定した時間が経過し、ビルドの実行が成功した場合、ビルドの実行が削除されます。
-
build
制限パラメーター: 1 つのビルドに対して、成功または失敗したビルド実行を限られた数だけ存在できるようにします。-
build.spec.retention.succeededLimit
: ビルドに対して存在できる、成功したビルド実行の数を定義します。 -
build.spec.retention.failedLimit
: ビルドに対して存在できる、失敗したビルド実行の数を定義します。
-
Legal Notice
Copyright © 2024 Red Hat, Inc.
OpenShift documentation is licensed under the Apache License 2.0 (https://www.apache.org/licenses/LICENSE-2.0).
Modified versions must remove all Red Hat trademarks.
Portions adapted from https://github.com/kubernetes-incubator/service-catalog/ with modifications by Red Hat.
Red Hat, Red Hat Enterprise Linux, the Red Hat logo, the Shadowman logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat Software Collections is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation’s permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.