Red Hat SummitEste contenido no está disponible en el idioma seleccionado.
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
-
You can sign task runs, task run results, and OCI registry images with cryptographic keys that tools such as
cosignandskopeogenerate. -
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
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
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.formatThe format for storing task run payloads.
in-toto,slsa/v1in-totoartifacts.taskrun.storageThe 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,grafeasociartifacts.taskrun.signerThe signature backend for signing task run payloads.
x509,kmsx509Noteslsa/v1is an alias ofin-totofor 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.formatThe format for storing pipeline run payloads.
in-toto,slsa/v1in-totoartifacts.pipelinerun.storageThe 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,grafeasociartifacts.pipelinerun.signerThe signature backend for signing pipeline run payloads.
x509,kmsx509artifacts.pipelinerun.enable-deep-inspectionWhen this parameter is
true, Tekton Chains records the results of the child task runs of a pipeline run. When this parameter isfalse, Tekton Chains records the results of the pipeline run, but not of its child task runs."true", "false""false"Note-
slsa/v1is an alias ofin-totofor backwards compatibility. -
For the
grafeasstorage backend, only Container Analysis is supported. You cannot configure thegrafeasserver 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.formatThe format for storing OCI payloads.
simplesigningsimplesigningartifacts.oci.storageThe 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,grafeasociartifacts.oci.signerThe signature backend for signing OCI payloads.
x509,kmsx509
1.2.1.1. Supported parameters for Key Management Service (KMS) signers
| Parameter | Description | Supported values | Default value |
|---|---|---|---|
|
|
The URI reference to a KMS service to use in |
Supported schemes: |
Supported parameters for storage
Expand Table 1.5. Chains configuration: Supported parameters for storage Parameter Description Supported values Default value storage.gcs.bucketThe Google Cloud Storage (GCS) bucket for storage
storage.oci.repositoryThe OCI repository for storing OCI signatures and attestation.
If you configure one of the artifact storage backends to
ociand 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.idThe builder ID to set for in-toto attestations
https://tekton.dev/chains/v2builddefinition.buildtypeThe 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 ishttps://tekton.dev/chains/v2/slsa-tekton, Tekton Chains records in-toto attestations with additional information, such as the labels and annotations in eachTaskRunandPipelineRunobject, and also adds each task in aPipelineRunobject underresolvedDependencies.https://tekton.dev/chains/v2/slsa,https://tekton.dev/chains/v2/slsa-tektonhttps://tekton.dev/chains/v2/slsaSupported parameters for docstore storage
If you enable the
docdbstorage 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 Default value storage.docdb.urlThe go-cloud URI reference to a
docstorecollection. Used if you enable thedocdbstorage method for any artifacts.firestore://projects/[PROJECT]/databases/(default)/documents/[COLLECTION]?name_field=namestorage.docdb.mongo-server-urlThe value for the Mongo server URL to use for
docdbstorage (MONGO_SERVER_URL). This URL can include authentication information. For production environments, providing authentication information as plain-text configuration might be insecure. Use the alternativestorage.docdb.mongo-server-url-dirconfiguration setting for production environments.storage.docdb.mongo-server-url-dirThe directory containing a file named
MONGO_SERVER_URL. This file has the Mongo server URL to use fordocdbstorage (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
grafeasstorage 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
| Parameter | Description | Supported values | Default value |
|---|---|---|---|
|
| The OpenShift Container Platform project containing the Grafeas server for storing occurrences. | ||
|
| Optional: the prefix to use for the name of all created notes. | A string without spaces. | |
|
|
Optional: the |
|
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.enabledEnable or disable automatic binary transparency uploads.
true,false,manualfalsetransparency.urlThe URL for uploading binary transparency attestations, if enabled.
https://rekor.sigstore.dev
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
x509keyless signing with FulcioIf you configure the
x509signature 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.enabledEnable or disable requesting automatic certificates from Fulcio.
true,falsefalsesigners.x509.fulcio.addressThe Fulcio address for requesting certificates, if enabled.
https://v1.fulcio.sigstore.devsigners.x509.fulcio.issuerThe expected OpenID Connect (OIDC) issuer.
https://oauth2.sigstore.dev/authsigners.x509.fulcio.providerThe provider from which to request the ID Token.
google,spiffe,github,filesystemRed Hat OpenShift Pipelines attempts to use every provider
signers.x509.identity.token.filePath to the file containing the ID Token.
signers.x509.tuf.mirror.urlThe URL for the The Update Framework (TUF) server.
$TUF_URL/root.jsonmust be present.https://sigstore-tuf-root.storage.googleapis.comSupported parameters for specific KMS authentication
If you configure the
kmssignature 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 Default value signers.kms.auth.addressURI of the KMS server (the value of
VAULT_ADDR).signers.kms.auth.tokenAuthentication token for the KMS server (the value of
VAULT_TOKEN). Providing the token as plain-text configuration might be insecure. Use the alternativesigners.kms.auth.token-pathconfiguration setting for production environments.signers.kms.auth.token-pathThe 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_TOKENsigners.kms.auth.oidc.pathThe path for OIDC authentication (for example,
jwtfor Vault).signers.kms.auth.oidc.roleThe role for OIDC authentication.
signers.kms.auth.spire.sockThe URI of the Spire socket for the KMS token (for example,
unix:///tmp/spire-agent/public/api.sock).signers.kms.auth.spire.audienceThe audience for requesting a SPIFFE Verifiable Identity Document (SVID) from Spire.
1.2.2. Creating and mounting the Mongo server URL secret
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-pipelinesnamespace.
Procedure
Create a secret named
mongo-urlwith theMONGO_SERVER_URLfile 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_URLfile that has the Mongo server URL value.
In the
TektonConfigcustom resource (CR), in thechainsection, configure mounting the secret on the Tekton Chains controller and set thestorage.docdb.mongo-server-url-dirparameter to the directory where you mount the secret, as shown in the following example:Example configuration for mounting the
mongo-urlsecretapiVersion: 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
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-pipelinesnamespace.
Procedure
Create a secret named
kms-secretswith theKMS_AUTH_TOKENfile 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 ofKMS_AUTH_TOKEN.
In the
TektonConfigcustom resource (CR), in thechainsection, configure mounting the secret on the Tekton Chains controller and set thesigners.kms.auth.token-pathparameter to the full pathname of the authentication token file, as shown in the following example:Example configuration for mounting the
kms-secretssecretapiVersion: 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
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-adminprivileges.
Procedure
In the
TektonConfigCR, in thechainsection, 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
devandtestnamespaces, filteringPipelineRunandTaskRunobjects 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
--namespaceargument or leave it empty, the controller watches all namespaces by default.
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}