签名密钥配置

概述

要在 Tekton Chains 中启用工件签名,您需要生成并配置签名密钥。本文档介绍如何针对不同的签名方法生成和配置签名密钥。

生成签名密钥

WARNING

签名密钥用于为工件生成签名信息。请妥善保管。

使用 Cosign

cosign generate-key-pair 会替换 signing-secrets 已持有的密钥对,除非 Secret 是不可变的,否则不会请求确认。运行该命令之前,请使用下方说明后显示的检查命令读取 Secret 的密钥名称;以 null (null) has no keys 结尾的错误表示 Secret 不包含任何数据。如果输出列出 cosign.key,则表示 Secret 已包含签名密钥:请先按照获取签名 Secret中的说明将其导出,因为使用该密钥创建的签名只能通过其 cosign.pub 进行验证。当 generateSigningSecret 在 TektonConfig 的 spec.chain 中为 true 时,不要运行此命令:此时 Operator 会自行将密钥对写入 signing-secrets。

您可以使用 cosign 工具生成签名密钥对。单独运行 read -rs 行,输入密码并按 Enter,然后运行其他行。在不支持带括号粘贴的 shell 中(例如 5.1 之前的 bash),read 会将粘贴代码块的下一行作为密码:

read -rs COSIGN_PASSWORD

然后运行:

export COSIGN_PASSWORD
cosign generate-key-pair k8s://tekton-pipelines/signing-secrets
unset COSIGN_PASSWORD

注意:

  • 您需要安装 cosign CLI 并拥有 Kubernetes 集群的访问权限。生成密钥会在 tekton-pipelines 中写入 Secret signing-secrets,下方的检查命令以及获取签名 Secret中的导出操作会读取该 Secret,而重启 Tekton Chains中的重启操作会删除其中的 Pods。这些步骤需要对 tekton-pipelines 中的 Secrets 和 Pods 具有相应权限,通常需要集群管理员权限
  • COSIGN_PASSWORD 是用于加密签名密钥的密码。在 read -rs COSIGN_PASSWORD 之后,输入密码并按 Enter:read -rs 不会显示该密码,因此密码不会出现在屏幕上或 shell 历史记录中。创建密钥对后,unset 会将其从 shell 中移除。请在 bash 或 zsh 中运行这些命令:在 POSIX sh(例如 dash)中,read -rs 会失败并使变量为空
  • tekton-pipelines 是部署 Chains 组件的命名空间(默认为 tekton-pipelines)
  • signing-secrets 是用于存储签名密钥的 Secret 名称
  • 下方的检查命令以及获取签名 Secret中的恢复和复制命令使用 jq CLI

执行后,检查 Secret 是否包含这三个密钥。该命令只打印密钥名称,不会打印私钥或密码:

$ kubectl get secret signing-secrets -n tekton-pipelines -o json | jq '.data | keys'

[
  "cosign.key",
  "cosign.password",
  "cosign.pub"
]

cosign 会将密钥对写入 signing-secrets,并使 Secret 成为不可变 Secret(immutable: true),即使该 Secret 已存在也是如此,因此之后无法更改其中的数据。再次对这个不可变 Secret 运行此命令会失败,并显示以下错误;而对于非不可变的 Secret(例如由 Operator 重新创建的 Secret),该命令会替换密钥:

Error: updating secret signing-secrets in ns <namespace>: Secret "signing-secrets" is invalid: data: Forbidden: field is immutable when `immutable` is set

获取签名公钥

TIP

如果您没有权限,可以请求管理员获取公钥。

export NAMESPACE=<tekton-pipelines>
kubectl get secret -n $NAMESPACE signing-secrets -o jsonpath='{.data.cosign\.pub}' | base64 -d > cosign.pub

获取签名 Secret

导出的文件包含私钥及其密码。子 shell 中的 umask 077 会创建一个仅您可读取的文件。rm -f 会先删除旧副本,因为 > 会保留现有文件的权限:

export NAMESPACE=<tekton-pipelines>
(umask 077 && rm -f signing-secrets.json && kubectl get secret -n $NAMESPACE signing-secrets -o json > signing-secrets.json)

该文件是整个 Secret 的副本。其中的 metadata(例如 uid 和 resourceVersion)属于导出的 Secret,因此不要直接使用该文件再次创建 Secret。要恢复密钥,例如在禁用并重新启用 Chains 后 signing-secrets 恢复但不包含数据时,请仅将文件中的 data 合并到 Secret 中;Operator 会创建不带 immutable 的 signing-secrets,因此仍然可以设置其数据。data 会保留密钥名称:Chains 从 Secret signing-secrets 的 cosign.key 中读取私钥,并从 cosign.password 中读取其密码:

export NAMESPACE=<tekton-pipelines>
jq '{data: .data}' signing-secrets.json | kubectl patch secret signing-secrets -n $NAMESPACE --type merge --patch-file /dev/stdin

然后按照重启 Tekton Chains中的说明重启 Chains。

