Home
Products
Red Hat OpenShift Pipelines
1.21
Securing OpenShift Pipelines
Chapter 1. Using Tekton Chains for OpenShift Pipelines supply chain security

Chapter 1. Using Tekton Chains for OpenShift Pipelines supply chain security

Tekton Chains is a Kubernetes Custom Resource Definition (CRD) controller. You can use it to manage the supply chain security of the tasks and pipelines created using Red Hat OpenShift Pipelines.

By default, Tekton Chains observes all task run executions in your OpenShift Container Platform cluster. When the task runs complete, Tekton Chains takes a snapshot of the task runs. It then converts the snapshot to one or more standard payload formats, and finally signs and stores all artifacts.

To capture information about task runs, Tekton Chains uses Result objects. When the objects are unavailable, Tekton Chains the URLs and qualified digests of the OCI images.

1.1. Key features
Copy link

You can sign task runs, task run results, and OCI registry images with cryptographic keys that tools such as cosign and skopeo generate.
You can use attestation formats such as in-toto.
You can securely store signatures and signed artifacts using OCI repository as a storage backend.

1.2. Configuring Tekton Chains
Copy link

The Red Hat OpenShift Pipelines Operator installs Tekton Chains by default. You can configure Tekton Chains by modifying the TektonConfig custom resource; the Operator automatically applies the changes that you make in this custom resource.

To edit the custom resource, use the following command:

$ oc edit TektonConfig config

The custom resource includes a chain: array. You can add any supported configuration parameters to this array, as shown in the following example:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  addon: {}
  chain:
    artifacts.taskrun.format: tekton
  config: {}

1.2.1. Supported parameters for Tekton Chains configuration
Copy link

Cluster administrators can use various supported parameter keys and values to configure specifications about task runs, Open Container Initiative (OCI) images, and storage.

Supported parameters for task run artifacts

Expand

Table 1.1. Chains configuration: Supported parameters for task run artifacts
Key	Description	Supported values	Default value
`artifacts.taskrun.format`	The format for storing task run payloads.	`in-toto`, `slsa/v1`	`in-toto`
`artifacts.taskrun.storage`	The storage backend for task run signatures. You can specify many backends as a comma-separated list, such as `”tekton,oci”`. To disable storing task run artifacts, give an empty string `””`.	`tekton`, `oci`, `gcs`, `docdb`, `grafeas`	`oci`
`artifacts.taskrun.signer`	The signature backend for signing task run payloads.	`x509`,`kms`	`x509`

Note

slsa/v1 is an alias of in-toto for backwards compatibility.

Supported parameters for pipeline run artifacts

Expand

Table 1.2. Chains configuration: Supported parameters for pipeline run artifacts
Parameter	Description	Supported values	Default value
`artifacts.pipelinerun.format`	The format for storing pipeline run payloads.	`in-toto`, `slsa/v1`	`in-toto`
`artifacts.pipelinerun.storage`	The storage backend for storing pipeline run signatures. You can specify many backends as a comma-separated list, such as `”tekton,oci”`. To disable storing pipeline run artifacts, give an empty string `””`.	`tekton`, `oci`, `gcs`, `docdb`, `grafeas`	`oci`
`artifacts.pipelinerun.signer`	The signature backend for signing pipeline run payloads.	`x509`, `kms`	`x509`
`artifacts.pipelinerun.enable-deep-inspection`	When this parameter is `true`, Tekton Chains records the results of the child task runs of a pipeline run. When this parameter is `false`, Tekton Chains records the results of the pipeline run, but not of its child task runs.	`"true", "false"`	`"false"`

Note

slsa/v1 is an alias of in-toto for backwards compatibility.
For the grafeas storage backend, only Container Analysis is supported. You cannot configure the grafeas server address in the current version of Tekton Chains.

Supported parameters for OCI artifacts

Expand

Table 1.3. Chains configuration: Supported parameters for OCI artifacts
Parameter	Description	Supported values	Default value
`artifacts.oci.format`	The format for storing OCI payloads.	`simplesigning`	`simplesigning`
`artifacts.oci.storage`	The storage backend for storing OCI signatures. You can specify many backends as a comma-separated list, such as `”oci,tekton”`. To disable storing OCI artifacts, give an empty string `””`.	`tekton`, `oci`, `gcs`, `docdb`, `grafeas`	`oci`
`artifacts.oci.signer`	The signature backend for signing OCI payloads.	`x509`, `kms`	`x509`

1.2.1.1. Supported parameters for Key Management Service (KMS) signers
Copy link

Expand

