設定

builds for Red Hat OpenShift 1.5

Builds の設定

概要

このドキュメントでは、Builds の設定に関する情報を提供します。

表1.1 Build CR の必須フィールド
フィールド	説明
`apiVersion`	リソースの API バージョンを指定します (例: `shipwright.io/v1beta1`)。
`kind`	リソースのタイプを指定します (例: `Build)`。
`metadata`	カスタムリソース定義インスタンスを識別するメタデータを指定します。たとえば、`ビルド` リソースの名前などです。
`spec.source`	ソースコードの場所を指定します。たとえば、Git リポジトリーやソースバンドルイメージなどです。
`spec.strategy`	`ビルド` リソースに使用されるストラテジーの名前とタイプを指定します。
`spec.output`	システムが生成されたイメージを保存する場所を指定します。
`spec.output.pushSecret`	コンテナーレジストリーへのアクセス権を取得するために使用する既存のシークレットを指定します。

表1.2 Build CR のオプションフィールド
フィールド	説明
`spec.paramValues`	ビルドストラテジーで定義されたパラメーターの値を設定するための名前と値のリストを指定します。
`spec.timeout`	カスタムタイムアウトを定義します。デフォルト値は 10 分です。このフィールドの値は、`BuildRun` リソースで上書きできます。
`spec.output.annotations`	出力イメージにアノテーションを付けるために使用できるキーと値のペアのリストを指定します。
`spec.output.labels`	出力イメージにラベルを付けるために使用できるキーと値のペアのリストを指定します。
`spec.env`	ビルドコンテナーに渡すことができる追加の環境変数を定義します。使用できる変数は、ビルドストラテジーで使用されるツールによって異なります。
`spec.retention.ttlAfterFailed`	失敗したビルド実行が存在できる期間を指定します。
`spec.retention.ttlAfterSucceeded`	成功したビルド実行が存続できる期間を指定します。
`spec.retention.failedLimit`	失敗したビルド実行が存続できる数を指定します。
`spec.retention.succeededLimit`	成功したビルド実行が存続できる数を指定します。
`spec.nodeSelector`	Builds を実行するノードを指定します。
`spec.tolerations`	Builds Pod の toleration を指定します。
`spec.schedulerName`	Builds Pod のスケジューラーを指定します。

retention.failedLimit および retention.succeededLimit パラメーターの値を変更すると、新しい制限がすぐに適用されます。ただし、retention.ttlAfterFailed パラメーターと retention.ttlAfterSucceeded パラメーターの値を変更すると、新しい保持期間は新しいビルドの実行時にのみ適用されます。以前のビルド実行は、以前の保持期間に従います。BuildRun と Build CR の両方で保持期間を定義している場合、BuildRun CR が優先されます。

1.8. ビルドのボリューム定義
リンクのコピー

BuildStrategy リソースで指定されたボリュームを上書きするには、Build カスタムリソース (CR) でボリュームを定義します。ボリュームが明示的に上書きされていない場合、ビルドの実行は失敗します。

次の例は、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: <volume_name>
      configMap:
        name: <configmap_name>

各項目の説明:

< ビルド名 >: ビルド の名前を指定します。
< ボリューム名 >: ボリューム名を指定します。
<configmap_name>: ConfigMap の名前を指定します。

1.9. Pod の設定
リンクのコピー

オプションの BuildRun カスタムリソース (CR) フィールドを使用して、ビルドの Pod のスケジューリングと配置を設定します。

ビルド Pod を設定するには、以下のオプションの ビルド CR フィールドを使用します。

spec.tolerations フィールドは、以下の制限で Builds Pod の toleration を指定します。
- NoSchedule テイント効果のみがサポートされます。
spec.nodeSelector フィールドは、Builds Pod を実行するノードを指定します。
spec.schedulerName フィールドは、Builds Pod のスケジューラーを指定します。

注記

これらのフィールドをビルド CR とビルドラン CR で定義した場合、ビルドランの値が優先されます。

第2章ビルドストラテジーの設定
リンクのコピー

プラットフォームエンジニアは、BuildStrategy または ClusterBuildStrategy カスタムリソース (CR) で、パラメーター、システム設定、リソース要件、アノテーション、ボリュームを指定することで、一貫性のあるビルドストラテジーを定義できます。これらのストラテジーにより、クラスター全体で制御された再利用可能なビルド実行が可能になります。

2.1. ストラテジーパラメーターの定義
リンクのコピー

BuildStrategy または ClusterBuildStrategy カスタムリソース (CR) でパラメーターを定義します。これらの値は、ビルド または ビルド実行 CR で設定または変更できます。

ストラテジーのパラメーターを定義する前に、以下の点を考慮してください。

ビルドストラテジー CR の spec.parameters フィールドでパラメーターのリストを定義します。各項目には、名前、説明、タイプ、およびオプションでデフォルト値 (配列型の場合は複数の値) が含まれます。デフォルト値が設定されていない場合は、Build または BuildRun CR で値を定義する必要があります。
ビルドストラテジーの spec.steps フィールドで、string または array 型のパラメーターを定義します。

$(params.your-parameter-name) 構文を使用して、文字列型のパラメーターを指定します。ストラテジーを参照する Build または BuildRun CR に your-parameter-name パラメーターの値を設定できます。必要に応じて、以下の文字列パラメーターを定義できます。

Expand

表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. システムパラメーターの定義
リンクのコピー

システムパラメーターを使用して、ビルドストラテジーの手順を定義し、システム情報、または ビルド または ビルド実行 カスタムリソース (CR) 内のユーザー定義情報にアクセスします。システムパラメーターは、build run controller によってランタイム時に定義されているため、設定または変更できません。

ビルドストラテジーの定義に以下のシステムパラメーターを定義できます。

Expand

表2.2 システムパラメーター
パラメーター	説明
`$(params.shp-source-root)`	ソースコードが格納されているディレクトリーへの絶対パスを指定します。
`$(params.shp-source-context)`	ソースコードのコンテキストディレクトリーへの絶対パスを指定します。`Build` CR で `spec.source.contextDir` の値を指定しない場合、このパラメーターは `$(params.shp-source-root)` システムパラメーターの値を使用します。
`$(params.shp-output-image)`	`ビルド` または `ビルド実行` CR の `spec.output.image` フィールドで定義されている、プッシュするイメージの URL を指定します。

2.3. ステップリソースの定義
リンクのコピー

ビルドストラテジーの各ステップにおける CPU、メモリー、およびディスクの制限を定義します。ストラテジーに複数のステップがある場合、それぞれのステップに異なるリソース量を割り当てることができます。

管理者として、同じストラテジーの異なるバージョン (たとえば、buildah-small と buildah-large) を提供することで、ユーザーが自身のビルド要件に合ったリソースプロファイルを選択できるようにすることができます。

2.3.1. さまざまなリソースを使用したストラテジー
リンクのコピー

異なるビルド要件に対して異なるリソース制限を適用するために、同じストラテジーの複数のバリエーションを定義します。

以下の例では、リソースに対して小および中程度の制限を定義した同じ buildah ストラテジーを使用しています。これらの例により、ストラテジー管理者はステップリソースの定義をより詳細に制御できます。

次の例に示すように、buildah ストラテジーの spec.steps[].resources フィールドに小さなリソース制限を設定できます。

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: []
    # ...

次の例に示すように、buildah ストラテジーの spec.steps[].resources フィールドに中程度のリソース制限を設定できます。

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: []
    # ...

ストラテジーのリソース定義を設定した後、次の例に示すように、ビルド カスタムリソース (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 は、ターゲットネームスペース内ですべてのステップを順番に実行する Pod を作成します。

2.4. アノテーション定義
リンクのコピー

BuildStrategy または ClusterBuildStrategy のアノテーションは、他の Kubernetes オブジェクトと同様の方法で定義します。ビルドストラテジーは、これらのアノテーションを TaskRun リソースに渡します。そして、テクトンはそれらを Pod に渡す。

アノテーションは、以下の目的で使用できます。

ネットワーク帯域幅: ネットワーク帯域幅を制限するには、kubernetes.io/ ingress-bandwidth または kubernetes.io/Egress-bandwidth を使用してください。
セキュリティープロファイル: container.apparmor.security.beta.kubernetes.io/<container_name> を使用して、コンテナーの AppArmor プロファイルを定義します。

以下の例では、ビルドストラテジーでのアノテーションの使用方法を示しています。

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. 文字列パラメーターの安全な参照
リンクのコピー

ビルドストラテジーで文字列パラメーターを参照するには、$(params.your-parameter-name) という構文を使用します。ビルドが実行されると、システムは変数を実際の文字列に置き換えます。

注記

システムパラメーターとストラテジーパラメーターには、$(params.your-parameter-name) という構文を使用できます。

インラインスクリプトを使用する際にコマンドインジェクションの脆弱性を防ぐには、以下のいずれかの安全な方法を使用してください。

環境変数の使用

引数の使用

文字列パラメーターを環境変数に参照する

パラメーターを環境変数に渡します。次に、スクリプト内でその変数を引用符で囲みます。以下の例では、スクリプト内の環境変数を使用して文字列パラメーターを参照します。

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}"

文字列パラメーターを引数に参照する

パラメーターをスクリプトへの引数として渡してください。次に、シェル変数を使用してそれを読み取ります。以下の例では、スクリプト内で定義した引数を使用して、文字列パラメーターを参照します。

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) では、以下の結果パラメーターを定義できます。

