Chains Configuration
TOC
OverviewConfigurationConfiguration inchains-config ConfigMapConfiguration in TektonConfigCheck That a Change Reached ChainsTaskRun ConfigurationPipelineRun ConfigurationOCI ConfigurationStorage ConfigurationSigstore Features ConfigurationTransparency LogKeyless Signing with FulcioReferencesOverview
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.
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.
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:
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:
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.
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 theTektonChainresource namedchain.disabled: Whether to disable Chains. Withtrue, the Operator deletes theTektonChainresource namedchainand, with it, the Secretsigning-secretsin the Chains namespace (defaulttekton-pipelines), which holds the signing key and its password. The key cannot be recovered from the cluster: when you enable Chains again,signing-secretscomes back empty with the shippedgenerateSigningSecret: false, or with a new key pair whengenerateSigningSecretistrue; neither is the old key. Before you setdisabled: 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/pipelinerunon aPipelineRun,chains.tekton.dev/taskrunon aTaskRun); 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 deleteor 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 withkubectl patch pipelinerun <name> -n <namespace> --type merge --patch-file finalizers.yaml(taskrunfor aTaskRun), wherefinalizers.yamlholds the linemetadata:followed by the linefinalizers: []indented by two spaces. The patch removes every finalizer of the run: read them first withkubectl get pipelinerun <name> -n <namespace> -o jsonpath='{.metadata.finalizers}'and, if there are others, list those in the file instead of[]. The TaskRuns of aPipelineRunthat Chains has handled carry their own finalizer and need the same patch, withtaskrunin place ofpipelinerun.generateSigningSecret: Whether to generate a signing secret.controllerEnvs: The environment variables for the Tekton Chains controller.- The only name accepted in a
TektonChainisMONGO_SERVER_URL.TektonConfigaccepts other names, but the Operator copies them into theTektonChain, where the webhook rejects them, for example withinvalid key name "SIGSTORE_ID_TOKEN": supported keys are MONGO_SERVER_URL. Set other variables inoptions, as in the sample. name: The name of the environment variable.value: The value of the environment variable.
- The only name accepted in a
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
TektonChainand will ultimately be synchronized to thechains-configConfigMap. The list gives examples; it is not complete.artifacts.oci.formatartifacts.oci.storageartifacts.pipelinerun.enable-deep-inspectionartifacts.pipelinerun.formatartifacts.pipelinerun.storageartifacts.taskrun.formatartifacts.taskrun.storagestorage.oci.repository.insecuresigners.x509.fulcio.enabledsigners.x509.fulcio.addresssigners.x509.fulcio.issuertransparency.enabledtransparency.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:
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
Explanation
slsa/v1is an alias ofin-totofor 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 TektonTaskRun's annotations, so they are deleted with theTaskRun, for example when the Pruner deletes it.
PipelineRun Configuration
Similar to TaskRuns, you can configure PipelineRun signing and storage.
- If the storage is
oci, the attestations will be stored alongside the stored OCI artifact itself. See cosign documentation for additional information. Withenable-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 TektonPipelineRun's annotations, so they are deleted with thePipelineRun, for example when the Pruner deletes it.
OCI Configuration
- 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 TektonTaskRunorPipelineRun'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
Explanation
storage.oci.repository.insecure: trueturns off TLS certificate verification for the registries that Chains pushes signatures and attestations to, including the requests that carry the push credentials, and Chains logsUsing 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, setstorage.oci.repository.insecuretofalse(the default) or remove the key, then check thatchains-configno longer holdstruefor it, as described in Check That a Change Reached Chains.
Sigstore Features Configuration
Transparency Log
Note: If transparency.enabled is set to manual, then only TaskRuns and PipelineRuns with the following annotation will be uploaded to the transparency log: