Skip to content

Commit 70bff76

Browse files
JSticklerJStickler
authored
Merge pull request #43302 from sounix000/3751-tekton-chains
RHDEVDOCS-3751 Document Tekton Chains
2 parents be48078 + 4e6d877 commit 70bff76

11 files changed

+545
-0
lines changed

‎_attributes/common-attributes.adoc

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,7 @@ endif::[]
7070
:pipelines-title: Red Hat OpenShift Pipelines
7171
:pipelines-shortname: Pipelines
7272
:pipelines-ver: pipelines-1.7
73+
:tekton-chains: Tekton Chains
7374
//odo
7475
:odo-title: odo
7576
//alibaba cloud

‎_topic_maps/_topic_map.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1598,6 +1598,8 @@ Topics:
15981598
File: securing-webhooks-with-event-listeners
15991599
- Name: Authenticating pipelines using git secret
16001600
File: authenticating-pipelines-using-git-secret
1601+
- Name: Using Tekton Chains for OpenShift Pipelines supply chain security
1602+
File: using-tekton-chains-for-openshift-pipelines-supply-chain-security
16011603
- Name: Viewing pipeline logs using the OpenShift Logging Operator
16021604
File: viewing-pipeline-logs-using-the-openshift-logging-operator
16031605
- Name: GitOps

