Chains Configuration

Overview

Tekton Chains is a Kubernetes Custom Resource Definition (CRD) controller that allows you to manage your supply chain security in Tekton. This document describes how to configure Tekton Chains.

Configuration

Chains configuration is stored in a ConfigMap named chains-config in the tekton-pipelines or tekton-chains namespace. A change made directly in this ConfigMap lasts only until the Operator regenerates it, so configure Chains through TektonConfig (see the warning below).

By default, Tekton Chains is deployed automatically through the TektonConfig resource. You can modify the TektonConfig resource to configure Chains.

Essentially, Tekton Operator will synchronize the Chains configuration from the TektonConfig resource to the TektonChain resource named chain, and finally reflect in the chains-config ConfigMap. After each change, check that it arrived, as described in Check That a Change Reached Chains.

WARNING

If you deploy Chains through TektonConfig, you must configure Chains through TektonConfig.

If you only modify the configuration in the chains-config ConfigMap, and it is not synchronized to the TektonChain resource, the configuration may be lost.

When the Chains configuration that the Operator generates changes, for example after spec.chain in TektonConfig changes, the Operator recreates chains-config from TektonConfig. Every value that you set by hand in the ConfigMap is lost, including keys that the Operator does not manage.

TIP

Chains itself accepts some values in chains-config that the Operator rejects, for example slsa/v2alpha4 for artifacts.taskrun.format and archivista for artifacts.taskrun.storage. The Operator's validation webhook accepts such a value in spec.chain of TektonConfig, but the Operator copies spec.chain into the TektonChain resource named chain, and the same webhook rejects it there with a message such as admission webhook "validation.webhook.operator.tekton.dev" denied the request: validation failed: invalid value: slsa/v2alpha4: spec.artifacts.taskrun.format.

Creating a TektonChain yourself does not avoid this. The webhook validates it in the same way and accepts only the name chain, and when spec.chain.disabled is true in TektonConfig, the Operator deletes the TektonChain named chain, together with the signing key (see disabled below).

Below is a simple demonstration of the different ways to configure Chains.

Configuration in chains-config ConfigMap

The following is an example of the 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

The boolean values are strings, such as "true" or "false".

Explanation of YAML fields
  • artifacts.oci.format: The format of the attestations.
  • artifacts.oci.storage: The storage backend for the attestations.
  • artifacts.pipelinerun.format: The format of the attestations for PipelineRuns.
  • artifacts.pipelinerun.storage: The storage backend for the attestations for PipelineRuns.
  • artifacts.taskrun.format: The format of the attestations for TaskRuns.
  • artifacts.taskrun.storage: The storage backend for the attestations for TaskRuns.

Configuration in TektonConfig

At the TektonConfig resource, the configuration of Chains is roughly as follows:

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: {}

The sample keeps keyless signing with Fulcio (signers.x509.fulcio.enabled) and the transparency log (transparency.enabled) disabled. If you enable either, Chains sends data to the service set in signers.x509.fulcio.address or transparency.url. Their defaults are the public Sigstore services listed under Sigstore Features Configuration below, so with the defaults that data leaves the cluster.

TIP

The boolean values are the original type, such as true or false.

