#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. You can modify this ConfigMap to change the behavior of Chains.

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 TektonChains resource, and finally reflect in the chains-config ConfigMap.

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

Tips: 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
    controllerEnvs:
      - name: SIGSTORE_ID_TOKEN
        value: "<your-id-token>"

    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>
    signers.x509.fulcio.address: <ttps://fulcio.sigstore.dev>
    signers.x509.fulcio.issuer: <https://oauth2.sigstore.dev/auth>
    transparency.enabled: <false>
    transparency.url: <https://rekor.sigstore.dev>

    storage.oci.repository.insecure: true

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

Tips: 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.
  • disabled: Whether to disable Chains.
    • This configuration is unique to TektonConfig and does not exist in TektonChains.
  • generateSigningSecret: Whether to generate a signing secret.
    • This configuration is unique to TektonConfig and does not exist in TektonChains.
  • controllerEnvs: The environment variables for the Tekton Chains controller.
    • This configuration is unique to TektonConfig and does not exist in TektonChains.
    • name: The name of the environment variable.
    • value: The value of the environment variable.
  • options: The options for the Tekton Chains controller.
    • This configuration is unique to TektonConfig and does not exist in TektonChains.
    • 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
  • The following configurations also exist in TektonChains and will ultimately be synchronized to the chains-config ConfigMap.
    • artifacts.oci.format
    • artifacts.oci.storage
    • artifacts.pipelinerun.format
    • artifacts.pipelinerun.storage
    • artifacts.taskrun.format
    • artifacts.taskrun.storage
    • storage.oci.repository.insecure
    • signers.x509.fulcio.address
    • signers.x509.fulcio.issuer
    • transparency.enabled
    • transparency.url

#TaskRun Configuration

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.

#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.
• If the storage is tekton, the attestations will be stored in the Tekton PipelineRun's annotations.

#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 Tekton TaskRun or PipelineRun's annotations.

#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

• If your OCI repository is use self-signed certificate, you need to set storage.oci.repository.insecure to true to allow insecure connection.

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

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

#Keyless Signing with Fulcio

#References

• Tekton Chains Configuration
• Additional fields as options