OpenShift 文档正在迁移，很快将只能在 docs.redhat.com（所有 Red Hat 产品文档的中心）访问。立即体验 新的文档体验。
  1. 文档
    2. history bug_report picture_as_pdf
×

配置构建运行

在BuildRun自定义资源 (CR) 中，您可以定义构建参考、构建规范、参数值、服务帐户、输出、保留参数和卷来配置构建运行。BuildRun 资源可在命名空间内使用。

要配置构建运行，请创建一个BuildRun资源 YAML 文件并将其应用到 OpenShift Container Platform 集群。

构建运行中的可配置字段

您可以在您的BuildRun自定义资源 (CR) 中使用以下字段

表 1. BuildRun CR 中的字段
字段 存在性 描述

apiVersion

必需

指定资源的 API 版本。例如，shipwright.io/v1beta1。

kind

必需

指定资源的类型。例如，BuildRun。

metadata

必需

指示标识自定义资源定义实例的元数据。例如，BuildRun资源的名称。

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资源中指定的任何环境变量。可用变量取决于构建策略使用的工具。

您不能在同一个 CR 中同时使用spec.build.name和spec.build.spec字段，因为它们是互斥的。

构建参考定义

您可以在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

构建规范定义

您可以使用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>

您不能在同一个 CR 中同时使用spec.build.name和spec.build.spec字段，因为它们是互斥的。

构建运行的参数值定义

您可以在您的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

服务账户定义

您可以在您的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资源的名称对应。

如果您没有定义服务账户，BuildRun资源将使用命名空间中存在的pipeline服务账户。否则，BuildRun资源将使用default服务账户。

构建运行的保留参数定义

您可以在您的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 中定义的保留参数的值。

构建运行的卷定义

您可以在您的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>

环境变量定义

您可以根据需要在您的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

构建运行状态

每当镜像构建状态发生变化时，BuildRun资源都会更新，如下例所示。

示例：状态为 Unknown 的 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资源的重要信息，例如状态、原因和消息。

构建运行状态描述

在镜像构建过程中，BuildRun自定义资源 (CR) 可以具有不同的状态。下表涵盖了构建运行的不同状态。

表 2. 构建运行的状态
状态 原因 描述

Unknown

Pending

BuildRun资源正在等待状态为Pending的 Pod。

Unknown

Running

BuildRun资源已验证并开始执行其工作。

Unknown

BuildRunCanceled

用户已请求取消构建运行。此请求将触发构建运行控制器发出取消相关任务运行的请求。在此状态存在时，取消仍在处理中。

True

Succeeded

为BuildRun资源创建了 Pod。

False

Failed

BuildRun资源在其中一个步骤中失败。

False

BuildRunTimeout

BuildRun资源的执行超时。

False

UnknownStrategyKind

Kind字段中定义的策略类型未知。您可以定义这些策略类型：ClusterBuildStrategy和BuildStrategy。

False

ClusterBuildStrategyNotFound

集群中未找到引用的集群范围策略。

False

BuildStrategyNotFound

集群中未找到引用的命名空间范围策略。

False

SetOwnerReferenceFailed

将BuildRun资源的ownerReferences字段设置为相关的TaskRun资源失败。

False

TaskRunIsMissing

未找到与BuildRun资源相关的TaskRun资源。

False

TaskRunGenerationFailed

TaskRun规范的生成失败。

False

MissingParameterValues

您没有为构建策略中定义的某些参数提供任何值，而这些参数没有任何默认值。您必须在Build或BuildRun CR 中为这些参数提供值。

False

RestrictedParametersInUse

提供了系统参数的值，这是不允许的。

False

UndefinedParameter

提供了构建策略中未定义的参数的值。

False

WrongParameterValueType

为构建策略参数提供了错误类型的值。例如，如果参数在构建策略中定义为数组或字符串，则必须相应地提供一组值或直接值。

False

InconsistentParameterValues

参数的值包含多个以下值：value、configMapValue和secretValue。您必须只提供上述值中的一个以保持一致性。

False

EmptyArrayItemParameterValues