Explanation of YAML fields
  • spec.chain: This section contains the configuration for Chains. The Operator copies it into the TektonChain resource named chain.
    • disabled: Whether to disable Chains. With true, the Operator deletes the TektonChain resource named chain and, with it, the Secret signing-secrets in the Chains namespace (default tekton-pipelines), which holds the signing key and its password. The key cannot be recovered from the cluster: when you enable Chains again, signing-secrets comes back empty with the shipped generateSigningSecret: false, or with a new key pair when generateSigningSecret is true; neither is the old key. Before you set disabled: true, export the Secret as described in Get the Signing Secret and keep the file in a safe place. After you enable Chains again, restore the key from that file as described there. Disabling Chains also leaves its finalizer on the runs that Chains has handled (chains.tekton.dev/pipelinerun on a PipelineRun, chains.tekton.dev/taskrun on a TaskRun); the Chains controller removes it when the run is deleted. While Chains is disabled, the deletion of such a run does not complete, whether the Pruner, kubectl delete or the deletion of the namespace requests it. Enable Chains again to let these deletions complete. To delete one such run while Chains stays disabled, remove its finalizers with kubectl patch pipelinerun <name> -n <namespace> --type merge --patch-file finalizers.yaml (taskrun for a TaskRun), where finalizers.yaml holds the line metadata: followed by the line finalizers: [] indented by two spaces. The patch removes every finalizer of the run: read them first with kubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.metadata.finalizers}' and, if there are others, list those in the file instead of []. The TaskRuns of a PipelineRun that Chains has handled carry their own finalizer and need the same patch, with taskrun in place of pipelinerun.
    • generateSigningSecret: Whether to generate a signing secret.
    • controllerEnvs: The environment variables for the Tekton Chains controller.
      • The only name accepted in a TektonChain is MONGO_SERVER_URL. TektonConfig accepts other names, but the Operator copies them into the TektonChain, where the webhook rejects them, for example with invalid key name "SIGSTORE_ID_TOKEN": supported keys are MONGO_SERVER_URL. Set other variables in options, as in the sample.
      • name: The name of the environment variable.
      • value: The value of the environment variable.
    • options: The options for the Tekton Chains controller.
      • deployments.tekton-chains-controller: The deployment options for the Tekton Chains controller.
        • spec.template.spec.containers.env.SIGSTORE_ID_TOKEN: The ID token for the Tekton Chains controller.
      • More detailed support can be found in Additional fields as options
    • Configurations such as the following also exist in TektonChain and will ultimately be synchronized to the chains-config ConfigMap. The list gives examples; it is not complete.
      • 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

Check That a Change Reached Chains

TektonConfig accepts a spec.chain value that the webhook later rejects in the TektonChain, and the edit itself reports no error. After each change to spec.chain, check that TektonConfig is ready and that chains-config holds the new values. Reading chains-config needs read access to ConfigMaps in the Chains namespace (tekton-pipelines by default), usually a cluster administrator:

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 must be True, every condition must be True, and the data of chains-config must show the values that you set. When the webhook rejects the value in the TektonChain, the ComponentsReady condition is False with the message Components not in ready state: TektonChain: <error>, and the Operator stops its reconcile at Chains: chains-config keeps the previous values, and the TektonResult and the other components that the Operator reconciles after Chains are not updated until you correct the value.

TaskRun Configuration

KeyDescriptionSupported ValuesDefault
artifacts.taskrun.formatThe format to store TaskRun payloads in.in-toto, slsa/v1, slsa/v2alpha3, slsa/v2alpha4 (the Operator rejects slsa/v2alpha4, see the tip above)in-toto
artifacts.taskrun.storageThe storage backend to store TaskRun signatures in. Multiple backends can be specified with comma-separated list ("tekton,oci"). To disable the TaskRun artifact input an empty string ("").tekton, oci, gcs, docdb, grafeas, archivista (the Operator rejects archivista)oci (set by the Operator)
artifacts.taskrun.signerThe signature backend to sign TaskRun payloads with.x509, kms, none (the Operator rejects none)x509

Explanation

  • slsa/v1 is an alias of in-toto for backwards compatibility.
  • If the storage is oci, the attestations will be stored alongside the stored OCI artifact itself. See cosign documentation for additional information.
  • If the storage is tekton, the attestations will be stored in the Tekton TaskRun's annotations, so they are deleted with the TaskRun, for example when the Pruner deletes it.

PipelineRun Configuration

Similar to TaskRuns, you can configure PipelineRun signing and storage.