Table 1.4. Chains configuration: Supported parameters for KMS signers
Parameter	Description	Supported values	Default value
`signers.kms.kmsref`	The URI reference to a KMS service to use in `kms` signers.	Supported schemes: `gcpkms://`, `awskms://`, `azurekms://`, `hashivault://`. See Providers in the Sigstore documentation for more details.

Supported parameters for storage

Expand

Table 1.5. Chains configuration: Supported parameters for storage
Parameter	Description	Supported values	Default value
`storage.gcs.bucket`	The Google Cloud Storage (GCS) bucket for storage
`storage.oci.repository`	The OCI repository for storing OCI signatures and attestation.	If you configure one of the artifact storage backends to `oci` and do not define this key, Tekton Chains stores the attestation alongside the stored OCI artifact itself. If you define this key, the attestation is not stored alongside the OCI artifact and is instead stored in the designated location. See the cosign documentation for additional information.
`builder.id`	The builder ID to set for in-toto attestations		`https://tekton.dev/chains/v2`
`builddefinition.buildtype`	The build type for in-toto attestation. When this parameter is `https://tekton.dev/chains/v2/slsa`, Tekton Chains records in-toto attestations in strict conformance with the Supply chain Levels for Software Artifacts (SLSA) v1.0 specification. When this parameter is `https://tekton.dev/chains/v2/slsa-tekton`, Tekton Chains records in-toto attestations with additional information, such as the labels and annotations in each `TaskRun` and `PipelineRun` object, and also adds each task in a `PipelineRun` object under `resolvedDependencies`.	`https://tekton.dev/chains/v2/slsa`,`https://tekton.dev/chains/v2/slsa-tekton`	`https://tekton.dev/chains/v2/slsa`

Supported parameters for docstore storage

If you enable the docdb storage method for any artifacts, configure docstore storage options. For more information about the go-cloud docstore URI format, see the docstore package documentation. Red Hat OpenShift Pipelines supports the following docstore services:

firestore
dynamodb

Expand

Table 1.6. Chains configuration: Supported parameters for docstore storage
Parameter	Description	Supported values
`storage.docdb.url`	The go-cloud URI reference to a `docstore` collection. Used if you enable the `docdb` storage method for any artifacts.	`firestore://projects/[PROJECT]/databases/(default)/documents/[COLLECTION]?name_field=name`
`storage.docdb.mongo-server-url`	The value for the Mongo server URL to use for `docdb` storage (`MONGO_SERVER_URL`). This URL can include authentication information. For production environments, providing authentication information as plain-text configuration might be insecure. Use the alternative `storage.docdb.mongo-server-url-dir` configuration setting for production environments.
`storage.docdb.mongo-server-url-dir`	The directory containing a file named `MONGO_SERVER_URL`. This file has the Mongo server URL to use for `docdb` storage (`MONGO_SERVER_URL`). Give this file as a secret and configure mounting this file for the Tekton Chains controller, as described in Creating and mounting the Mongo server URL secret.	Example value: `/tmp/mongo-url`

Supported parameters for Grafeas storage
If you enable the grafeas storage method for any artifacts, configure Grafeas storage options. For more information about Grafeas notes and occurrences, see Grafeas concepts.

To create occurrences, Red Hat OpenShift Pipelines must first create notes that link occurrences. Red Hat OpenShift Pipelines creates two types of occurrences: ATTESTATION Occurrence and BUILD Occurrence.

Red Hat OpenShift Pipelines uses the configurable noteid as the prefix of the note name. It appends the suffix -simplesigning for the ATTESTATION note and the suffix -intoto for the BUILD note. If the noteid field is not configured, Red Hat OpenShift Pipelines uses tekton-<NAMESPACE> as the prefix.

+ .Chains configuration: Supported parameters for Grafeas storage

Expand

Parameter	Description	Supported values	Default value
`storage.grafeas.projectid`	The OpenShift Container Platform project containing the Grafeas server for storing occurrences.
`storage.grafeas.noteid`	Optional: the prefix to use for the name of all created notes.	A string without spaces.
`storage.grafeas.notehint`	Optional: the `human_readable_name` field for the Grafeas `ATTESTATION` note.		`This attestation note was generated by Tekton Chains`

Supported parameters for transparency attestation storage

Optionally, you can enable additional uploads of binary transparency attestations.

Expand

Table 1.7. Chains configuration: Supported parameters for transparency attestation storage
Parameter	Description	Supported values	Default value
`transparency.enabled`	Enable or disable automatic binary transparency uploads.	`true`, `false`, `manual`	`false`
`transparency.url`	The URL for uploading binary transparency attestations, if enabled.		`https://rekor.sigstore.dev`