Expand

表2.3 結果パラメーター
パラメーター	説明
`$(results.shp-image-digest.path)`	イメージのダイジェストまたはコンテンツハッシュを保存するファイルへのパスを指定します。
`$(results.shp-image-size.path)`	イメージの圧縮サイズを保存するファイルへのパスを指定します。
`$(results.shp-error-reason.path)`	エラー理由を保存するファイルのパスを指定します。
`$(results.shp-error-message.path)`	エラーメッセージが保存されているファイルのパスを指定します。

次の例は、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. ボリュームとボリュームマウントの定義
リンクのコピー

ビルドストラテジーでは、ボリュームとボリュームマウントを使用して、ビルド手順中にデータを管理します。デフォルトでは、BuildStrategy 内のボリュームを上書きすることはできません。ビルド または ビルド実行で カスタムボリュームを使用できるようにするには、ストラテジーで overridable フィールドを true に設定する必要があります。

注記

ビルドのステップで定義されたボリュームマウントを使用すると、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 CR は、名前空間内で個々のビルドがどのように実行されるかを管理し、実行時の動作を制御します。

3.1. ビルド実行の設定可能なフィールド
リンクのコピー

入力パラメーター、サービスアカウント、出力、ライフサイクル設定を指定して、BuildRun カスタムリソース (CR) を設定します。