‎cicd/pipelines/installing-pipelines.adoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,8 @@ include::modules/op-disabling-automatic-creation-of-rbac-resources.adoc[leveloff
4747

4848
* You can learn more about installing Operators on {product-title} in the xref:../../operators/admin/olm-adding-operators-to-cluster.adoc#olm-adding-operators-to-a-cluster[adding Operators to a cluster] section.
4949

50+
* To install Tekton Chains using the {pipelines-title} Operator, see xref:../../cicd/pipelines/using-tekton-chains-for-openshift-pipelines-supply-chain-security.adoc#using-tekton-chains-for-openshift-pipelines-supply-chain-security[Using Tekton Chains for OpenShift Pipelines supply chain security].
51+
5052
* For more information on using pipelines in a restricted environment, see:
5153

5254
** xref:../../cicd/pipelines/creating-applications-with-cicd-pipelines.html#op-mirroring-images-to-run-pipelines-in-restricted-environment_creating-applications-with-cicd-pipelines[Mirroring images to run pipelines in a restricted environment]

‎cicd/pipelines/using-tekton-chains-for-openshift-pipelines-supply-chain-security.adoc

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
:_content-type: ASSEMBLY
2+
[id="using-tekton-chains-for-openshift-pipelines-supply-chain-security"]
3+
= Using Tekton Chains for OpenShift Pipelines supply chain security
4+
include::_attributes/common-attributes.adoc[]
5+
:context: using-tekton-chains-for-openshift-pipelines-supply-chain-security
6+
7+
toc::[]
8+
9+
:FeatureName: Tekton Chains
10+
include::snippets/technology-preview.adoc[]
11+
12+
[role="_abstract"]
13+
{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}.
14+
15+
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.
16+
17+
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.
18+
19+
[NOTE]
20+
====
21+
The `PipelineResource` object is deprecated and will be removed in a future release; for manual use, the `Results` object is recommended.
22+
====
23+
24+
[id="tc-key-features"]
25+
== Key features
26+
* You can sign task runs, task run results, and OCI registry images with cryptographic key types and services such as `cosign`.
27+
* You can use attestation formats such as `in-toto`.
28+
* You can securely store signatures and signed artifacts using OCI repository as a storage backend.
29+
30+
include::modules/op-installing-tekton-chains-using-pipelines-operator.adoc[leveloffset=+1]
31+
32+
include::modules/op-configuring-tekton-chains.adoc[leveloffset=+1]
33+
34+
include::modules/op-supported-keys-tekton-chains-configuration.adoc[leveloffset=+2]
35+
36+
include::modules/op-signing-secrets-in-tekton-chains.adoc[leveloffset=+1]
37+
38+
include::modules/op-authenticating-to-an-oci-registry.adoc[leveloffset=+1]
39+
40+
include::modules/op-creating-and-verifying-task-run-signatures-without-any-additional-authentication.adoc[leveloffset=+1]
41+
42+
include::modules/op-using-tekton-chains-to-sign-and-verify-image-and-provenance.adoc[leveloffset=+1]
43+
44+
[role="_additional-resources"]
45+
[id="additional-resources-tekton-chains"]
46+
== Additional resources
47+
48+
* xref:../../cicd/pipelines/installing-pipelines.adoc#installing-pipelines[Installing OpenShift Pipelines]
49+

‎modules/op-authenticating-to-an-oci-registry.adoc

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-tekton-chains-for-pipelines-supply-chain-security.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="authenticating-to-an-oci-registry_{context}"]
7+
= Authenticating to an OCI registry
8+
9+
Before pushing signatures to an OCI registry, cluster administrators must configure {tekton-chains} to authenticate with the registry. The {tekton-chains} controller uses the same service account under which the task runs execute. To set up a service account with the necessary credentials for pushing signatures to an OCI registry, perform the following steps:
10+
11+
[discrete]
12+
.Procedure
13+
14+
. Set the namespace and name of the Kubernetes service account.
15+
+
16+
[source,terminal]
17+
----
18+
$ export NAMESPACE=<namespace> <1>
19+
$ export SERVICE_ACCOUNT_NAME=<service_account> <2>
20+
----
21+
<1> The namespace associated with the service account.
22+
<2> The name of the service account.
23+
24+
. Create a Kubernetes secret.
25+
+
26+
[source,terminal]
27+
----
28+
$ oc create secret registry-credentials \
29+
--from-file=.dockerconfigjson \ <1>
30+
--type=kubernetes.io/dockerconfigjson \
31+
-n $NAMESPACE
32+
----
33+
<1> Substitute with the path to your Docker config file. Default path is `~/.docker/config.json`.
34+
35+
. Give the the service account access to the secret.
36+
+
37+
[source,terminal]
38+
----
39+
$ oc patch serviceaccount $SERVICE_ACCOUNT_NAME \
40+
-p "{\"imagePullSecrets\": [{\"name\": \"registry-credentials\"}]}" -n $NAMESPACE
41+
----
42+
+
43+
If you patch the default `pipeline` service account that {pipelines-title} assigns to all task runs, the {pipelines-title} Operator will override the service account. As a best practice, you can perform the following steps:
44+
45+
.. Create a separate service account to assign to user's task runs.
46+
+
47+
[source,terminal]
48+
----
49+
$ oc create serviceaccount <service_account_name>
50+
----
51+
52+
.. Associate the service account to the task runs by setting the value of the `serviceaccountname` field in the task run template.
53+
+
54+
[source,yaml]
55+
----
56+
apiVersion: tekton.dev/v1beta1
57+
kind: TaskRun
58+
metadata:
59+
name: build-push-task-run-2
60+
spec:
61+
serviceAccountName: build-bot <1>
62+
taskRef:
63+
name: build-push
64+
...
65+
----
66+
<1> Substitute with the name of the newly created service account.
67+
68+
69+

‎modules/op-configuring-tekton-chains.adoc

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-tekton-chains-for-pipelines-supply-chain-security.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="configuring-tekton-chains_{context}"]
7+
= Configuring {tekton-chains}
8+
9+
{tekton-chains} uses a `ConfigMap` object named `chains-config` in the `openshift-pipelines` namespace for configuration.
10+
11+
To configure {tekton-chains}, use the following example:
12+
13+
.Example: Configuring {tekton-chains}
14+
[source,terminal]
15+
----
16+
$ oc patch configmap chains-config -n openshift-pipelines -p='{"data":{"artifacts.oci.storage": "", "artifacts.taskrun.format":"tekton", "artifacts.taskrun.storage": "tekton"}}' <1>
17+
----
18+
<1> Use a combination of supported key-value pairs in the JSON payload.
19+

