Chains 配置

概述

Tekton Chains 是一个 Kubernetes Custom Resource Definition (CRD) controller,可用于管理 Tekton 中的供应链安全。本节介绍如何配置 Tekton Chains。

配置

Chains 配置存储在名为 chains-config 的 ConfigMap 中,该 ConfigMap 位于 tekton-pipelines 或 tekton-chains namespace 中。直接对此 ConfigMap 所做的更改只会持续到 Operator 重新生成该 ConfigMap 为止,因此请通过 TektonConfig 配置 Chains(请参阅下面的警告)。

默认情况下,Tekton Chains 会通过 TektonConfig 资源自动部署。您可以修改 TektonConfig 资源来配置 Chains。

基本上,Tekton Operator 会将 Chains 配置从 TektonConfig 资源同步到名为 chain 的 TektonChain 资源,最终反映到 chains-config ConfigMap 中。每次更改后,请检查更改是否已传达到位,具体说明请参阅检查更改是否已传达到 Chains。

WARNING

如果您通过 TektonConfig 部署 Chains,则必须通过 TektonConfig 配置 Chains。

如果您只修改 chains-config ConfigMap 中的配置,而该配置未同步到 TektonChain 资源,则配置可能会丢失。

当 Operator 生成的 Chains 配置发生更改时(例如 TektonConfig 中的 spec.chain 发生更改后),Operator 会根据 TektonConfig 重新创建 chains-config。您在 ConfigMap 中手动设置的每个值都会丢失,包括 Operator 不管理的键。

TIP

Chains 本身接受 chains-config 中的某些值,但 Operator 会拒绝这些值,例如 artifacts.taskrun.format 的 slsa/v2alpha4 和 artifacts.taskrun.storage 的 archivista。Operator 的验证 webhook 会接受 TektonConfig 的 spec.chain 中的此类值,但 Operator 会将 spec.chain 复制到名为 chain 的 TektonChain 资源中,而同一个 webhook 会在该资源中拒绝此值,并显示类似 admission webhook "validation.webhook.operator.tekton.dev" denied the request: validation failed: invalid value: slsa/v2alpha4: spec.artifacts.taskrun.format 的消息。

自行创建 TektonChain 并不能规避此问题。Webhook 会以相同方式对其进行验证,并且只接受名称 chain;当 TektonConfig 中的 spec.chain.disabled 为 true 时,Operator 会删除名为 chain 的 TektonChain,以及其中的签名密钥(请参阅下面的 disabled)。

下面简单演示配置 Chains 的不同方式。

在 chains-config ConfigMap 中配置

以下是 chains-config ConfigMap 示例:

apiVersion: v1
data:
  artifacts.oci.format: simplesigning
  artifacts.oci.storage: oci
  artifacts.pipelinerun.format: in-toto
  artifacts.pipelinerun.storage: oci
  artifacts.taskrun.format: in-toto
  artifacts.taskrun.storage: oci
  transparency.enabled: "false"
kind: ConfigMap
metadata:
  name: chains-config
TIP

布尔值采用字符串形式,例如 "true" 或 "false"。

Explanation of YAML fields
  • artifacts.oci.format:attestation 的格式。
  • artifacts.oci.storage:attestation 的存储后端。
  • artifacts.pipelinerun.format:PipelineRuns 的 attestation 格式。
  • artifacts.pipelinerun.storage:PipelineRuns 的 attestation 存储后端。
  • artifacts.taskrun.format:TaskRuns 的 attestation 格式。
  • artifacts.taskrun.storage:TaskRuns 的 attestation 存储后端。

在 TektonConfig 中配置

在 TektonConfig 资源中,Chains 的配置大致如下:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  chain:
    disabled: false
    generateSigningSecret: false

    artifacts.oci.format: simplesigning
    artifacts.oci.storage: oci
    artifacts.pipelinerun.format: in-toto
    artifacts.pipelinerun.storage: oci
    artifacts.taskrun.format: in-toto
    artifacts.taskrun.storage: oci

    signers.x509.fulcio.enabled: false
    transparency.enabled: false

    options:
      deployments:
        tekton-chains-controller:
          spec:
            template:
              spec:
                containers:
                - name: tekton-chains-controller
                  env:
                    - name: SIGSTORE_ID_TOKEN
                      value: "<your-id-token>"
                  resources: {}