次の表は、BuildRun カスタムリソース (CR) で必須となるフィールドについて説明しています。

Expand

表3.1 BuildRun CR の必須フィールド
フィールド	説明
`apiVersion`	リソースの API バージョンを指定します。たとえば、`shipwright.io/v1beta1` です。
`kind`	リソースの型を指定します。たとえば、`BuildRun` です。
`metadata`	カスタムリソース定義インスタンスを識別するメタデータを示します。たとえば、`BuildRun` リソースの名前などです。

次の表は、BuildRun カスタムリソース (CR) のオプションフィールドについて説明しています。

Expand

表3.2 BuildRun CR のオプションフィールド
フィールド	説明
`spec.build.name`	使用する既存の `Build` リソースインスタンスを指定します。このフィールドは `spec.build.spec` フィールドでは使用できません。
`spec.build.spec`	使用する組み込み `Build` リソースインスタンスを指定します。このフィールドは `spec.build.name` フィールドでは使用できません。
`spec.serviceAccount`	イメージのビルド時に使用するサービスアカウントを示します。
`spec.timeout`	カスタムタイムアウトを定義します。このフィールドの値は、`Build` リソースで定義される `spec.timeout` フィールドの値を上書きします。
`spec.paramValues`	ビルドストラテジーで定義されたパラメーターの値を指定するための名前と値のリストを示します。パラメーター値は、`Build` リソース内の同じ名前で定義されるパラメーターの値を上書きします。
`spec.output.image`	生成されたイメージのプッシュ先のカスタムの場所を示します。このフィールドの値は、`Build` リソースで定義される `output.image` フィールドの値をオーバーライドします。
`spec.output.pushSecret`	コンテナーレジストリーにアクセスするための既存のシークレットを示します。このシークレットは、`Build` リソースで要求される他のシークレットと共にサービスアカウントに追加されます。
`spec.env`	ビルドコンテナーに渡すことができる追加の環境変数を定義します。このフィールド値は、`Build` リソースで指定されている環境変数をオーバーライドします。使用できる変数は、ビルドストラテジーで使用されるツールによって異なります。
`spec.nodeSelector`	Builds を実行するノードを指定します。
`spec.tolerations`	Builds Pod の toleration を指定します。
`spec.schedulerName`	Builds Pod のスケジューラーを指定します。