‎modules/op-creating-and-verifying-task-run-signatures-without-any-additional-authentication.adoc

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-tekton-chains-for-pipelines-supply-chain-security.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="creating-and-verifying-task-run-signatures-without-any-additional-authentication_{context}"]
7+
== Creating and verifying task run signatures without any additional authentication
8+
9+
[role="_abstract"]
10+
To verify signatures of task runs using {tekton-chains} with any additional authentication, perform the following tasks:
11+
12+
* Create an encrypted x509 key pair and save it as a Kubernetes secret.
13+
* Configure the {tekton-chains} backend storage.
14+
* Create a task run, sign it, and store the signature and the payload as annotations on the task run itself.
15+
* Retrieve the signature and payload from the signed task run.
16+
* Verify the signature of the task run.
17+
18+
[discrete]
19+
.Prerequisites
20+
Ensure that the following are installed on the cluster:
21+
22+
* {pipelines-title} Operator
23+
* {tekton-chains}
24+
* link:https://docs.sigstore.dev/cosign/installation/[Cosign]
25+
26+
[discrete]
27+
.Procedure
28+
29+
. Create an encrypted x509 key pair and save it as a Kubernetes secret:
30+
+
31+
[source,terminal]
32+
----
33+
$ cosign generate-key-pair k8s://openshift-pipelines/signing-secrets
34+
----
35+
+
36+
Provide a password when prompted. Cosign stores the resulting private key as part of the `signing-secrets` Kubernetes secret in the `openshift-pipelines` namespace.
37+
38+
. In the {tekton-chains} configuration, disable the OCI storage, and set the task run storage and format to `tekton`.
39+
+
40+
[source,terminal]
41+
----
42+
$ oc patch configmap chains-config -n openshift-pipelines -p='{"data":{"artifacts.oci.storage": "", "artifacts.taskrun.format":"tekton", "artifacts.taskrun.storage": "tekton"}}'
43+
----
44+
45+
. Restart the {tekton-chains} controller to ensure that the modified configuration is applied.
46+
+
47+
[source.terminal]
48+
----
49+
$ oc delete po -n openshift-pipelines -l app=tekton-chains-controller
50+
----
51+
52+
. Create a task run.
53+
+
54+
[source,terminal]
55+
----
56+
$ oc create -f https://raw.githubusercontent.com/tektoncd/chains/main/examples/taskruns/task-output-image.yaml <1>
57+
taskrun.tekton.dev/build-push-run-output-image-qbjvh created
58+
----
59+
<1> Substitute with the URI or file path pointing to your task run.
60+
61+
. Check the status of the steps, and wait till the process finishes.
62+
+
63+
[source,terminal]
64+
----
65+
$ tkn tr describe --last
66+
[...truncated output...]
67+
NAME STATUS
68+
∙ create-dir-builtimage-9467f Completed
69+
∙ git-source-sourcerepo-p2sk8 Completed
70+
∙ build-and-push Completed
71+
∙ echo Completed
72+
∙ image-digest-exporter-xlkn7 Completed
73+
----
74+
75+
. Retrieve the signature and payload from the object stored as `base64` encoded annotations:
76+
+
77+
[source,terminal]
78+
----
79+
$ export TASKRUN_UID=$(tkn tr describe --last -o jsonpath='{.metadata.uid}')
80+
$ tkn tr describe --last -o jsonpath="{.metadata.annotations.chains\.tekton\.dev/signature-taskrun-$TASKRUN_UID}" > signature
81+
$ tkn tr describe --last -o jsonpath="{.metadata.annotations.chains\.tekton\.dev/payload-taskrun-$TASKRUN_UID}" | base64 -d > payload
82+
----
83+
84+
. Verify the signature.
85+
+
86+
[source,terminal]
87+
----
88+
$ cosign verify-blob --key k8s://openshift-pipelines/signing-secrets --signature ./signature ./payload
89+
Verified OK
90+
----
91+
92+