此示例将使用 Fulcio 的无密钥签名(signers.x509.fulcio.enabled)和透明日志(transparency.enabled)保持禁用状态。如果启用其中任一项,Chains 会将数据发送到 signers.x509.fulcio.address 或 transparency.url 中设置的服务。这些配置的默认值是下面 Sigstore Features Configuration 中列出的公共 Sigstore 服务,因此在使用默认值时,数据会离开集群。

TIP

布尔值采用原始类型,例如 true 或 false。

Explanation of YAML fields
  • spec.chain:此部分包含 Chains 的配置。Operator 会将其复制到名为 chain 的 TektonChain 资源中。
    • disabled:是否禁用 Chains。设置为 true 时,Operator 会删除名为 chain 的 TektonChain 资源,并同时删除 Chains namespace(默认为 tekton-pipelines)中的 Secret signing-secrets,该 Secret 保存签名密钥及其密码。无法从集群中恢复该密钥:再次启用 Chains 时,signing-secrets 会使用随附的 generateSigningSecret: false 重新变为空,或者在 generateSigningSecret 为 true 时生成新的密钥对;两者都不是旧密钥。设置 disabled: true 前,请按照获取签名 Secret 中的说明导出 Secret,并将文件保存在安全位置。再次启用 Chains 后,按照该页面中的说明从文件恢复密钥。禁用 Chains 还会在 Chains 已处理的运行上保留其 finalizer(PipelineRun 上的 chains.tekton.dev/pipelinerun,TaskRun 上的 chains.tekton.dev/taskrun);删除运行时,Chains controller 会移除该 finalizer。Chains 禁用期间,无论是 Pruner、kubectl delete 还是 namespace 的删除请求发起此类运行的删除,删除都不会完成。请重新启用 Chains,使这些删除操作完成。若要在 Chains 保持禁用的情况下删除此类运行,请使用 kubectl patch pipelinerun <name> -n <namespace> --type merge --patch-file finalizers.yaml 移除其 finalizer(TaskRun 使用 taskrun),其中 finalizers.yaml 包含一行 metadata:,后跟一行向右缩进两个空格的 finalizers: []。该补丁会移除运行的每个 finalizer:请先使用 kubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.metadata.finalizers}' 读取它们;如果存在其他 finalizer,请在文件中列出这些 finalizer,而不是 []。Chains 已处理的 PipelineRun 中的 TaskRuns 带有自己的 finalizer,需要应用相同的补丁,并以 taskrun 替代 pipelinerun。
    • generateSigningSecret:是否生成签名 Secret。
    • controllerEnvs:Tekton Chains controller 的环境变量。
      • TektonChain 中唯一接受的名称是 MONGO_SERVER_URL。TektonConfig 接受其他名称,但 Operator 会将其复制到 TektonChain,Webhook 会在其中拒绝这些名称,例如显示 invalid key name "SIGSTORE_ID_TOKEN": supported keys are MONGO_SERVER_URL。请按照示例,在 options 中设置其他变量。
      • name:环境变量的名称。
      • value:环境变量的值。
    • options:Tekton Chains controller 的选项。
      • deployments.tekton-chains-controller:Tekton Chains controller 的部署选项。
        • spec.template.spec.containers.env.SIGSTORE_ID_TOKEN:Tekton Chains controller 的 ID token。
      • 更多详细支持信息请参阅作为选项的其他字段
    • TektonChain 中还存在如下配置,最终会同步到 chains-config ConfigMap。以下列表仅给出示例,并不完整。
      • artifacts.oci.format
      • artifacts.oci.storage
      • artifacts.pipelinerun.enable-deep-inspection
      • artifacts.pipelinerun.format
      • artifacts.pipelinerun.storage
      • artifacts.taskrun.format
      • artifacts.taskrun.storage
      • storage.oci.repository.insecure
      • signers.x509.fulcio.enabled
      • signers.x509.fulcio.address
      • signers.x509.fulcio.issuer
      • transparency.enabled
      • transparency.url