重要

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 リソースに完全なビルド仕様を定義します。このアプローチにより、専用のビルド カスタム リソース (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) で定義できます。BuildRun リソースで設定された値は、Build リソース内の同名の値を上書きします。

次の例では、BuildRun の キャッシュ 値が Build リソースの キャッシュ 値を上書きします。

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:
  # ...

以下は、

<your_build>: ビルド CR の名前を指定します。
<your_namespace>: ビルド CR の名前空間を指定します。
< あなたの戦略 >: ビルド CR に使用されるストラテジーを指定します。

apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: <your_buildrun>
  namespace: <your_namespace>
spec:
  build:
    name: <your_build>
  paramValues:
  - name: cache
    value: registry

以下は、

<your_buildrun>: ビルドラン CR の名前を指定します。
<your_namespace>: Buildrun CR の名前空間を指定します。
<your_build>: ビルド の名前を指定します。

3.5. サービスアカウント定義
リンクのコピー

次の例に示すように、BuildRun リソースでサービスアカウントを定義して、Build リソースが参照するシークレットへのアクセス権限を付与します。

apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: buildah-buildrun
spec:
  build:
    name: buildah-build
  serviceAccount: pipeline

spec.serviceAccount:: BuildRun リソースの名前に対応する、生成されるサービスアカウントの名前を定義します。実行時にサービスアカウントを生成するには、値を .generate に設定することもできます。
注記
サービスアカウントを定義せず、namespace に pipeline サービスアカウントが存在する場合、BuildRun リソースはそのアカウントを使用します。それ以外の場合、BuildRun リソースは default サービスアカウントを使用します。

3.6. ビルド実行の保持パラメーター定義
リンクのコピー

ビルド実行 カスタムリソース (CR) の保持パラメーターを使用して、完了したビルド実行を自動的に削除します。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>

各項目の説明:

< ビルド名 >: ビルドラン CR の名前を指定します。
<buildrun_name>: ビルド CR の名前を指定します。
< ボリューム名 >: ビルド CR の ボリューム 名を指定します。
<configmap_name>: ビルド CR の ConfigMap の名前を指定します。

3.8. 環境変数の定義
リンクのコピー

BuildRun カスタムリソース (CR) 内で環境変数を設定できます。これらの変数は、ビルドコンテナーに情報を渡します。リテラル値を使用することも、Kubernetes のダウンワード API を使用することもできます。

次の例は、環境変数を定義する方法を示しています。

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>"

各項目の説明:

環境名: BuildRun CR 内の環境変数の名前を定義します。
env.value: BuildRun CR 内の環境変数の値を定義します。

次の例は、Kubernetes downward API を使用して 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

各項目の説明:

<pod_name>: Pod の名前を指定します。

次の例は、Kubernetes Downward API を使用してコンテナーを環境変数として公開する 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

各項目の説明:

<my_container>: コンテナーの名前を指定します。

3.9. ビルド実行ステータス
リンクのコピー

BuildRun カスタムリソース (CR) のステータスを確認することで、イメージビルドの進行状況と完了状況を監視できます。BuildRun CR は、ステータス情報を status.conditions フィールドに格納します。このフィールドには、ステータス、そのステータスの理由、および説明メッセージが含まれます。たとえば、成功という 条件タイプは、ビルドが正常に完了したことを意味します。

以下の例は、特定のビルド実行 CR のステータスを表示する方法を示しています。

不明なステータス: 不明 ステータスは、ビルドがまだ開始中または進行中であることを示します。次の例は、ステータスが 不明なビルド実行 を示しています。