Note

If you set transparency.enabled to manual, Tekton Chains uploads only task runs and pipeline runs with the following annotation to the transparency log:

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

Supported parameters for x509 keyless signing with Fulcio

If you configure the x509 signature backend, you can optionally enable keyless signing with Fulcio.

Expand

Table 1.8. Chains configuration: Supported parameters for x509 keyless signing with Fulcio
Parameter	Description	Supported values	Default value
`signers.x509.fulcio.enabled`	Enable or disable requesting automatic certificates from Fulcio.	`true`, `false`	`false`
`signers.x509.fulcio.address`	The Fulcio address for requesting certificates, if enabled.		`https://v1.fulcio.sigstore.dev`
`signers.x509.fulcio.issuer`	The expected OpenID Connect (OIDC) issuer.		`https://oauth2.sigstore.dev/auth`
`signers.x509.fulcio.provider`	The provider from which to request the ID Token.	`google`, `spiffe`, `github`, `filesystem`	Red Hat OpenShift Pipelines attempts to use every provider
`signers.x509.identity.token.file`	Path to the file containing the ID Token.
`signers.x509.tuf.mirror.url`	The URL for the The Update Framework (TUF) server. `$TUF_URL/root.json` must be present.		`https://sigstore-tuf-root.storage.googleapis.com`

Supported parameters for specific KMS authentication

If you configure the kms signature backend, set the KMS configuration, including OIDC and Spire, as necessary.

Expand

Table 1.9. Chains configuration: Supported parameters for KMS signing
Parameter	Description	Supported values
`signers.kms.auth.address`	URI of the KMS server (the value of `VAULT_ADDR`).
`signers.kms.auth.token`	Authentication token for the KMS server (the value of `VAULT_TOKEN`). Providing the token as plain-text configuration might be insecure. Use the alternative `signers.kms.auth.token-path` configuration setting for production environments.
`signers.kms.auth.token-path`	The full path name of the file that has the authentication token for the KMS server (the value of `VAULT_TOKEN`). Give this file as a secret and configure mounting this file for the Tekton Chains controller, as described in Creating and mounting the KMS authentication token secret.	Example value: `/etc/kms-secrets/KMS_AUTH_TOKEN`
`signers.kms.auth.oidc.path`	The path for OIDC authentication (for example, `jwt` for Vault).
`signers.kms.auth.oidc.role`	The role for OIDC authentication.
`signers.kms.auth.spire.sock`	The URI of the Spire socket for the KMS token (for example, `unix:///tmp/spire-agent/public/api.sock`).
`signers.kms.auth.spire.audience`	The audience for requesting a SPIFFE Verifiable Identity Document (SVID) from Spire.

1.2.2. Creating and mounting the Mongo server URL secret
Copy link

You can give the value of the Mongo server URL to use for docdb storage (MONGO_SERVER_URL) using a secret. You must create this secret, mount it on the Tekton Chains controller, and set the storage.docdb.mongo-server-url-dir parameter to the directory where you mount the secret.

Prerequisites

You installed the OpenShift CLI (oc) utility.
You logged in to your OpenShift Container Platform cluster with administrative rights for the openshift-pipelines namespace.

Procedure

Create a secret named mongo-url with the MONGO_SERVER_URL file that has the Mongo server URL value by entering the following command:
```
$ oc create secret generic mongo-url -n tekton-chains \
  --from-file=MONGO_SERVER_URL=<path>/MONGO_SERVER_URL
```
<path>
The full path and name of the MONGO_SERVER_URL file that has the Mongo server URL value.

In the TektonConfig custom resource (CR), in the chain section, configure mounting the secret on the Tekton Chains controller and set the storage.docdb.mongo-server-url-dir parameter to the directory where you mount the secret, as shown in the following example:

Example configuration for mounting the mongo-url secret

apiVersion: operator.tekton.dev/v1
kind: TektonConfig
metadata:
  name: config
spec:
# ...
  chain:
    disabled: false
    storage.docdb.mongo-server-url-dir: /tmp/mongo-url
    options:
      deployments:
        tekton-chains-controller:
          spec:
            template:
              spec:
                containers:
                - name: tekton-chains-controller
                  volumeMounts:
                  - mountPath: /tmp/mongo-url
                    name: mongo-url
                volumes:
                -  name: mongo-url
                   secret:
                    secretName: mongo-url
# ...

1.2.3. Creating and mounting the Key Management Service (KMS) authentication token secret
Copy link

You can give the authentication token for the Key Management Service (KMS) server by using a secret. For example, if the KMS provider is Hashicorp Vault, the secret must contain the value of VAULT_TOKEN.