KeyDescriptionSupported ValuesDefault
artifacts.pipelinerun.formatThe format to store PipelineRun payloads in.in-toto, slsa/v1, slsa/v2alpha3, slsa/v2alpha4 (the Operator rejects slsa/v2alpha4, see the tip above)in-toto
artifacts.pipelinerun.storageThe storage backend to store PipelineRun signatures in. Multiple backends can be specified with comma-separated list ("tekton,oci"). To disable the PipelineRun artifact input an empty string ("").tekton, oci, gcs, docdb, grafeas, archivista (the Operator rejects archivista)oci (set by the Operator)
artifacts.pipelinerun.signerThe signature backend to sign PipelineRun payloads with.x509, kms, none (the Operator rejects none)x509
artifacts.pipelinerun.enable-deep-inspectionThis boolean option will configure whether Chains should inspect child taskruns in order to capture inputs/outputs within a pipelinerun. "false" means that Chains only checks pipeline level results, whereas "true" means Chains inspects both pipeline level and task level results."true", "false""false"
  • If the storage is oci, the attestations will be stored alongside the stored OCI artifact itself. See cosign documentation for additional information. With enable-deep-inspection: "false", the PipelineRun must report the image in type-hinted Pipeline results; otherwise Chains stores no PipelineRun attestation in the registry (see Signing Key Configuration).
  • If the storage is tekton, the attestations will be stored in the Tekton PipelineRun's annotations, so they are deleted with the PipelineRun, for example when the Pruner deletes it.

OCI Configuration

KeyDescriptionSupported ValuesDefault
artifacts.oci.formatThe format to store OCI payloads in.simplesigningsimplesigning
artifacts.oci.storageThe storage backend to store OCI signatures in. Multiple backends can be specified with comma-separated list ("oci,tekton"). To disable the OCI artifact input an empty string ("").tekton, oci, gcs, docdb, grafeas, archivista (the Operator rejects archivista)oci
artifacts.oci.signerThe signature backend to sign OCI payloads with.x509, kms, none (the Operator rejects none)x509
  • If the storage is oci, the attestations will be stored alongside the stored OCI artifact itself. See cosign documentation for additional information.
  • If the storage is tekton, the attestations will be stored in the Tekton TaskRun or PipelineRun's annotations, so they are deleted with the run.

Storage Configuration

Chains supports multiple storage backends for storing attestations and signatures. A few of the more common ones are listed below, for more detailed configuration, please refer to Storage Configuration

KeyDescriptionSupported ValuesDefault
storage.oci.repositoryThe OCI repo to store OCI signatures and attestation inIf left undefined and one of artifacts.{oci,taskrun}.storage includes oci storage, attestations will be stored alongside the stored OCI artifact itself. (example on GCP) Defining this value results in the OCI bundle stored in the designated location instead of alongside the image. See cosign documentation for additional information.
storage.oci.repository.insecureWhether to use insecure connection when connecting to the OCI repositorytrue, falsefalse

Explanation

  • storage.oci.repository.insecure: true turns off TLS certificate verification for the registries that Chains pushes signatures and attestations to, including the requests that carry the push credentials, and Chains logs Using insecure OCI registry connection. This skips TLS certificate verification and poses security risks. Only use this in testing or development environments. The Chains build shipped with Alauda DevOps Pipelines also allows plain HTTP connections to these registries. Use it only with test or development registries, for example one with a self-signed certificate, and never in production. To turn it off, set storage.oci.repository.insecure to false (the default) or remove the key, then check that chains-config no longer holds true for it, as described in Check That a Change Reached Chains.

Sigstore Features Configuration

Transparency Log

KeyDescriptionSupported ValuesDefault
transparency.enabledWhether to enable transparency."true", "false", "manual""false"
transparency.urlThe URL of the transparency log."https://rekor.sigstore.dev"

Note: If transparency.enabled is set to manual, then only TaskRuns and PipelineRuns with the following annotation will be uploaded to the transparency log:

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

Keyless Signing with Fulcio

KeyDescriptionSupported ValuesDefault
signers.x509.fulcio.enabledWhether to enable automatic certificates from fulcio."true", "false""false"
signers.x509.fulcio.addressFulcio address to request certificate from, if enabled"https://fulcio.sigstore.dev"
signers.x509.fulcio.issuerExpected OIDC issuer."https://oauth2.sigstore.dev/auth"
signers.x509.fulcio.providerProvider to request ID Token from"google", "spiffe", "github", "filesystem"Unset, each provider will be attempted.
signers.x509.identity.token.filePath to file containing ID Token.
signers.x509.tuf.mirror.urlTUF server URL. $TUF_URL/root.json is expected to be present."https://tuf-repo-cdn.sigstore.dev"

References