$ oc get buildrun buildah-buildrun-mp99r

出力例:

NAME                    SUCCEEDED   REASON    STARTTIME   COMPLETIONTIME
buildah-buildrun-mp99r  Unknown     Unknown      1s

真の状態: True ステータスは、ビルドが正常に完了したことを示します。以下の例は、ステータスが True の BuildRun`を示しています。

$ oc get buildrun buildah-buildrun-mp99r

出力例:

NAME                   SUCCEEDED     REASON     STARTTIME   COMPLETIONTIME
buildah-buildrun-mp99r  True        Succeeded      29m       20m

BuildRun CR は、ステータス関連の情報を status.conditions フィールドに格納します。たとえば、Succeeded タイプの条件は、リソースが操作を正常に完了したことを示します。status.conditions フィールドには、BuildRun CR のステータス、理由、メッセージなどの重要な情報が含まれます。

3.9.1. ビルド実行ステータスの説明
リンクのコピー

BuildRun カスタムリソース (CR) は、イメージ構築プロセス中にステータスが異なる可能性があります。ステータス フィールドを使用して、ビルドの状態を追跡してください。

次の表は、ビルド実行のさまざまなステータスを示しています。

Expand

表3.3 ビルド実行のステータス
ステータス	原因	説明
`Unknown`	`Pending`	`BuildRun` リソースは、`Pending` ステータスの Pod を待機します。
`Unknown`	`Running`	コントローラーは検証を行い、`ビルド実行` を開始します。
`Unknown`	`BuildRunCanceled`	ユーザーがビルド実行のキャンセルを要求しました。この要求は build run controller をトリガーし、関連するタスクの実行をキャンセルするリクエストを作成します。このステータスが存在する場合、キャンセルはまだ処理中です。
`True`	`Succeeded`	`BuildRun` リソースの Pod が作成されます。
`False`	`Failed`	`BuildRun` リソースがステップの 1 つで失敗しました。
`False`	`BuildRunTimeout`	`BuildRun` リソースの実行がタイムアウトしました。
`False`	`UnknownStrategyKind`	`Kind` フィールドで定義されたストラテジータイプは不明です。`ClusterBuildStrategy` と `BuildStrategy` のストラテジータイプを定義できます。
`False`	`ClusterBuildStrategyNotFound`	参照されたクラスタースコープのストラテジーがクラスター内に見つかりませんでした。
`False`	`BuildStrategyNotFound`	参照された namespace スコープのストラテジーがクラスター内に見つかりませんでした。
`False`	`SetOwnerReferenceFailed`	`BuildRun` リソースから関連する `TaskRun` リソースへの `ownerReferences` フィールドの設定に失敗しました。
`False`	`TaskRunIsMissing`	`BuildRun` リソースに関連する `TaskRun` リソースが見つかりませんでした。
`False`	`TaskRunGenerationFailed`	`TaskRun` 仕様の生成に失敗しました。
`False`	`MissingParameterValues`	デフォルトのないビルドストラテジーで定義されている一部のパラメーターに値が指定されていません。`Build` または `BuildRun` CR でこれらのパラメーターの値を指定する必要があります。
`False`	`RestrictedParametersInUse`	システムパラメーターの値が指定されましたが、これは許可されません。
`False`	`UndefinedParameter`	ビルドストラテジーで定義されていないパラメーターの値が指定されました。
`False`	`WrongParameterValueType`	システムは、ビルドストラテジーパラメーターの値の入力ミスを検出しました。たとえば、ビルドストラテジーでパラメーターが配列または文字列として定義されている場合は、それに応じて値のセットまたは直接値を指定する必要があります。
`False`	`InconsistentParameterValues`	パラメーターの値に、`value`、`configMapValue`、および `secretValue` の値が複数含まれていました。一貫性を維持するには、前述の値のうち 1 つだけを指定する必要があります。
`False`	`EmptyArrayItemParameterValues`	配列パラメーターの値内の項目に、`value`、`configMapValue`、および `secretValue` の値が含まれていませんでした。null 配列項目は許可されないため、前述の値のうち 1 つだけを指定する必要があります。
`False`	`IncompleteConfigMapValueParameterValues`	パラメーターの値に、`name` または `value` フィールドが空の `configMapValue` 値が含まれていました。namespace 内の既存の config map キーを指すように空のフィールドを指定する必要があります。
`False`	`IncompleteSecretValueParameterValues`	パラメーターの値に、`name` または `value` フィールドが空の `secretValue` 値が含まれていました。namespace 内の既存の秘密鍵を指すには、空のフィールドを指定する必要があります。
`False`	`ServiceAccountNotFound`	参照されたサービスアカウントがクラスター内に見つかりませんでした。
`False`	`BuildRegistrationFailed`	`BuildRun` リソースで参照されているビルドは `Failed` の状態です。
`False`	`BuildNotFound`	`BuildRun` リソースで参照されているビルドが見つかりませんでした。
`False`	`BuildRunCanceled`	`BuildRun` および関連する `TaskRun` リソースは正常にキャンセルされました。
`False`	`BuildRunNameInvalid`	`metadata.name` フィールドに定義されたビルド実行名が無効です。`BuildRun` CR でビルド実行名の有効なラベル値を指定する必要があります。
`False`	`BuildRunNoRefOrSpec`	`BuildRun` リソースには、`spec.build.name` も `spec.build.spec` フィールドも定義されていません。
`False`	`BuildRunAmbiguousBuild`	定義された `BuildRun` リソースは、`spec.build.name` フィールドと `spec.build.spec` フィールドの両方を使用します。一度に許可されるパラメーターは 1 つだけです。
`False`	`BuildRunBuildFieldOverrideForbidden`	定義された `spec.build.name` フィールドは、`spec.build.spec` フィールドと組み合わせたオーバーライドを使用しますが、これは使用できません。`spec.build.spec` フィールドを使用してそれぞれの値を直接指定してください。
`False`	`PodEvicted`	ビルド実行 Pod が、実行されていたノードからエビクトされました。

3.9.2. ビルド実行の失敗を理解する
リンクのコピー

ビルドが失敗した場合、BuildRun カスタムリソース (CR) の status.failureDetails フィールドには、エラーメッセージ、失敗理由、エラーが発生した特定のコンテナーまたは Pod など、包括的なエラー情報が表示されます。このフィールドは、ビルドの失敗に関するトラブルシューティングに役立ちます。

次の例は、失敗したビルド実行を示しています。

# ...
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 カスタムリソース (CR) の実行が完了すると、.status.taskResults にはイメージダイジェストやコミット SHA などのステップ結果が表示されます。.status.sources にはソースステップの結果が、.status.output に は出力ステップの結果が格納され、ソースとビルドされたイメージが反映されます。

以下の例は、Git ソースのステップ結果を含む BuildRun CR を示しています。

# ...
status:
  buildSpec:
    # ...
  output:
    digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53
    size: 1989004
  sources:
  - name: default
    git:
      commitAuthor: xxx xxxxxx
      commitSha: f25822b85021d02059c9ac8a211ef3804ea8fdde
      branchName: main

次の例は、ローカルソースコードのステップ結果を含む BuildRun CR を示しています。

# ...
status:
  buildSpec:
    # ...
  output:
    digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53
    size: 1989004
  sources:
  - name: default
    bundle:
      digest: sha256:0f5e2070b534f9b880ed093a537626e3c7fdd28d5328a8d6df8d29cd3da760c7

注記

出力イメージのダイジェストとサイズは、ビルドストラテジーで定義されている場合にのみ表示されます。

3.9.4. ビルドのスナップショット
リンクのコピー

ビルドスナップショットには、特定のビルド実行で使用された正確な設定が記録されます。

ビルド実行が調整されると、BuildRun カスタムリソース (CR) の status.buildSpec フィールドが更新されます。このフィールドには、その特定のイメージビルドに使用された元の ビルド 仕様の完全なコピーが格納されます。このスナップショットを使用すれば、元の ビルド CR が後で変更された場合でも、実行時に使用された設定を確認できます。

3.10. ビルド実行と Tekton タスクの関係
リンクのコピー

BuildRun は、Tekton TaskRun の リソースを使用してイメージをビルドします。TaskRun は、ビルドが完了または失敗するまで、ビルドストラテジーで定義された手順に従います。

BuildRun を 作成すると、ビルドコントローラーは新しい TaskRun を開始します。BuildRun リソースは、イメージビルドのタスクをこの TaskRun に割り当てます。TaskRun は、ビルドストラテジーで定義されたすべてのステップを実行します。

3.11. ビルド実行のキャンセル
リンクのコピー

アクティブな BuildRun リソースを停止するには、BuildRun リソースの 状態 フィールドを BuildRunCanceled に設定します。BuildRun を キャンセルすると、基となる TaskRun リソースもキャンセルされます。

次の例は、BuildRun リソースのキャンセルされたビルド実行を示しています。

apiVersion: shipwright.io/v1beta1
kind: BuildRun
metadata:
  name: buildah-buildrun
spec:
  # [...]
  state: "BuildRunCanceled"

3.12. ビルド実行の自動削除
リンクのコピー

保持期間と TTL パラメーターを定義することで、ビルド実行のライフサイクルを自動的に管理します。

ビルド または ビルド実行の 仕様に以下の保持パラメーターを追加すると、ビルド実行が自動的に削除されます。

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: ビルドに対して存在できる、失敗したビルド実行の数を定義します。

3.13. Pod の設定
リンクのコピー

オプションの BuildRun カスタムリソース (CR) フィールドを使用して、ビルドの Pod のスケジューリングと配置を設定します。

ビルド Pod を設定するには、以下のフィールドを使用します。

spec.tolerations: Pod の許容範囲を指定します。注:NoSchedule の taint 効果のみがサポートされています。
spec.nodeSelector: Pod を実行する必要のあるノードを指定します。
spec.schedulerName: Pod のカスタムスケジューラーを指定します。

注記

これらのフィールドを ビルド CR と ビルドラン CR の両方で定義した場合、ビルドランの 値が優先されます。

設定

Builds の設定

第1章 Builds の設定リンクのコピーリンクがクリップボードにコピーされました!

1.1. build の設定可能なフィールドリンクのコピーリンクがクリップボードにコピーされました!

1.2. ソース定義リンクのコピーリンクがクリップボードにコピーされました!

1.3. ストラテジー定義リンクのコピーリンクがクリップボードにコピーされました!

1.4. ビルドのパラメーター値の定義リンクのコピーリンクがクリップボードにコピーされました!

1.4.1. パラメーター値を定義する設定例リンクのコピーリンクがクリップボードにコピーされました!

1.5. Builder または Docker ファイルの定義リンクのコピーリンクがクリップボードにコピーされました!

1.6. 出力定義リンクのコピーリンクがクリップボードにコピーされました!

1.7. ビルドの保持パラメーター定義リンクのコピーリンクがクリップボードにコピーされました!

1.8. ビルドのボリューム定義リンクのコピーリンクがクリップボードにコピーされました!

1.9. Pod の設定リンクのコピーリンクがクリップボードにコピーされました!

第2章 ビルドストラテジーの設定リンクのコピーリンクがクリップボードにコピーされました!

2.1. ストラテジーパラメーターの定義リンクのコピーリンクがクリップボードにコピーされました!

2.2. システムパラメーターの定義リンクのコピーリンクがクリップボードにコピーされました!

2.3. ステップリソースの定義リンクのコピーリンクがクリップボードにコピーされました!

2.3.1. さまざまなリソースを使用したストラテジーリンクのコピーリンクがクリップボードにコピーされました!

2.3.2. Tekton パイプラインのリソース管理リンクのコピーリンクがクリップボードにコピーされました!

2.4. アノテーション定義リンクのコピーリンクがクリップボードにコピーされました!

2.5. 文字列パラメーターの安全な参照リンクのコピーリンクがクリップボードにコピーされました!

2.6. システム結果の定義リンクのコピーリンクがクリップボードにコピーされました!

2.7. ボリュームとボリュームマウントの定義リンクのコピーリンクがクリップボードにコピーされました!

第3章 ビルド実行の設定リンクのコピーリンクがクリップボードにコピーされました!

3.1. ビルド実行の設定可能なフィールドリンクのコピーリンクがクリップボードにコピーされました!

3.2. ビルド参照定義リンクのコピーリンクがクリップボードにコピーされました!

3.3. ビルド仕様の定義リンクのコピーリンクがクリップボードにコピーされました!

3.4. ビルド実行のパラメーター値定義リンクのコピーリンクがクリップボードにコピーされました!

3.5. サービスアカウント定義リンクのコピーリンクがクリップボードにコピーされました!

3.6. ビルド実行の保持パラメーター定義リンクのコピーリンクがクリップボードにコピーされました!

3.7. ビルド実行のボリューム定義リンクのコピーリンクがクリップボードにコピーされました!

3.8. 環境変数の定義リンクのコピーリンクがクリップボードにコピーされました!

3.9. ビルド実行ステータスリンクのコピーリンクがクリップボードにコピーされました!

3.9.1. ビルド実行ステータスの説明リンクのコピーリンクがクリップボードにコピーされました!

3.9.2. ビルド実行の失敗を理解するリンクのコピーリンクがクリップボードにコピーされました!

3.9.3. ステップ結果のビルド実行ステータスリンクのコピーリンクがクリップボードにコピーされました!

3.9.4. ビルドのスナップショットリンクのコピーリンクがクリップボードにコピーされました!

3.10. ビルド実行と Tekton タスクの関係リンクのコピーリンクがクリップボードにコピーされました!

3.11. ビルド実行のキャンセルリンクのコピーリンクがクリップボードにコピーされました!

3.12. ビルド実行の自動削除リンクのコピーリンクがクリップボードにコピーされました!

3.13. Pod の設定リンクのコピーリンクがクリップボードにコピーされました!

詳細情報

試用、購入および販売

コミュニティー

会社概要

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

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

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

第1章 Builds の設定
リンクのコピー

1.1. build の設定可能なフィールド
リンクのコピー

1.2. ソース定義
リンクのコピー

1.3. ストラテジー定義
リンクのコピー

1.4. ビルドのパラメーター値の定義
リンクのコピー

1.4.1. パラメーター値を定義する設定例
リンクのコピー

1.5. Builder または Docker ファイルの定義
リンクのコピー

1.6. 出力定義
リンクのコピー

1.7. ビルドの保持パラメーター定義
リンクのコピー

1.8. ビルドのボリューム定義
リンクのコピー

1.9. Pod の設定
リンクのコピー

第2章ビルドストラテジーの設定
リンクのコピー

2.1. ストラテジーパラメーターの定義
リンクのコピー

2.2. システムパラメーターの定義
リンクのコピー

2.3. ステップリソースの定義
リンクのコピー

2.3.1. さまざまなリソースを使用したストラテジー
リンクのコピー

2.3.2. Tekton パイプラインのリソース管理
リンクのコピー

2.4. アノテーション定義
リンクのコピー

2.5. 文字列パラメーターの安全な参照
リンクのコピー

2.6. システム結果の定義
リンクのコピー

2.7. ボリュームとボリュームマウントの定義
リンクのコピー

第3章ビルド実行の設定
リンクのコピー

3.1. ビルド実行の設定可能なフィールド
リンクのコピー

3.2. ビルド参照定義
リンクのコピー

3.3. ビルド仕様の定義
リンクのコピー

3.4. ビルド実行のパラメーター値定義
リンクのコピー

3.5. サービスアカウント定義
リンクのコピー

3.6. ビルド実行の保持パラメーター定義
リンクのコピー

3.7. ビルド実行のボリューム定義
リンクのコピー

3.8. 環境変数の定義
リンクのコピー

3.9. ビルド実行ステータス
リンクのコピー

3.9.1. ビルド実行ステータスの説明
リンクのコピー

3.9.2. ビルド実行の失敗を理解する
リンクのコピー

3.9.3. ステップ結果のビルド実行ステータス
リンクのコピー

3.9.4. ビルドのスナップショット
リンクのコピー

3.10. ビルド実行と Tekton タスクの関係
リンクのコピー

3.11. ビルド実行のキャンセル
リンクのコピー

3.12. ビルド実行の自動削除
リンクのコピー

3.13. Pod の設定
リンクのコピー