检查更改是否已传达到 Chains

TektonConfig 接受 webhook 随后会在 TektonChain 中拒绝的 spec.chain 值,而编辑操作本身不会报告错误。每次更改 spec.chain 后,请检查 TektonConfig 是否已就绪,以及 chains-config 是否包含新值。读取 chains-config 需要具备对 Chains namespace(默认为 tekton-pipelines)中 ConfigMap 的读取权限,通常只有集群管理员具备此权限:

kubectl get tektonconfig config
kubectl get tektonconfig config -o jsonpath='{range .status.conditions[*]}{.type}={.status} {.message}{"\n"}{end}'
kubectl get configmap chains-config -n tekton-pipelines -o yaml

READY 必须为 True,每个 condition 都必须为 True,并且 chains-config 的 data 必须显示您设置的值。当 webhook 拒绝 TektonChain 中的值时,ComponentsReady condition 为 False,并显示消息 Components not in ready state: TektonChain: <error>;Operator 会在 Chains 处停止 reconcile:chains-config 保留之前的值,并且在 Chains 之后由 Operator reconcile 的 TektonResult 及其他组件不会更新,直到您修正该值。

TaskRun 配置

Key描述支持的值默认值
artifacts.taskrun.format用于存储 TaskRun 负载的格式。in-toto、slsa/v1、slsa/v2alpha3、slsa/v2alpha4(Operator 会拒绝 slsa/v2alpha4,请参见上面的提示)in-toto
artifacts.taskrun.storage用于存储 TaskRun 签名的存储后端。可以使用逗号分隔的列表指定多个后端(“tekton,oci”)。要禁用 TaskRun 工件输入,请使用空字符串("")。tekton、oci、gcs、docdb、grafeas、archivista(Operator 会拒绝 archivista)oci(由 Operator 设置)
artifacts.taskrun.signer用于对 TaskRun 负载进行签名的签名后端。x509、kms、none(Operator 会拒绝 none)x509

说明

  • slsa/v1 是 in-toto 的别名,用于向后兼容。
  • 如果存储为 oci,证明将与存储的 OCI 工件本身一起存储。有关更多信息,请参阅 cosign 文档。
  • 如果存储为 tekton,证明将存储在 Tekton TaskRun 的 annotations 中,因此会随 TaskRun 一起删除,例如 Pruner 删除它时。

PipelineRun 配置

与 TaskRun 类似,您可以配置 PipelineRun 的签名和存储。

Key描述支持的值默认值
artifacts.pipelinerun.format用于存储 PipelineRun 负载的格式。in-toto、slsa/v1、slsa/v2alpha3、slsa/v2alpha4(Operator 会拒绝 slsa/v2alpha4,请参见上面的提示)in-toto
artifacts.pipelinerun.storage用于存储 PipelineRun 签名的存储后端。可以使用逗号分隔的列表指定多个后端(“tekton,oci”)。要禁用 PipelineRun 工件输入,请使用空字符串("")。tekton、oci、gcs、docdb、grafeas、archivista(Operator 会拒绝 archivista)oci(由 Operator 设置)
artifacts.pipelinerun.signer用于对 PipelineRun 负载进行签名的签名后端。x509、kms、none(Operator 会拒绝 none)x509
artifacts.pipelinerun.enable-deep-inspection此布尔选项用于配置 Chains 是否应检查子 TaskRun,以捕获 PipelineRun 中的输入和输出。“false”表示 Chains 仅检查 Pipeline 级别的结果,而“true”表示 Chains 同时检查 Pipeline 级别和 Task 级别的结果。“true”、“false”“false”
  • 如果存储为 oci,证明将与存储的 OCI 工件本身一起存储。有关更多信息,请参阅 cosign 文档。使用 enable-deep-inspection: "false" 时,PipelineRun 必须在带有类型提示的 Pipeline 结果中报告镜像;否则 Chains 不会在注册表中存储 PipelineRun 证明(请参阅签名密钥配置)。
  • 如果存储为 tekton,证明将存储在 Tekton PipelineRun 的 annotations 中,因此会随 PipelineRun 一起删除,例如 Pruner 删除它时。

