Chains Configuration

Chains works by observing TaskRun and PipelineRun executions, capturing relevant information, and storing it in a cryptographically-signed format.

TaskRuns and PipelineRuns can indicate inputs and outputs which are then captured and surfaced in the Chains payload formats, where relevant. Chains uses the Results to hint at the correct inputs and outputs. Check out slsa-provenance.md for more details.

Chains Configuration

Chains uses a ConfigMap called chains-config in the tekton-chains namespace for configuration. Supported keys include:

TaskRun Configuration

Key	Description	Supported Values	Default
artifacts.taskrun.format	The format to store TaskRun payloads in.	in-toto, slsa/v1, slsa/v2alpha3, slsa/v2alpha4	in-toto
artifacts.taskrun.storage	The 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	tekton
artifacts.taskrun.signer	The signature backend to sign TaskRun payloads with. Use none to disable signing while still storing provenance.	x509, kms, none	x509

NOTE:

• slsa/v1 is an alias of in-toto for backwards compatibility.
• slsa/v2alpha3 corresponds to the slsav1.0 spec. and uses latest v1 Tekton Objects. Recommended format for new chains users who want the slsav1.0 spec.
• slsa/v2alpha4 corresponds to the slsav1.0 spec. and uses latest v1 Tekton Objects. It reads type-hinted results from StepActions. Recommended format for new chains users who want the slsav1.0 spec.

PipelineRun Configuration

Key	Description	Supported Values	Default
artifacts.pipelinerun.format	The format to store PipelineRun payloads in.	in-toto, slsa/v1, slsa/v2alpha3, slsa/v2alpha4	in-toto
artifacts.pipelinerun.storage	The 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	tekton
artifacts.pipelinerun.signer	The signature backend to sign PipelineRun payloads with. Use none to disable signing while still storing provenance.	x509, kms, none	x509
artifacts.pipelinerun.enable-deep-inspection	This 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"

NOTE:

• For grafeas storage backend, currently we only support Container Analysis. We will make grafeas server address configurabe within a short time.
• slsa/v1 is an alias of in-toto for backwards compatibility.
• slsa/v2alpha3 corresponds to the slsav1.0 spec. and uses latest v1 Tekton Objects. Recommended format for new chains users who want the slsav1.0 spec.
• slsa/v2alpha4 corresponds to the slsav1.0 spec. and uses latest v1 Tekton Objects. It reads type-hinted results from StepActions when artifacts.pipelinerun.enable-deep-inspection is set to true. Recommended format for new chains users who want the slsav1.0 spec.

OCI Configuration

Key	Description	Supported Values	Default
artifacts.oci.format	The format to store OCI payloads in.	simplesigning	simplesigning
artifacts.oci.storage	The 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	oci
artifacts.oci.signer	The signature backend to sign OCI payloads with. Use none to skip signing of OCI artifacts while still allowing provenance generation and attestation signing (see note below).	x509, kms, none	x509

Note: When artifacts.oci.signer is set to none, only OCI image signing is disabled; attestations are still generated and pushed as configured. To push attestations to registries, set artifacts.taskrun.storage and/or artifacts.pipelinerun.storage to include oci. Attestations will still be pushed to the same location determined by type hinting (IMAGE_URL/IMAGE_DIGEST results) or storage.oci.repository if configured.

KMS Configuration

Key	Description	Supported Values	Default
signers.kms.kmsref	The URI reference to a KMS service to use in KMS signers.	Supported schemes: gcpkms://, awskms://, azurekms://, hashivault://. See https://docs.sigstore.dev/cosign/kms_support for more details.

Storage Configuration