要在另一个命名空间中使用该密钥(例如使用该密钥签名的 pipeline 所在的命名空间),请使用该文件在其中创建 Secret 的副本。jq 过滤器仅保留 Secret 的名称、类型和 data,不会保留导出 Secret 中的其他 metadata,并且密钥不会出现在命令行中:

jq '{apiVersion, kind, type, metadata: {name: .metadata.name}, data}' signing-secrets.json | kubectl create -n <namespace> -f -

任何能够读取该命名空间中 Secrets 的人,或能够在其中运行挂载该副本的 Pod 的人,都可以使用与 Chains 相同的密钥进行签名。请限制该命名空间中的 Secret 访问权限,并在不再需要该副本时将其删除。

不再需要该文件时,请将其删除(rm -f signing-secrets.json)。

重启 Tekton Chains

配置签名密钥后,重启 Tekton Chains 组件使其生效:

kubectl delete pods -n tekton-pipelines -l app=tekton-chains-controller

等待组件启动:

$ kubectl get pods -n tekton-pipelines -l app=tekton-chains-controller -w

NAME                                        READY   STATUS    RESTARTS   AGE
tekton-chains-controller-55876dfbbd-5wv5z   1/1     Running   0          1m30s

推荐设置

启用时机:当合规性要求平台上构建的每个镜像和 attestation 都带有可验证的签名时启用签名。在 Chains 命名空间的 signing-secrets Secret 中为集群配置一次密钥对;之后,一个公钥即可验证 Chains 在该集群上签名的所有内容。

推荐值:将 cosign 密钥对保存在 Chains 命名空间中的 signing-secrets Secret(默认为 tekton-pipelines)中,并按照生成签名密钥中的说明创建。将镜像签名,以及其结果报告镜像的 TaskRuns 和 PipelineRuns 的 attestations,存储在该镜像旁边的 OCI registry 中(其结果未报告镜像的 run 没有可供将这些内容存储在其旁边的镜像),并通过 TektonConfig 进行配置(参见Chains 配置):

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  chain:
    disabled: 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
    transparency.enabled: false

将示例保存为 tektonconfig-chains.yaml,并将其合并到现有的 TektonConfig 中。合并补丁只会更改文件中的键,并保留 TektonConfig 的其他字段。它需要对 TektonConfig 执行 patch 的权限;该资源的作用域为集群,通常需要集群管理员权限:

kubectl patch tektonconfig config --type merge --patch-file tektonconfig-chains.yaml

不要将 kubectl apply -f 用于仅包含 TektonConfig 部分内容的文件:之后对另一个部分文件执行的 kubectl apply -f 会删除该文件设置但后续文件未包含的字段。然后按照检查变更是否已传递到 Chains中的说明,检查变更是否已传递到 chains-config。直接编辑 chains-config ConfigMap 会立即生效,但 operator 下次重新生成 ConfigMap 时会丢弃该编辑,例如 TektonConfig 中的 spec.chain 发生任何变更后。

对于包含 CustomRun 的 PipelineRun,例如手动审批步骤中的 ApprovalTask,Chains 不会创建 PipelineRun 级别的签名或 provenance(参见 tektoncd/chains#1210)。Chains 根据该 PipelineRun 的 TaskRuns 创建的镜像签名和 attestations 不受影响。

除非配置了由你控制的 Rekor 实例,否则请将 transparency.enabled 保持为默认值 false。如果在没有 transparency.url 的情况下启用它,Chains 会将内容上传到 https://rekor.sigstore.dev 上的公共 Rekor;如果集群可以访问该服务,还会将每个已签名 run 的签名和 provenance(包括 registry 主机名、镜像引用和 Task 详细信息)发布到该公共的只追加日志中,从而使这些构建信息公开。若要使用自己的 Rekor 实例,还需在 spec.chain 中将 transparency.url 设置为该实例的地址。签名本身不会强制执行任何操作:请在部署时将签名和 attestations 的验证作为单独步骤,如镜像签名验证和构建系统 provenance 验证中所述。

前提条件。Tekton Chains 已部署(默认通过 TektonConfig 部署),cosign CLI 可以访问集群以生成密钥对,并且在创建密钥后已重启 Tekton Chains controller(参见重启 Tekton Chains)。构建 Tasks 必须将镜像 URL 和 digest 作为带有类型提示的结果进行报告(参见类型提示)。对于 PipelineRun attestation,Pipeline 还必须将镜像 URL 和 digest 作为带有类型提示的 Pipeline 结果向上传递,例如从构建 Task 的结果中获取的 IMAGE_URL 和 IMAGE_DIGEST:使用默认的 artifacts.pipelinerun.enable-deep-inspection: "false" 时,Chains 只读取 Pipeline 结果。如果这些结果缺失,Chains 不会存储 PipelineRun attestation,而是记录 No image subject to attest for tekton.dev/v1/PipelineRun/<namespace>/<name>. Skipping upload to registry,并仍将该 run 标记为已签名。将 enable-deep-inspection 设置为 "true" 后,Chains 还会读取该 run 的 TaskRuns 结果(参见PipelineRun 配置);本指南不使用此选项。Chains 还需要目标 registry 的 push 凭据(参见OCI registry 身份验证)。

参考