配置

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

您可以通过设置以下字段的值，在 Build 自定义资源(CR)中配置构建的源详情：

构建控制器不会自动验证您为拉取镜像指定的 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 存储库是否存在：

以下示例演示了如何使用不同源输入集配置构建。

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-build
spec:
  source:
    git:
      url: https://github.com/sclorg/nodejs-ex
      cloneSecret: source-repository-credentials

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

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

您可以在 Build CR 中为构建配置策略。以下构建策略可供使用：

要配置构建策略，请在 Build CR 中定义 spec.strategy.name 和 spec.strategy.kind 字段，如下例所示：

apiVersion: shipwright.io/v1beta1
kind: Build
metadata:
  name: buildah-build
spec:
  strategy:
    name: buildah
    kind: ClusterBuildStrategy

您可以在 Build CR 中为构建策略参数指定值。通过指定参数值，您可以控制构建策略的步骤的工作方式。您还可以覆盖 BuildRun 资源中的值。

对于所有参数，您必须直接指定值，或使用配置映射或 secret 的引用键来指定值。

在 Build CR 中使用 paramValues 字段时，请避免以下情况：

另外，请确保在 Build CR 中定义 paramValues 字段前了解策略的内容。

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

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

apiVersion: v1
kind: ConfigMap
metadata:
  name: buildah-configuration
  namespace: <your_namespace>
data:
  storage-driver: overlay

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

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

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

在 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

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

在 Build CR 中，您可以指定一个输出位置来推送镜像。当使用外部私有 registry 作为输出位置时，您必须指定一个 secret 才能访问该镜像。您还可以指定输出镜像的注解和标签。

以下示例定义了推送镜像的公共 registry：

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

以下示例定义了推送镜像的私有 registry：

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"

您可以针对以下目的定义保留参数：

保留参数提供了一种自动清理 BuildRun 实例或资源的方法。您可以在 Build CR 中设置以下保留参数的值：

以下示例显示了在 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
  # ...

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

您可以在 BuildStrategy 或 ClusterBuildStrategy 自定义资源(CR)中定义策略参数，并在 Build 或 BuildRun CR 中定义这些参数的值。您还可以在构建时配置或修改策略参数。

在为您的策略定义参数前请考虑以下点：

您可以在定义构建策略的步骤时使用系统参数访问系统信息，或在 Build 或 BuildRun 自定义资源(CR)中用户定义的信息。您无法配置或修改系统参数，因为它们在构建运行控制器运行时定义。

您可以在构建策略定义中定义以下系统参数：

您可以为构建策略中的所有步骤包含资源的定义，如对 CPU、内存和磁盘用量实施的限制。对于具有多个步骤的策略，步骤可能需要的资源数量超过其他步骤。作为策略管理员，您可以定义每个步骤最佳的资源值。

例如，您可以使用相同的步骤安装策略，但集群中的不同名称和步骤资源，以便用户可以创建具有较小或更大资源要求的构建。

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

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

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

您可以像为任何其他 Kubernetes 对象一样，为构建策略或集群构建策略定义注解。构建策略首先将注解传播到 TaskRun 资源。然后，Tekton 将它们传播到 pod。

您可以将注解用于以下目的：

以下示例演示了在构建策略中使用注解：

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

以下注解不会被传播：

策略管理员可以使用策略引擎进一步限制注解的使用。

当您在 BuildStrategy 或 ClusterBuildStrategy 自定义资源(CR)中定义环境变量、参数或镜像时，会使用字符串参数。在构建策略步骤中，您可以使用 $(params.your-parameter-name) 语法引用字符串参数。

在 pod 中，所有 $(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)

您可以将构建策略创建的镜像大小和摘要存储到一组结果文件。当 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

构建策略包括卷和卷挂载的定义。构建策略中定义的卷支持所有常见的 volumeSource 类型。构建步骤通过创建卷挂载来引用卷。

构建策略中的卷 使用可覆盖 的布尔值标志，该标志默认设置为 false。如果 Build 或 BuildRun 资源尝试覆盖 BuildStrategy 资源中定义的卷，则它将失败，因为 overridable 标志的默认值是 false。

以下示例显示了定义 volumes 和 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: {}

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

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

您可以在 BuildRun CR 中指定构建策略参数的值。如果您为那些在 Build 资源中定义的参数提供了一个名称相同的参数，则 BuildRun 资源中定义的值具有优先权。

在以下示例中，BuildRun 资源中的 cache 参数的值会覆盖 cache 参数的值，该参数在 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:
  # ...

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 资源中引用的所有 secret，如下例所示：

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

您可以指定 BuildRun 资源中可以存在已完成的构建运行的时间。保留参数提供了一种自动清理 BuildRun 实例的方法。您可以在 BuildRun CR 中设置以下保留参数的值：

以下示例演示了如何在 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 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 中的环境变量。以下示例演示了如何定义环境变量：

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 资源：

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 资源：

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 资源会在镜像构建状态更改时更新，如下例所示：

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

$ 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 资源的大量信息，如 status、reason 和 message。

# ...
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:
  buildSpec:
    # ...
  output:
    digest: sha256:07626e3c7fdd28d5328a8d6df8d29cd3da760c7f5e2070b534f9b880ed093a53
    size: 1989004
  sources:
  - name: default
    git:
      commitAuthor: xxx xxxxxx
      commitSha: f25822b85021d02059c9ac8a211ef3804ea8fdde
      branchName: main

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

BuildRun 资源将镜像构造的任务委派给 Tekton TaskRun 资源，该资源运行所有步骤，直到任务完成或任务中发生失败为止。

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

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

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

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

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

作为集群管理员，您可以验证集群范围的代理设置。

作为集群管理员，您可以验证环境变量，以确保为 OpenShift Container Platform 集群上的 Red Hat OpenShift 构建正确配置了代理设置。