Skip to content

Commit 4e6d877

Browse files
author
Souvik Sarkar
committed
tekton chains
revisions in titles revisions in titles revisions in titles revisions in titles revisions in titles revisions in titles revisions in titles revisions in titles revisions in titles trying to fix section heading anomaly introduction and key features installation installation troubleshooting build error due to duplicate id random intermediate checkin finalizing structure and fixing build error typo; fixing build error finalizing structure and fixing build error complete draft review comments final changes
1 parent be48078 commit 4e6d877

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)