数组参数的值中的一个项目不包含以下值：value、configMapValue和secretValue。您必须只提供上述值中的一个，因为不允许空数组项。

False

IncompleteConfigMapValueParameterValues

参数的值包含一个configMapValue值，其中name或value字段为空。您必须指定空字段以指向命名空间中现有的配置映射键。

False

IncompleteSecretValueParameterValues

参数的值包含一个secretValue值，其中name或value字段为空。您必须指定空字段以指向命名空间中现有的密钥。

False

ServiceAccountNotFound

集群中未找到引用的服务账号。

False

构建注册失败

BuildRun 资源中引用的构建处于 失败 状态。

False

构建未找到

BuildRun 资源中引用的构建未找到。

False

BuildRunCanceled

BuildRun 和相关的 TaskRun 资源已成功取消。

False

BuildRun名称无效

metadata.name 字段中定义的构建运行名称无效。您必须在 BuildRun CR 中为构建运行名称提供有效的标签值。

False

BuildRun缺少引用或规范

BuildRun 资源未定义 spec.build.name 或 spec.build.spec 字段。

False

BuildRun构建定义不明确

已定义的 BuildRun 资源同时使用了 spec.build.name 和 spec.build.spec 字段。一次只允许使用一个参数。

False

禁止覆盖BuildRun构建字段

已定义的 spec.build.name 字段与 spec.build.spec 字段一起使用了覆盖，这是不允许的。使用 spec.build.spec 字段直接指定相应的值。

False

Pod被驱逐

构建运行 Pod 已从其运行所在的节点中驱逐。

构建运行失败

构建运行失败时，您可以检查 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 相关的所有操作的错误详细信息。

构建运行状态中的步骤结果

BuildRun 资源完成执行后，.status 字段包含构建运行控制器生成的步骤发出的 .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

只有在构建策略中定义了输出镜像的摘要和大小，您才能看到它们。

构建快照

对于每次构建运行协调，如果现有任务运行是该构建运行的一部分，则 BuildRun 资源状态中的 buildSpec 字段将更新。

在此更新期间，将生成 Build 资源快照并将其嵌入到 BuildRun 资源的 status.buildSpec 字段中。因此，buildSpec 字段包含用于执行特定镜像构建的原始 Build 规范的精确副本。通过使用构建快照，您可以查看原始 Build 资源配置。

构建运行与 Tekton 任务的关系

BuildRun 资源将镜像构建的任务委托给 Tekton TaskRun 资源，后者运行所有步骤，直到任务完成或任务发生故障。

在构建运行协调期间，构建运行控制器会生成一个新的 TaskRun 资源。控制器将构建运行执行所需的步骤嵌入到 TaskRun 资源中。嵌入式步骤在您的构建策略中定义。

取消构建运行

您可以通过将其状态设置为 BuildRunCanceled 来取消活动的 BuildRun 实例。取消 BuildRun 实例时，底层的 TaskRun 资源也会被标记为已取消。

以下示例显示了 BuildRun 资源的已取消构建运行

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

自动删除构建运行

要自动删除构建运行，您可以在 build 或 buildrun 规范中添加以下保留参数

  • buildrun TTL 参数：确保构建运行仅在完成后的定义时间段内存在。

    • buildrun.spec.retention.ttlAfterFailed：如果指定的时间已过并且构建运行失败，则删除构建运行。

    • buildrun.spec.retention.ttlAfterSucceeded：如果指定的时间已过并且构建运行成功，则删除构建运行。

  • build TTL 参数：确保构建的构建运行仅在完成后的定义时间段内存在。

    • build.spec.retention.ttlAfterFailed：如果指定的时间已过并且构建的构建运行失败，则删除构建运行。

    • build.spec.retention.ttlAfterSucceeded：如果指定的时间已过并且构建的构建运行成功，则删除构建运行。

  • build 限制参数：确保构建只能存在有限数量的成功或失败的构建运行。

    • build.spec.retention.succeededLimit：定义构建可以存在的成功构建运行的数量。

    • build.spec.retention.failedLimit：定义构建可以存在的失败构建运行的数量。