Key	Description	Supported Values	Default
storage.gcs.bucket	The GCS bucket for storage
storage.oci.repository	The OCI repo to store OCI signatures and attestation in	If 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.insecure	Whether to use insecure connection when connecting to the OCI repository	true, false	false
storage.docdb.url	The go-cloud URI reference to a docstore collection	firestore://projects/[PROJECT]/databases/(default)/documents/[COLLECTION]?name_field=name
storage.docdb.mongo-server-url (optional)	The value of MONGO_SERVER_URL env var with the MongoDB connection URI	Example: mongodb://[USER]:[PASSWORD]@[HOST]:[PORT]/[DATABASE]
storage.docdb.mongo-server-url-dir (optional)	The path of the directory that contains the file named MONGO_SERVER_URL that stores the value of MONGO_SERVER_URL env var	If the file /mnt/mongo-creds-secret/MONGO_SERVER_URL has the value of MONGO_SERVER_URL, then set storage.docdb.mongo-server-url-dir: /mnt/mongo-creds-secret
storage.docdb.mongo-server-url-path (optional)	The path of the file that contains the value of mongo server url	If the file /mnt/mongo-creds-secret/mongo-server-url has the value, then set storage.docdb.mongo-server-url-path: /mnt/mongo-creds-secret/mongo-server-url
storage.grafeas.projectid	The project of where grafeas server is located for storing occurrences
storage.grafeas.noteid (optional)	This field will be used as the prefix part of the note name that will be created. The value of this field must be a string without spaces. (See more details below.)
storage.grafeas.notehint (optional)	This field is used to set the human_readable_name field in the Grafeas ATTESTATION note. If it is not provided, the default This attestation note was generated by Tekton Chains will be used.
storage.archivista.url	The URL endpoint for the Archivista service.	A valid HTTPS URL pointing to your Archivista instance (e.g. https://archivista.testifysec.io).	None

docstore

You can read about the go-cloud docstore URI format here. Tekton Chains supports the following docstore services:

• firestore
• dynamodb
• mongo

MongoDB

You can provide MongoDB connection through different options

• Using MONGO_SERVER_URL Environment Variable

  • User can set the MongoDB connection URL in the MONGO_SERVER_URL env var in the Chains deployment

• Using storage.docdb.mongo-server-url field in the chains-config configmap

  • Alternatively, you can set the connection URL using the storage.docdb.mongo-server-url field in the chains-config configmap
  • This field overrides the MONGO_SERVER_URL env var

• Using storage.docdb.mongo-server-url-dir field

  • Another option is to set storage.docdb.mongo-server-url-dir, which points to a directory containing a file named MONGO_SERVER_URL
  • The directory path setting takes precedence over both storage.docdb.mongo-server-url and the MONGO_SERVER_URL env var
  • For instance, if /mnt/mongo-creds-secret/MONGO_SERVER_URL contains the MongoDB URL, set storage.docdb.mongo-server-url-dir: /mnt/mongo-creds-secret

• Using storage.docdb.mongo-server-url-path field

  • You can use storage.docdb.mongo-server-url-path field in chains-config configmap to directly reference the file containing the MongoDB URL
  • This field overrides all others (mongo-server-url-dir, mongo-server-url, and MONGO_SERVER_URL env var)
  • For instance, if /mnt/mongo-creds-secret/mongo-server-url contains the MongoDB URL, then set storage.docdb.mongo-server-url-path: /mnt/mongo-creds-secret/mongo-server-url

NOTE :-

• When using storage.docdb.mongo-server-url-dir or storage.docdb.mongo-server-url-path field, store the value of mongo server url in a secret and mount the secret. When the secret is updated, the new value will be fetched by Tekton Chains controller
• Also using storage.docdb.mongo-server-url-dir or storage.docdb.mongo-server-url-path field are recommended, using storage.docdb.mongo-server-url should be avoided since credentials are stored in a ConfigMap instead of a secret

Grafeas

You can read more about Grafeas notes and occurrences here. To create occurrences, we have to create notes first that are used to link occurrences. Two types of occurrences will be created: ATTESTATION Occurrence and BUILD Occrrence. The configurable noteid is used as the prefix of the note name. Under the hood, the suffix -simplesigning will be appended for the ATTESTATION note, and the suffix -intoto will be appended for the BUILD note. If the noteid field is not configured, tekton-<NAMESPACE> will be used as the prefix.

In-toto Configuration

Key	Description	Supported Values	Default
builder.id	The builder ID to set for in-toto attestations		https://tekton.dev/chains/v2
builddefinition.buildtype	The buildType for in-toto attestations	https://tekton.dev/chains/v2/slsa, https://tekton.dev/chains/v2/slsa-tekton	https://tekton.dev/chains/v2/slsa

NOTE: Considerations for the builddefinition.buildtype parameter:

• It is only valid for slsa/v2alpha3 configurations (see TaskRun or PipelineRun configuration).
• The parameter can take one of two values:
  • https://tekton.dev/chains/v2/slsa: This buildType strictly conforms to the slsav1.0 spec.
  • https://tekton.dev/chains/v2/slsa-tekton: This buildType also conforms to the slsav1.0 spec, but adds additional information specific to Tekton. This information includes the PipelinRun/TaskRun labels and annotations as internalParameters. It also includes capturing each pipeline task in a PipelinRun under resolvedDependencies.

Sigstore Features Configuration

Transparency Log

Key	Description	Supported Values	Default
transparency.enabled	Whether to enable automatic binary transparency uploads.	true, false, manual	false
transparency.url	The URL to upload binary transparency attestations to, if enabled.		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

Key	Description	Supported Values	Default
signers.x509.fulcio.enabled	Whether to enable automatic certificates from fulcio.	true, false	false
signers.x509.fulcio.address	Fulcio address to request certificate from, if enabled		https://fulcio.sigstore.dev
signers.x509.fulcio.issuer	Expected OIDC issuer.		https://oauth2.sigstore.dev/auth
signers.x509.fulcio.provider	Provider to request ID Token from	google, spiffe, github, filesystem	Unset, each provider will be attempted.
signers.x509.identity.token.file	Path to file containing ID Token.
signers.x509.tuf.mirror.url	TUF server URL. $TUF_URL/root.json is expected to be present.		https://sigstore-tuf-root.storage.googleapis.com

KMS OIDC and Spire Configuration

Key	Description	Supported Values	Default
signers.kms.auth.address	URI of KMS server (e.g. the value of VAULT_ADDR)
signers.kms.auth.token	Auth token KMS server (e.g. the value of VAULT_TOKEN)
signers.kms.auth.token-path	Path to store KMS server Auth token (e.g. /etc/kms-secrets)
signers.kms.auth.oidc.path	Path used for OIDC authentication (e.g. jwt for Vault)
signers.kms.auth.oidc.role	Role used for OIDC authentication
signers.kms.auth.oidc.token-path	Path to a file containing the JWT token for OIDC authentication. If not set, defaults to the Kubernetes service account token at /var/run/secrets/kubernetes.io/serviceaccount/token.		/var/run/secrets/kubernetes.io/serviceaccount/token
signers.kms.auth.spire.sock	URI of the Spire socket used for KMS token (e.g. unix:///tmp/spire-agent/public/api.sock)
signers.kms.auth.spire.audience	Audience for requesting a SVID from Spire

NOTE:

If signers.kms.auth.token-path is set, create a secret and ensure the Chains deployment mounts this secret to the path specified by signers.kms.auth.token-path.

Visual Guide: ConfigMap Configuration Options

Refer the diagram below to explore the pictorial representation of signing and storage configuration options, and their usage in the context of chains artifacts.

Namespaces Restrictions in Chains Controller

This feature allows you to specify a list of namespaces for the controller to monitor, providing granular control over its operation. If no namespaces are specified, the controller defaults to monitoring all namespaces.

Usage

To restrict the Chains Controller to specific namespaces, pass a comma-separated list of namespaces as an argument to the controller using the --namespace flag.

Example

To restrict the controller to the dev and test namespaces, you would start the controller with the following argument:

--namespace=dev,test

In this example, the controller will only monitor resources (pipelinesruns and taskruns) within the dev and test namespaces.