From 7c159226efec3906839ff0ecc2aeb4331a0065be Mon Sep 17 00:00:00 2001 From: Misha Ramendik Date: Sat, 6 May 2023 03:56:41 +0100 Subject: [PATCH] RHDEVDOCS-5246: Tekton Chains configuration changes for GA Modularization improvements for the Tekton Chains PR typo --- ...shift-pipelines-supply-chain-security.adoc | 26 +- .../op-chains-resolving-existing-secret.adoc | 28 ++ modules/op-chains-signing-secrets-cosign.adoc | 27 ++ modules/op-chains-signing-secrets-skopeo.adoc | 80 +++++ modules/op-configuring-tekton-chains.adoc | 22 +- ...without-any-additional-authentication.adoc | 71 +++-- ...ing-pipelines-operator-in-web-console.adoc | 18 +- .../op-signing-secrets-in-tekton-chains.adoc | 48 +-- ...rted-keys-tekton-chains-configuration.adoc | 56 ---- ...arameters-tekton-chains-configuration.adoc | 275 ++++++++++++++++++ 10 files changed, 498 insertions(+), 153 deletions(-) create mode 100644 modules/op-chains-resolving-existing-secret.adoc create mode 100644 modules/op-chains-signing-secrets-cosign.adoc create mode 100644 modules/op-chains-signing-secrets-skopeo.adoc delete mode 100644 modules/op-supported-keys-tekton-chains-configuration.adoc create mode 100644 modules/op-supported-parameters-tekton-chains-configuration.adoc diff --git a/cicd/pipelines/using-tekton-chains-for-openshift-pipelines-supply-chain-security.adoc b/cicd/pipelines/using-tekton-chains-for-openshift-pipelines-supply-chain-security.adoc index 7719d736c8..a1c864d12d 100644 --- a/cicd/pipelines/using-tekton-chains-for-openshift-pipelines-supply-chain-security.adoc +++ b/cicd/pipelines/using-tekton-chains-for-openshift-pipelines-supply-chain-security.adoc @@ -6,38 +6,35 @@ include::_attributes/common-attributes.adoc[] toc::[] -:FeatureName: Tekton Chains -include::snippets/technology-preview.adoc[] - [role="_abstract"] {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 {pipelines-title}. -By default, {tekton-chains} observes all task run executions in your {product-title} 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. +By default, {tekton-chains} observes all task run executions in your {product-title} 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 the `Result` and `PipelineResource` objects. When the objects are unavailable, {tekton-chains} the URLs and qualified digests of the OCI images. - -[NOTE] -==== -The `PipelineResource` object is deprecated and will be removed in a future release; for manual use, the `Results` object is recommended. -==== +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. [id="tc-key-features"] == Key features -* You can sign task runs, task run results, and OCI registry images with cryptographic key types and services such as `cosign`. +* You can sign task runs, task run results, and OCI registry images with cryptographic keys that are generated by tools such as `cosign` and `skopeo`. * You can use attestation formats such as `in-toto`. * You can securely store signatures and signed artifacts using OCI repository as a storage backend. -include::modules/op-installing-tekton-chains-using-pipelines-operator.adoc[leveloffset=+1] - include::modules/op-configuring-tekton-chains.adoc[leveloffset=+1] -include::modules/op-supported-keys-tekton-chains-configuration.adoc[leveloffset=+2] +include::modules/op-supported-parameters-tekton-chains-configuration.adoc[leveloffset=+2] include::modules/op-signing-secrets-in-tekton-chains.adoc[leveloffset=+1] +include::modules/op-chains-signing-secrets-cosign.adoc[leveloffset=+2] +include::modules/op-chains-signing-secrets-skopeo.adoc[leveloffset=+2] +include::modules/op-chains-resolving-existing-secret.adoc[leveloffset=+2] include::modules/op-authenticating-to-an-oci-registry.adoc[leveloffset=+1] include::modules/op-creating-and-verifying-task-run-signatures-without-any-additional-authentication.adoc[leveloffset=+1] +=== Additional resources + +* xref:signing-secrets-in-tekton-chains_{context}[] +* xref:configuring-tekton-chains_{context}[] include::modules/op-using-tekton-chains-to-sign-and-verify-image-and-provenance.adoc[leveloffset=+1] @@ -46,4 +43,3 @@ include::modules/op-using-tekton-chains-to-sign-and-verify-image-and-provenance. == Additional resources * xref:../../cicd/pipelines/installing-pipelines.adoc#installing-pipelines[Installing {pipelines-shortname}] - diff --git a/modules/op-chains-resolving-existing-secret.adoc b/modules/op-chains-resolving-existing-secret.adoc new file mode 100644 index 0000000000..a8ab0c32a6 --- /dev/null +++ b/modules/op-chains-resolving-existing-secret.adoc @@ -0,0 +1,28 @@ +// This module is included in the following assembly: +// +// *cicd/pipelines/using-tekton-chains-for-pipelines-supply-chain-security.adoc + +:_content-type: PROCEDURE + +[id="chains-resolving-existing-secret_{context}"] += Resolving the "secret already exists" error + +If the `signing-secret` secret is already populated, the command to create this secret might output the following error message: + +[source,terminal] +---- +Error from server (AlreadyExists): secrets "signing-secrets" already exists +---- + +You can resolve this error by deleting the secret. + +.Procedure + +. Delete the `signing-secret` secret by running the following command: ++ +[source,terminal] +---- +$ oc delete secret signing-secrets -n openshift-pipelines +---- + +. Re-create the key pairs and store them in the secret using your preferred signing scheme. diff --git a/modules/op-chains-signing-secrets-cosign.adoc b/modules/op-chains-signing-secrets-cosign.adoc new file mode 100644 index 0000000000..e3e8ae6f4b --- /dev/null +++ b/modules/op-chains-signing-secrets-cosign.adoc @@ -0,0 +1,27 @@ +// This module is included in the following assembly: +// +// *cicd/pipelines/using-tekton-chains-for-pipelines-supply-chain-security.adoc + +:_content-type: PROCEDURE + +[id="chains-signing-secrets-cosign_{context}"] += Signing using cosign + +You can use the `cosign` signing scheme with {tekton-chains} using the `cosign` tool. + +.Prerequisites + +* You installed the link:https://docs.sigstore.dev/cosign/installation/[cosign] tool. + +.Procedure + +. Generate the `cosign.key` and `cosign.pub` key pairs by running the following command: ++ +[source,terminal] +---- +$ cosign generate-key-pair k8s://openshift-pipelines/signing-secrets +---- ++ +Cosign prompts you for a password and then creates a Kubernetes secret. + +. Store the encrypted `cosign.key` private key and the `cosign.password` decryption password in the `signing-secrets` Kubernetes secret. Ensure that the private key is stored as an encrypted PEM file of the `ENCRYPTED COSIGN PRIVATE KEY` type. diff --git a/modules/op-chains-signing-secrets-skopeo.adoc b/modules/op-chains-signing-secrets-skopeo.adoc new file mode 100644 index 0000000000..d6c1871059 --- /dev/null +++ b/modules/op-chains-signing-secrets-skopeo.adoc @@ -0,0 +1,80 @@ +// This module is included in the following assembly: +// +// *cicd/pipelines/using-tekton-chains-for-pipelines-supply-chain-security.adoc + +:_content-type: PROCEDURE + +[id="chains-signing-secrets-skopeo_{context}"] += Signing using skopeo + +You can generate keys using the `skopeo` tool and use them in the `cosign` signing scheme with {tekton-chains}. + +.Prerequisites + +* You installed the link:https://github.com/containers/skopeo[skopeo] tool. + +.Procedure + +. Generate a public/private key pair by running the following command: ++ +[source,terminal] +---- +$ skopeo generate-sigstore-key --output-prefix # <1> +---- +<1> Replace `` with a key name of your choice. ++ +Skopeo prompts you for a passphrase for the private key and then creates the key files named `.private` and `.pub`. + +. Encode the `.pub` file using the `base64` tool by running the following command: ++ +[source,terminal] +---- +$ base64 -w 0 .pub > b64.pub +---- + +. Encode the `.private` file using the `base64` tool by running the following command: ++ +[source,terminal] +---- +$ base64 -w 0 .private > b64.private +---- + +. Encode the passhprase using the `base64` tool by running the following command: ++ +[source,terminal] +---- +$ echo -n '' | base64 -w 0 > b64.passphrase # <1> +---- +<1> Replace `` with the passphrase that you used for the key pair. + +. Create the `signing-secrets` secret in the `openshift-pipelines` namespace by running the following command: ++ +[source,terminal] +---- +$ oc create secret generic signing-secrets -n openshift-pipelines +---- ++ +. Edit the `signing-secrets` secret by running the following command: +---- +$ oc edit secret -n openshift-pipelines signing-secrets +---- ++ +Add the encoded keys in the data of the secret in the following way: ++ +[source,yaml] +---- +apiVersion: v1 +data: + cosign.key: .private> # <1> + cosign.password: # <2> + cosign.pub: .pub> # <3> +immutable: true +kind: Secret +metadata: + name: signing-secrets +# ... +type: Opaque +---- +<1> Replace `.private>` with the content of the `b64.private` file. +<2> Replace `` with the content of the `b64.passphrase` file. +<3> Replace `.pub>` with the content of the `b64.pub` file. diff --git a/modules/op-configuring-tekton-chains.adoc b/modules/op-configuring-tekton-chains.adoc index 482e272471..e06d7aaad0 100644 --- a/modules/op-configuring-tekton-chains.adoc +++ b/modules/op-configuring-tekton-chains.adoc @@ -6,14 +6,26 @@ [id="configuring-tekton-chains_{context}"] = Configuring {tekton-chains} -{tekton-chains} uses a `ConfigMap` object named `chains-config` in the `openshift-pipelines` namespace for configuration. +The {pipelines-title} 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 configure {tekton-chains}, use the following example: +To edit the custom resource, use the following command: -.Example: Configuring {tekton-chains} [source,terminal] ---- -$ oc patch configmap chains-config -n openshift-pipelines -p='{"data":{"artifacts.oci.storage": "", "artifacts.taskrun.format":"tekton", "artifacts.taskrun.storage": "tekton"}}' <1> +$ oc edit TektonConfig config ---- -<1> Use a combination of supported key-value pairs in the JSON payload. +The custom resource includes a `chain:` array. You can add any supported configuration parameters to this array, as shown in the following example: + +[source,yaml] +---- +apiVersion: operator.tekton.dev/v1alpha1 +kind: TektonConfig +metadata: + name: config +spec: + addon: {} + chain: + artifacts.taskrun.format: tekton + config: {} +---- diff --git a/modules/op-creating-and-verifying-task-run-signatures-without-any-additional-authentication.adoc b/modules/op-creating-and-verifying-task-run-signatures-without-any-additional-authentication.adoc index 2aa3994774..cbca91894e 100644 --- a/modules/op-creating-and-verifying-task-run-signatures-without-any-additional-authentication.adoc +++ b/modules/op-creating-and-verifying-task-run-signatures-without-any-additional-authentication.adoc @@ -4,7 +4,7 @@ :_content-type: PROCEDURE [id="creating-and-verifying-task-run-signatures-without-any-additional-authentication_{context}"] -== Creating and verifying task run signatures without any additional authentication += Creating and verifying task run signatures without any additional authentication [role="_abstract"] To verify signatures of task runs using {tekton-chains} with any additional authentication, perform the following tasks: @@ -16,7 +16,7 @@ To verify signatures of task runs using {tekton-chains} with any additional auth * Verify the signature of the task run. .Prerequisites -Ensure that the following are installed on the cluster: +Ensure that the following components are installed on the cluster: * {pipelines-title} Operator * {tekton-chains} @@ -24,43 +24,56 @@ Ensure that the following are installed on the cluster: .Procedure -. Create an encrypted x509 key pair and save it as a Kubernetes secret: +. Create an encrypted x509 key pair and save it as a Kubernetes secret. For more information about creating a key pair and saving it as a secret, see "Signing secrets in {tekton-chains}". +. In the {tekton-chains} configuration, disable the OCI storage, and set the task run storage and format to `tekton`. In the `TektonConfig` custom resource set the following values: + -[source,terminal] +[source,yaml] ---- -$ cosign generate-key-pair k8s://openshift-pipelines/signing-secrets +apiVersion: operator.tekton.dev/v1alpha1 +kind: TektonConfig +metadata: + name: config +spec: +# ... + chain: + artifacts.oci.storage: "" + artifacts.taskrun.format: tekton + artifacts.taskrun.storage: tekton +# ... ---- + -Provide a password when prompted. Cosign stores the resulting private key as part of the `signing-secrets` Kubernetes secret in the `openshift-pipelines` namespace. - -. In the {tekton-chains} configuration, disable the OCI storage, and set the task run storage and format to `tekton`. -+ -[source,terminal] ----- -$ oc patch configmap chains-config -n openshift-pipelines -p='{"data":{"artifacts.oci.storage": "", "artifacts.taskrun.format":"tekton", "artifacts.taskrun.storage": "tekton"}}' ----- - -. Restart the {tekton-chains} controller to ensure that the modified configuration is applied. +For more information about configuring {tekton-chains} using the `TektonConfig` custom resource, see "Configuring {tekton-chains}". +. To restart the {tekton-chains} controller to ensure that the modified configuration is applied, enter the following command: + [source.terminal] ---- $ oc delete po -n openshift-pipelines -l app=tekton-chains-controller ---- -. Create a task run. +. Create a task run by entering the following command: + [source,terminal] ---- $ oc create -f https://raw.githubusercontent.com/tektoncd/chains/main/examples/taskruns/task-output-image.yaml <1> +---- +<1> Replace the example URI with the URI or file path pointing to your task run. ++ +.Example output +[source,terminal] +---- taskrun.tekton.dev/build-push-run-output-image-qbjvh created ---- -<1> Substitute with the URI or file path pointing to your task run. -. Check the status of the steps, and wait till the process finishes. +. Check the status of the steps by entering the following command. Wait until the process finishes. + [source,terminal] ---- $ tkn tr describe --last +---- ++ +.Example output +[source,terminal] +---- [...truncated output...] NAME STATUS ∙ create-dir-builtimage-9467f Completed @@ -70,21 +83,27 @@ NAME STATUS ∙ image-digest-exporter-xlkn7 Completed ---- -. Retrieve the signature and payload from the object stored as `base64` encoded annotations: +. To retrieve the signature from the object stored as `base64` encoded annotations, enter the following commands: ++ +[source,terminal] +---- +$ tkn tr describe --last -o jsonpath="{.metadata.annotations.chains\.tekton\.dev/signature-taskrun-$TASKRUN_UID}" | base64 -d > sig +---- + [source,terminal] ---- $ export TASKRUN_UID=$(tkn tr describe --last -o jsonpath='{.metadata.uid}') -$ tkn tr describe --last -o jsonpath="{.metadata.annotations.chains\.tekton\.dev/signature-taskrun-$TASKRUN_UID}" > signature -$ tkn tr describe --last -o jsonpath="{.metadata.annotations.chains\.tekton\.dev/payload-taskrun-$TASKRUN_UID}" | base64 -d > payload ---- -. Verify the signature. -+ +. To verify the signature using the public key that you created, enter the following command: +[source,terminal] +---- +$ cosign verify-blob-attestation --insecure-ignore-tlog --key path/to/cosign.pub --signature sig --type slsaprovenance --check-claims=false /dev/null <1> +---- +<1> Replace `path/to/cosign.pub` with the path name of the public key file. ++ +.Example output [source,terminal] ---- -$ cosign verify-blob --key k8s://openshift-pipelines/signing-secrets --signature ./signature ./payload Verified OK ---- - - diff --git a/modules/op-installing-pipelines-operator-in-web-console.adoc b/modules/op-installing-pipelines-operator-in-web-console.adoc index e94e646dc4..ebcb8284ef 100644 --- a/modules/op-installing-pipelines-operator-in-web-console.adoc +++ b/modules/op-installing-pipelines-operator-in-web-console.adoc @@ -74,7 +74,7 @@ $ oc get tektonconfig config .Example output ---- NAME VERSION READY REASON -config 1.9.2 True +config 1.11.0 True ---- + If the *READY* condition is *True*, the Operator and its components have been installed successfully. @@ -83,17 +83,23 @@ Additonally, check the components' versions by running the following command: + [source,terminal] ---- -$ oc get tektonpipeline,tektontrigger,tektonaddon,pac +$ oc get tektonpipeline,tektontrigger,tektonchain,tektonaddon,pac ---- + .Example output ---- NAME VERSION READY REASON -tektonpipeline.operator.tekton.dev/pipeline v0.41.1 True +tektonpipeline.operator.tekton.dev/pipeline v0.47.0 True + NAME VERSION READY REASON -tektontrigger.operator.tekton.dev/trigger v0.22.2 True +tektontrigger.operator.tekton.dev/trigger v0.23.1 True + NAME VERSION READY REASON -tektonaddon.operator.tekton.dev/addon 1.9.2 True +tektonchain.operator.tekton.dev/chain v0.16.0 True + +NAME VERSION READY REASON +tektonaddon.operator.tekton.dev/addon 1.11.0 True + NAME VERSION READY REASON -openshiftpipelinesascode.operator.tekton.dev/pipelines-as-code v0.15.5 True +openshiftpipelinesascode.operator.tekton.dev/pipelines-as-code v0.19.0 True ---- diff --git a/modules/op-signing-secrets-in-tekton-chains.adoc b/modules/op-signing-secrets-in-tekton-chains.adoc index 924b922537..54d1307f16 100644 --- a/modules/op-signing-secrets-in-tekton-chains.adoc +++ b/modules/op-signing-secrets-in-tekton-chains.adoc @@ -4,10 +4,10 @@ :_content-type: CONCEPT [id="signing-secrets-in-tekton-chains_{context}"] -= Signing secrets in {tekton-chains} += Secrets for signing data in {tekton-chains} [role="_abstract"] -Cluster administrators can generate a key pair and use {tekton-chains} to sign artifacts using a Kubernetes secret. For {tekton-chains} to work, a private key and a password for encrypted keys must exist as part of the `signing-secrets` Kubernetes secret, in the `openshift-pipelines` namespace. +Cluster administrators can generate a key pair and use {tekton-chains} to sign artifacts using a Kubernetes secret. For {tekton-chains} to work, a private key and a password for encrypted keys must exist as part of the `signing-secrets` secret in the `openshift-pipelines` namespace. Currently, {tekton-chains} supports the `x509` and `cosign` signature schemes. @@ -16,46 +16,4 @@ Currently, {tekton-chains} supports the `x509` and `cosign` signature schemes. Use only one of the supported signature schemes. ==== -[id="chains-signing-secrets-x509_{context}"] -== Signing using x509 - -To use the `x509` signing scheme with {tekton-chains}, store the `x509.pem` private key of the `ed25519` or `ecdsa` type in the `signing-secrets` Kubernetes secret. Ensure that the key is stored as an unencrypted PKCS8 PEM file (`BEGIN PRIVATE KEY`). - -[id="chains-signing-secrets-cosign_{context}"] -== Signing using cosign - -To use the `cosign` signing scheme with {tekton-chains}: - -. Install link:https://docs.sigstore.dev/cosign/installation/[cosign]. - -. Generate the `cosign.key` and `cosign.pub` key pairs. -+ -[source,terminal] ----- -$ cosign generate-key-pair k8s://openshift-pipelines/signing-secrets ----- -+ -Cosign prompts you for a password, and creates a Kubernetes secret. - -. Store the encrypted `cosign.key` private key and the `cosign.password` decryption password in the `signing-secrets` Kubernetes secret. Ensure that the private key is stored as an encrypted PEM file of the `ENCRYPTED COSIGN PRIVATE KEY` type. - -[id="chains-troubleshooting-signing_{context}"] -== Troubleshooting signing - -If the signing secrets are already populated, you might get the following error: - -[source,yaml] ----- -Error from server (AlreadyExists): secrets "signing-secrets" already exists ----- - -To resolve the error: - -. Delete the secrets: -+ -[source,terminal] ----- -$ oc delete secret signing-secrets -n openshift-pipelines ----- - -. Recreate the key pairs and store them in the secrets using your preferred signing scheme. \ No newline at end of file +To use the `x509` signing scheme with {tekton-chains}, store the `x509.pem` private key of the `ed25519` or `ecdsa` type in the `signing-secrets` Kubernetes secret. diff --git a/modules/op-supported-keys-tekton-chains-configuration.adoc b/modules/op-supported-keys-tekton-chains-configuration.adoc deleted file mode 100644 index e314fbc496..0000000000 --- a/modules/op-supported-keys-tekton-chains-configuration.adoc +++ /dev/null @@ -1,56 +0,0 @@ -// This module is included in the following assembly: -// -// *cicd/pipelines/using-tekton-chains-for-pipelines-supply-chain-security.adoc - -:_content-type: REFERENCE -[id="supported-keys-tekton-chains-configuration_{context}"] -= Supported keys for {tekton-chains} configuration - -Cluster administrators can use various supported keys and values to configure specifications about task runs, OCI images, and storage. - -[id="chains-supported-keys-task-run_{context}"] -== Supported keys for task run - -.Chains configuration: Supported keys for task run -[options="header"] -|=== - -| Supported keys | Description | Supported values | Default values - -| `artifacts.taskrun.format` | The format to store task run payloads. | `tekton`, `in-toto` | `tekton` - -| `artifacts.taskrun.storage` | The storage backend for task run signatures. You can specify multiple backends as a comma-separated list, such as `“tekton,oci”`. To disable this artifact, provide an empty string `“”`. | `tekton`, `oci` | `tekton` - -| `artifacts.taskrun.signer` | The signature backend to sign task run payloads. | `x509` | `x509` - -|=== - -[id="chains-supported-keys-oci_{context}"] -== Supported keys for OCI - -.Chains configuration: Supported keys for OCI -[options="header"] -|=== - -| Supported keys | Description | Supported values | Default values - -| `artifacts.oci.format` | The format to store OCI payloads. | `simplesigning` | `simplesigning` - -| `artifacts.oci.storage` | The storage backend to for OCI signatures. You can specify multiple backends as a comma-separated list, such as `“oci,tekton”`. To disable the OCI artifact, provide an empty string `“”`. | `tekton`, `oci` | `oci` - -| `artifacts.oci.signer` | The signature backend to sign OCI payloads. | `x509`, `cosign` | `x509` - -|=== - -[id="chains-supported-keys-storage_{context}"] -== Supported keys for storage - -.Chains configuration: Supported keys for storage -[options="header"] -|=== - -| Supported keys | Description | Supported values | Default values - -| `artifacts.oci.repository` | The OCI repository to store OCI signatures. | Currently, Chains support only the internal OpenShift OCI registry; other popular options such as link:https://quay.io/[Quay] is not supported. | - -|=== diff --git a/modules/op-supported-parameters-tekton-chains-configuration.adoc b/modules/op-supported-parameters-tekton-chains-configuration.adoc new file mode 100644 index 0000000000..696ae20e90 --- /dev/null +++ b/modules/op-supported-parameters-tekton-chains-configuration.adoc @@ -0,0 +1,275 @@ +// This module is included in the following assembly: +// +// *cicd/pipelines/using-tekton-chains-for-pipelines-supply-chain-security.adoc + +:_content-type: REFERENCE +[id="supported-parameters-tekton-chains-configuration_{context}"] += Supported parameters for {tekton-chains} configuration + +Cluster administrators can use various supported parameter keys and values to configure specifications about task runs, OCI images, and storage. + +[id="chains-supported-parameters-task-run_{context}"] +== Supported parameters for task run artifacts + +.Chains configuration: Supported parameters for task run artifacts +[options="header"] +|=== + +| 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 multiple backends as a comma-separated list, such as `“tekton,oci”`. To disable storing task run artifacts, provide an empty string `“”`. +| `tekton`, `oci`, `gcs`, `docdb`, `grafeas` +| `tekton` + +| `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. +==== + +[id="chains-supported-parameters-pipeline-run_{context}"] +== Supported parameters for pipeline run artifacts + +.Chains configuration: Supported parameters for pipeline run artifacts +[options="header"] +|=== + +| 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 multiple backends as a comma-separated list, such as `“tekton,oci”`. To disable storing pipeline run artifacts, provide an empty string `“”`. +| `tekton`, `oci`, `gcs`, `docdb`, `grafeas` +| `tekton` + +| `artifacts.pipelinerun.signer` +| The signature backend for signing pipeline run payloads. +| `x509`, `kms` +| `x509` +|=== + +[NOTE] +==== +* `slsa/v1` is an alias of `in-toto` for backwards compatibility. +* For the `grafeas` storage backend, only Container Analysis is supported. You can not configure the `grafeas` server address in the current version of {tekton-chains}. +==== + +[id="chains-supported-parameters-oci_{context}"] +== Supported parameters for OCI artifacts + +.Chains configuration: Supported parameters for OCI artifacts +[options="header"] +|=== + +| 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 multiple backends as a comma-separated list, such as `“oci,tekton”`. To disable storing OCI artifacts, provide an empty string `“”`. +| `tekton`, `oci`, `gcs`, `docdb`, `grafeas` +| `oci` + +| `artifacts.oci.signer` +| The signature backend for signing OCI payloads. +| `x509`, `kms` +| `x509` + +|=== + +[id="chains-supported-parameters-kms_{context}"] +== Supported parameters for KMS signers + +.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 link:https://docs.sigstore.dev/cosign/kms_support[KMS Support] in the Sigstore documentation for more details. +| +|=== + +[id="chains-supported-parameters-storage_{context}"] +== Supported parameters for storage + +.Chains configuration: Supported parameters for storage +[options="header"] +|=== + +| Parameter | Description | Supported values | Default value + +| `storage.gcs.bucket` +| The GCS bucket for storage +| +| + +| `artifacts.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 link:https://github.com/sigstore/cosign#specifying-registry[cosign documentation] for additional information. +| + +| `builder.id` +| The builder ID to set for in-toto attestations +| +| `+https://tekton.dev/chains/v2+` + +|=== + +If you enable the `docdb` storage method is for any artifacts, configure docstore storage options. For more information about the go-cloud docstore URI format, see the link:https://gocloud.dev/howto/docstore/[docstore package documentation]. {pipelines-title} supports the following docstore services: + +* `firestore` +* `dynamodb` + +.Chains configuration: Supported parameters for `docstore` storage +[options="header"] +|=== + +| Parameter | Description | Supported values | Default value + + +| `storage.docdb.url` +| The go-cloud URI reference to a `docstore` collection. Used if the `docdb` storage method is enabled for any artifacts. +| `firestore://projects/[PROJECT]/databases/(default)/documents/[COLLECTION]?name_field=name` +| + +|=== + +If you enable the `grafeas` storage method for any artifacts, configure Grafeas storage options. For more information about Grafeas notes and occurrences, see link:https://github.com/grafeas/grafeas/blob/master/docs/grafeas_concepts.md[Grafeas concepts]. + +To create occurrences, {pipelines-title} must first create notes that are used to link occurrences. {pipelines-title} creates two types of occurrences: `ATTESTATION` Occurrence and `BUILD` Occurrence. + +{pipelines-title} 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, {pipelines-title} uses `tekton-` as the prefix. + +.Chains configuration: Supported parameters for Grafeas storage +[options="header"] +|=== + +| Parameter | Description | Supported values | Default value + +| `storage.grafeas.projectid` +| The {OCP} project in which the Grafeas server for storing occurrences is located. +| +| + +| `storage.grafeas.noteid` +| Optional: the prefix to use for the name of all created notes. +| A string without spaces. +| + +| `storage.grafeas.notehint` +| Optional: the https://github.com/grafeas/grafeas/blob/cd23d4dc1bef740d6d6d90d5007db5c9a2431c41/proto/v1/attestation.proto#L49[`human_readable_name`] field for the Grafeas `ATTESTATION` note. +| +|`This attestation note was generated by Tekton Chains` +|=== + +Optionally, you can enable additional uploads of binary transparency attestations. + +.Chains configuration: Supported parameters for transparency attestation storage +[options="header"] +|=== + +| 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`, only task runs and pipeline runs with the following annotation are uploaded to the transparency log: + +[source,yaml] +---- +chains.tekton.dev/transparency-upload: "true" +---- + +If you configure the `x509` signature backend, you can optionally enable keyless signing with Fulcio. + +.Chains configuration: Supported parameters for `x509` keyless signing with Fulcio +[options="header"] +|=== + +| 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 OIDC issuer. +| +| `+https://oauth2.sigstore.dev/auth+` + +| `signers.x509.fulcio.provider` +| The provider from which to request the ID Token. +| `google`, `spiffe`, `github`, `filesystem` +| {pipelines-title} 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 TUF server. `$TUF_URL/root.json` must be present. +| +| `+https://sigstore-tuf-root.storage.googleapis.com+` +|=== + +If you configure the `kms` signature backend, set the KMS configuration, including OIDC and Spire, as necessary. + +.Chains configuration: Supported parameters for KMS signing +[options="header"] +|=== + +| Parameter | Description | Supported values | Default value + +| `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`). + +| `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 SVID from Spire. +|===