‎modules/op-installing-tekton-chains-using-pipelines-operator.adoc

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-tekton-chains-for-pipelines-supply-chain-security.adoc
4+
5+
:_content-type: PROCEDURE
6+
[id="installing-tekton-chains-using-pipelines-operator_{context}"]
7+
= Installing {tekton-chains} using the {pipelines-title} Operator
8+
9+
Cluster administrators can use the `TektonChain` custom resource (CR) to install and manage {tekton-chains}.
10+
11+
[NOTE]
12+
====
13+
{tekton-chains} is an optional component of {pipelines-title}. Currently, you cannot install it using the `TektonConfig` CR.
14+
====
15+
16+
[discrete]
17+
.Prerequisites
18+
* Ensure that the {pipelines-title} Operator is installed in the `openshift-pipelines` namespace on your cluster.
19+
20+
[discrete]
21+
.Procedure
22+
23+
. Create the `TektonChain` CR for your {product-title} cluster.
24+
+
25+
[source,yaml]
26+
----
27+
apiVersion: operator.tekton.dev/v1alpha1
28+
kind: TektonChain
29+
metadata:
30+
name: chain
31+
spec:
32+
targetNamespace: openshift-pipelines
33+
----
34+
35+
. Apply the `TektonChain` CR.
36+
+
37+
[source,terminal]
38+
----
39+
$ oc apply -f TektonChain.yaml <1>
40+
----
41+
+
42+
<1> Substitute with the file name of the `TektonChain` CR.
43+
44+
. Check the status of the installation.
45+
+
46+
[source,terminal]
47+
----
48+
$ oc get tektonchains.operator.tekton.dev
49+
----
50+
51+

‎modules/op-signing-secrets-in-tekton-chains.adoc

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
// This module is included in the following assembly:
2+
//
3+
// *cicd/pipelines/using-tekton-chains-for-pipelines-supply-chain-security.adoc
4+
5+
:_content-type: CONCEPT
6+
[id="signing-secrets-in-tekton-chains_{context}"]
7+
= Signing secrets in {tekton-chains}
8+
9+
[role="_abstract"]
10+
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.
11+
12+
Currently, {tekton-chains} supports the `x509` and `cosign` signature schemes.
13+
14+
[NOTE]
15+
====
16+
Use only one of the supported signature schemes.
17+
====
18+
19+
[id="chains-signing-secrets-x509_{context}"]
20+
== Signing using x509
21+
22+
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`).
23+
24+
[id="chains-signing-secrets-cosign_{context}"]
25+
== Signing using cosign
26+
27+
To use the `cosign` signing scheme with {tekton-chains}:
28+
29+
. Install link:https://docs.sigstore.dev/cosign/installation/[cosign].
30+
31+
. Generate the `cosign.key` and `cosign.pub` key pairs.
32+
+
33+
[source,terminal]
34+
----
35+
$ cosign generate-key-pair k8s://openshift-pipelines/signing-secrets
36+
----
37+
+
38+
Cosign prompts you for a password, and creates a Kubernetes secret.
39+
40+
. 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.
41+
42+
[id="chains-troubleshooting-signing_{context}"]
43+
== Troubleshooting signing
44+
45+
If the signing secrets are already populated, you might get the following error:
46+
47+
[source,yaml]
48+
----
49+
Error from server (AlreadyExists): secrets "signing-secrets" already exists
50+
----
51+
52+
To resolve the error:
53+
54+
. Delete the secrets:
55+
+
56+
[source,terminal]
57+
----
58+
$ oc delete secret signing-secrets -n openshift-pipelines
59+
----
60+
61+
. Recreate the key pairs and store them in the secrets using your preferred signing scheme.

0 commit comments

Comments
 (0)