OCI 配置

Key描述支持的值默认值
artifacts.oci.format用于存储 OCI 负载的格式。simplesigningsimplesigning
artifacts.oci.storage用于存储 OCI 签名的存储后端。可以使用逗号分隔的列表指定多个后端(“oci,tekton”)。要禁用 OCI 工件输入,请使用空字符串("")。tekton、oci、gcs、docdb、grafeas、archivista(Operator 会拒绝 archivista)oci
artifacts.oci.signer用于对 OCI 负载进行签名的签名后端。x509、kms、none(Operator 会拒绝 none)x509
  • 如果存储为 oci,证明将与存储的 OCI 工件本身一起存储。有关更多信息,请参阅 cosign 文档。
  • 如果存储为 tekton,证明将存储在 Tekton TaskRun 或 PipelineRun 的 annotations 中,因此会随运行一起删除。

存储配置

Chains 支持多个用于存储证明和签名的存储后端。 下面列出了一些较常用的后端;有关更详细的配置,请参阅存储配置

Key描述支持的值默认值
storage.oci.repository用于存储 OCI 签名和证明的 OCI 仓库如果未定义此项,且 artifacts.{oci,taskrun}.storage 包含 oci 存储,则证明将与存储的 OCI 工件本身一起存储。(GCP 示例)定义此值后,OCI bundle 将存储在指定位置,而不是与镜像一起存储。有关更多信息,请参阅 cosign 文档。
storage.oci.repository.insecure连接 OCI 仓库时是否使用不安全连接true、falsefalse

说明

  • storage.oci.repository.insecure: true 会关闭 Chains 向其推送签名和证明的注册表的 TLS 证书验证,包括携带推送凭据的请求,并且 Chains 会记录 Using insecure OCI registry connection. This skips TLS certificate verification and poses security risks. Only use this in testing or development environments.。Alauda DevOps Pipelines 随附的 Chains build 还允许与这些注册表建立纯 HTTP 连接。仅将其用于测试或开发注册表,例如使用自签名证书的注册表,切勿在生产环境中使用。要将其关闭,请将 storage.oci.repository.insecure 设置为 false(默认值),或移除此键,然后按照检查更改是否已传递到 Chains中的说明,确认其中不再包含 true 的 chains-config。

Sigstore 功能配置

透明日志

Key描述支持的值默认值
transparency.enabled是否启用透明日志。"true"、"false"、"manual""false"
transparency.url透明日志的 URL。"https://rekor.sigstore.dev"

注意:如果将 transparency.enabled 设置为 manual,则只有带有以下注解的 TaskRun 和 PipelineRun 才会上传到透明日志:

chains.tekton.dev/transparency-upload: "true"

使用 Fulcio 进行无密钥签名

Key描述支持的值默认值
signers.x509.fulcio.enabled是否启用来自 fulcio 的自动证书。"true"、"false""false"
signers.x509.fulcio.address启用后,用于请求证书的 Fulcio 地址"https://fulcio.sigstore.dev"
signers.x509.fulcio.issuer预期的 OIDC issuer。"https://oauth2.sigstore.dev/auth"
signers.x509.fulcio.provider用于请求 ID Token 的 provider"google"、"spiffe"、"github"、"filesystem"未设置,将尝试每个 provider。
signers.x509.identity.token.file包含 ID Token 的文件路径。
signers.x509.tuf.mirror.urlTUF 服务器 URL。预期存在 $TUF_URL/root.json。"https://tuf-repo-cdn.sigstore.dev"

参考