You must create this secret, mount it on the Tekton Chains controller, and set the signers.kms.auth.token-path parameter to the full pathname of the authentication token file.

Prerequisites

You installed the OpenShift CLI (oc) utility.
Log in to your OpenShift Container Platform cluster with administrative rights for the openshift-pipelines namespace.

Procedure

Create a secret named kms-secrets with the KMS_AUTH_TOKEN file that has the authentication token for the KMS server by entering the following command:
```
$ oc create secret generic kms-secrets -n tekton-chains \
  --from-file=KMS_AUTH_TOKEN=<path_and_name>
```
<path_and_name>
The full path and name of the file that has the authentication token for the KMS server, for example, /home/user/KMS_AUTH_TOKEN. You can use another file name instead of KMS_AUTH_TOKEN.

In the TektonConfig custom resource (CR), in the chain section, configure mounting the secret on the Tekton Chains controller and set the signers.kms.auth.token-path parameter to the full pathname of the authentication token file, as shown in the following example:

Example configuration for mounting the kms-secrets secret

apiVersion: operator.tekton.dev/v1
kind: TektonConfig
metadata:
  name: config
spec:
# ...
  chain:
    disabled: false
    signers.kms.auth.token-path: /etc/kms-secrets/KMS_AUTH_TOKEN
    options:
      deployments:
        tekton-chains-controller:
          spec:
            template:
              spec:
                containers:
                - name: tekton-chains-controller
                  volumeMounts:
                  - mountPath: /etc/kms-secrets
                    name: kms-secrets
                volumes:
                -  name: kms-secrets
                   secret:
                    secretName: kms-secrets
# ...

1.2.4. Enabling Tekton Chains to operate only in selected namespaces
Copy link

By default, the Tekton Chains controller monitors resources in all namespaces. You can customize Tekton Chains to run only in specific namespaces, which provides granular control over its operation.

Prerequisites

You logged in to your OpenShift Container Platform cluster with cluster-admin privileges.

Procedure

In the TektonConfig CR, in the chain section, add the --namespace= argument to contain the namespaces that the controller should watch.

The following example shows the configuration for the Tekton Chains controller to only watch resources within the dev and test namespaces, filtering PipelineRun and TaskRun objects so:

apiVersion: operator.tekton.dev/v1alpha1
kind: TektonConfig
metadata:
  name: config
spec:
  chain:
    disabled: false
    options:
      deployments:
        tekton-chains-controller:
          spec:
            template:
              spec:
                containers:
                - args:
                  - --namespace=dev, test
                  name: tekton-chains-controller

--namespace: If you do not give the --namespace argument or leave it empty, the controller watches all namespaces by default.

Chapter 1. Using Tekton Chains for OpenShift Pipelines supply chain security

1.1. Key features
Copy link

1.2. Configuring Tekton Chains
Copy link

1.2.1. Supported parameters for Tekton Chains configuration
Copy link

1.2.1.1. Supported parameters for Key Management Service (KMS) signers
Copy link

1.2.2. Creating and mounting the Mongo server URL secret
Copy link

1.2.3. Creating and mounting the Key Management Service (KMS) authentication token secret
Copy link

1.2.4. Enabling Tekton Chains to operate only in selected namespaces
Copy link

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

Chapter 1. Using Tekton Chains for OpenShift Pipelines supply chain security

1.1. Key featuresCopy linkLink copied to clipboard!

1.2. Configuring Tekton ChainsCopy linkLink copied to clipboard!

1.2.1. Supported parameters for Tekton Chains configurationCopy linkLink copied to clipboard!

1.2.1.1. Supported parameters for Key Management Service (KMS) signersCopy linkLink copied to clipboard!

1.2.2. Creating and mounting the Mongo server URL secretCopy linkLink copied to clipboard!

1.2.3. Creating and mounting the Key Management Service (KMS) authentication token secretCopy linkLink copied to clipboard!

1.2.4. Enabling Tekton Chains to operate only in selected namespacesCopy linkLink copied to clipboard!

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Theme

Red Hat legal and privacy links

Red Hat legal and privacy links

1.1. Key features
Copy link

1.2. Configuring Tekton Chains
Copy link

1.2.1. Supported parameters for Tekton Chains configuration
Copy link

1.2.1.1. Supported parameters for Key Management Service (KMS) signers
Copy link

1.2.2. Creating and mounting the Mongo server URL secret
Copy link

1.2.3. Creating and mounting the Key Management Service (KMS) authentication token secret
Copy link

1.2.4. Enabling Tekton Chains to operate only in selected namespaces
Copy link