Skip to content

Commit 0137faf

Browse files
gabriel-rhgabriel-rh
authored
Merge pull request #59627 from mramendi/tekton-chains-ga
RHDEVDOCS-5246: Tekton Chains configuration changes for GA
2 parents acd67d3 + edfbb34 commit 0137faf

10 files changed

+497
-152
lines changed

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

Lines changed: 11 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -6,38 +6,35 @@ include::_attributes/common-attributes.adoc[]
66

77
toc::[]
88

9-
:FeatureName: Tekton Chains
10-
include::snippets/technology-preview.adoc[]
11-
129
[role="_abstract"]
1310
{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}.
1411

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.
12+
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.
1813

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-
====
14+
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.
2315

2416
[id="tc-key-features"]
2517
== Key features
26-
* You can sign task runs, task run results, and OCI registry images with cryptographic key types and services such as `cosign`.
18+
* 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`.
2719
* You can use attestation formats such as `in-toto`.
2820
* You can securely store signatures and signed artifacts using OCI repository as a storage backend.
2921

30-
include::modules/op-installing-tekton-chains-using-pipelines-operator.adoc[leveloffset=+1]
31-
3222
include::modules/op-configuring-tekton-chains.adoc[leveloffset=+1]
3323

34-
include::modules/op-supported-keys-tekton-chains-configuration.adoc[leveloffset=+2]
24+
include::modules/op-supported-parameters-tekton-chains-configuration.adoc[leveloffset=+2]
3525

3626
include::modules/op-signing-secrets-in-tekton-chains.adoc[leveloffset=+1]
27+
include::modules/op-chains-signing-secrets-cosign.adoc[leveloffset=+2]
28+
include::modules/op-chains-signing-secrets-skopeo.adoc[leveloffset=+2]
29+
include::modules/op-chains-resolving-existing-secret.adoc[leveloffset=+2]
3730

3831
include::modules/op-authenticating-to-an-oci-registry.adoc[leveloffset=+1]
3932

4033
include::modules/op-creating-and-verifying-task-run-signatures-without-any-additional-authentication.adoc[leveloffset=+1]
34+
=== Additional resources
35+
36+
* xref:signing-secrets-in-tekton-chains_{context}[]
37+
* xref:configuring-tekton-chains_{context}[]
4138

4239
include::modules/op-using-tekton-chains-to-sign-and-verify-image-and-provenance.adoc[leveloffset=+1]
4340

@@ -46,4 +43,3 @@ include::modules/op-using-tekton-chains-to-sign-and-verify-image-and-provenance.
4643
== Additional resources
4744

4845
* xref:../../cicd/pipelines/installing-pipelines.adoc#installing-pipelines[Installing {pipelines-shortname}]
49-

‎modules/op-chains-resolving-existing-secret.adoc

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
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+
7+
[id="chains-resolving-existing-secret_{context}"]
8+
= Resolving the "secret already exists" error
9+
10+
If the `signing-secret` secret is already populated, the command to create this secret might output the following error message:
11+
12+
[source,terminal]
13+
----
14+
Error from server (AlreadyExists): secrets "signing-secrets" already exists
15+
----
16+
17+
You can resolve this error by deleting the secret.
18+
19+
.Procedure
20+
21+
. Delete the `signing-secret` secret by running the following command:
22+
+
23+
[source,terminal]
24+
----
25+
$ oc delete secret signing-secrets -n openshift-pipelines
26+
----
27+
28+
. Re-create the key pairs and store them in the secret using your preferred signing scheme.

‎modules/op-chains-signing-secrets-cosign.adoc

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
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+
7+
[id="chains-signing-secrets-cosign_{context}"]
8+
= Signing using cosign
9+
10+
You can use the `cosign` signing scheme with {tekton-chains} using the `cosign` tool.
11+
12+
.Prerequisites
13+
14+
* You installed the link:https://docs.sigstore.dev/cosign/installation/[cosign] tool.
15+
16+
.Procedure
17+
18+
. Generate the `cosign.key` and `cosign.pub` key pairs by running the following command:
19+
+
20+
[source,terminal]
21+
----
22+
$ cosign generate-key-pair k8s://openshift-pipelines/signing-secrets
23+
----
24+
+
25+
Cosign prompts you for a password and then creates a Kubernetes secret.
26+
27+
. 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.

‎modules/op-chains-signing-secrets-skopeo.adoc

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
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+
7+
[id="chains-signing-secrets-skopeo_{context}"]
8+
= Signing using skopeo
9+
10+
You can generate keys using the `skopeo` tool and use them in the `cosign` signing scheme with {tekton-chains}.
11+
12+
.Prerequisites
13+
14+
* You installed the link:https://github.com/containers/skopeo[skopeo] tool.
15+
16+
.Procedure
17+
18+
. Generate a public/private key pair by running the following command:
19+
+
20+
[source,terminal]
21+
----
22+
$ skopeo generate-sigstore-key --output-prefix <mykey> # <1>
23+
----
24+
<1> Replace `<mykey>` with a key name of your choice.
25+
+
26+
Skopeo prompts you for a passphrase for the private key and then creates the key files named `<mykey>.private` and `<mykey>.pub`.
27+
28+
. Encode the `<mykey>.pub` file using the `base64` tool by running the following command:
29+
+
30+
[source,terminal]
31+
----
32+
$ base64 -w 0 <mykey>.pub > b64.pub
33+
----
34+
35+
. Encode the `<mykey>.private` file using the `base64` tool by running the following command:
36+
+
37+
[source,terminal]
38+
----
39+
$ base64 -w 0 <mykey>.private > b64.private
40+
----
41+
42+
. Encode the passhprase using the `base64` tool by running the following command:
43+
+
44+
[source,terminal]
45+
----
46+
$ echo -n '<passphrase>' | base64 -w 0 > b64.passphrase # <1>
47+
----
48+
<1> Replace `<passphrase>` with the passphrase that you used for the key pair.
49+
50+
. Create the `signing-secrets` secret in the `openshift-pipelines` namespace by running the following command:
51+
+
52+
[source,terminal]
53+
----
54+
$ oc create secret generic signing-secrets -n openshift-pipelines
55+
----
56+
+
57+
. Edit the `signing-secrets` secret by running the following command:
58+
----
59+
$ oc edit secret -n openshift-pipelines signing-secrets
60+
----
61+
+
62+
Add the encoded keys in the data of the secret in the following way:
63+
+
64+
[source,yaml]
65+
----
66+
apiVersion: v1
67+
data:
68+
cosign.key: <Encoded <mykey>.private> # <1>
69+
cosign.password: <Encoded passphrase> # <2>
70+
cosign.pub: <Encoded <mykey>.pub> # <3>
71+
immutable: true
72+
kind: Secret
73+
metadata:
74+
name: signing-secrets
75+
# ...
76+
type: Opaque
77+
----
78+
<1> Replace `<Encoded <mykey>.private>` with the content of the `b64.private` file.
79+
<2> Replace `<Encoded passphrase>` with the content of the `b64.passphrase` file.
80+
<3> Replace `<Encoded <mykey>.pub>` with the content of the `b64.pub` file.

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

Lines changed: 17 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,14 +6,26 @@
66
[id="configuring-tekton-chains_{context}"]
77
= Configuring {tekton-chains}
88

9-
{tekton-chains} uses a `ConfigMap` object named `chains-config` in the `openshift-pipelines` namespace for configuration.
9+
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.
1010

11-
To configure {tekton-chains}, use the following example:
11+
To edit the custom resource, use the following command:
1212

13-
.Example: Configuring {tekton-chains}
1413
[source,terminal]
1514
----
16-
$ oc patch configmap chains-config -n openshift-pipelines -p='{"data":{"artifacts.oci.storage": "", "artifacts.taskrun.format":"tekton", "artifacts.taskrun.storage": "tekton"}}' <1>
15+
$ oc edit TektonConfig config
1716
----
18-
<1> Use a combination of supported key-value pairs in the JSON payload.
1917

18+
The custom resource includes a `chain:` array. You can add any supported configuration parameters to this array, as shown in the following example:
19+
20+
[source,yaml]
21+
----
22+
apiVersion: operator.tekton.dev/v1alpha1
23+
kind: TektonConfig
24+
metadata:
25+
name: config
26+
spec:
27+
addon: {}
28+
chain:
29+
artifacts.taskrun.format: tekton
30+
config: {}
31+
----

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

Lines changed: 44 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
:_content-type: PROCEDURE
66
[id="creating-and-verifying-task-run-signatures-without-any-additional-authentication_{context}"]
7-
== Creating and verifying task run signatures without any additional authentication
7+
= Creating and verifying task run signatures without any additional authentication
88

99
[role="_abstract"]
1010
To verify signatures of task runs using {tekton-chains} with any additional authentication, perform the following tasks:
@@ -16,51 +16,64 @@ To verify signatures of task runs using {tekton-chains} with any additional auth
1616
* Verify the signature of the task run.
1717
1818
.Prerequisites
19-
Ensure that the following are installed on the cluster:
19+
Ensure that the following components are installed on the cluster:
2020

2121
* {pipelines-title} Operator
2222
* {tekton-chains}
2323
* link:https://docs.sigstore.dev/cosign/installation/[Cosign]
2424
2525
.Procedure
2626

27-
. Create an encrypted x509 key pair and save it as a Kubernetes secret:
27+
. 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}".
28+
. 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:
2829
+
29-
[source,terminal]
30+
[source,yaml]
3031
----
31-
$ cosign generate-key-pair k8s://openshift-pipelines/signing-secrets
32+
apiVersion: operator.tekton.dev/v1alpha1
33+
kind: TektonConfig
34+
metadata:
35+
name: config
36+
spec:
37+
# ...
38+
chain:
39+
artifacts.oci.storage: ""
40+
artifacts.taskrun.format: tekton
41+
artifacts.taskrun.storage: tekton
42+
# ...
3243
----
3344
+
34-
Provide a password when prompted. Cosign stores the resulting private key as part of the `signing-secrets` Kubernetes secret in the `openshift-pipelines` namespace.
35-
36-
. In the {tekton-chains} configuration, disable the OCI storage, and set the task run storage and format to `tekton`.
37-
+
38-
[source,terminal]
39-
----
40-
$ oc patch configmap chains-config -n openshift-pipelines -p='{"data":{"artifacts.oci.storage": "", "artifacts.taskrun.format":"tekton", "artifacts.taskrun.storage": "tekton"}}'
41-
----
42-
43-
. Restart the {tekton-chains} controller to ensure that the modified configuration is applied.
45+
For more information about configuring {tekton-chains} using the `TektonConfig` custom resource, see "Configuring {tekton-chains}".
46+
. To restart the {tekton-chains} controller to ensure that the modified configuration is applied, enter the following command:
4447
+
4548
[source.terminal]
4649
----
4750
$ oc delete po -n openshift-pipelines -l app=tekton-chains-controller
4851
----
4952

50-
. Create a task run.
53+
. Create a task run by entering the following command:
5154
+
5255
[source,terminal]
5356
----
5457
$ oc create -f https://raw.githubusercontent.com/tektoncd/chains/main/examples/taskruns/task-output-image.yaml <1>
58+
----
59+
<1> Replace the example URI with the URI or file path pointing to your task run.
60+
+
61+
.Example output
62+
[source,terminal]
63+
----
5564
taskrun.tekton.dev/build-push-run-output-image-qbjvh created
5665
----
57-
<1> Substitute with the URI or file path pointing to your task run.
5866

59-
. Check the status of the steps, and wait till the process finishes.
67+
. Check the status of the steps by entering the following command. Wait until the process finishes.
6068
+
6169
[source,terminal]
6270
----
6371
$ tkn tr describe --last
72+
----
73+
+
74+
.Example output
75+
[source,terminal]
76+
----
6477
[...truncated output...]
6578
NAME STATUS
6679
∙ create-dir-builtimage-9467f Completed
@@ -70,21 +83,27 @@ NAME STATUS
7083
∙ image-digest-exporter-xlkn7 Completed
7184
----
7285

73-
. Retrieve the signature and payload from the object stored as `base64` encoded annotations:
86+
. To retrieve the signature from the object stored as `base64` encoded annotations, enter the following commands:
87+
+
88+
[source,terminal]
89+
----
90+
$ tkn tr describe --last -o jsonpath="{.metadata.annotations.chains\.tekton\.dev/signature-taskrun-$TASKRUN_UID}" | base64 -d > sig
91+
----
7492
+
7593
[source,terminal]
7694
----
7795
$ export TASKRUN_UID=$(tkn tr describe --last -o jsonpath='{.metadata.uid}')
78-
$ tkn tr describe --last -o jsonpath="{.metadata.annotations.chains\.tekton\.dev/signature-taskrun-$TASKRUN_UID}" > signature
79-
$ tkn tr describe --last -o jsonpath="{.metadata.annotations.chains\.tekton\.dev/payload-taskrun-$TASKRUN_UID}" | base64 -d > payload
8096
----
8197

82-
. Verify the signature.
98+
. To verify the signature using the public key that you created, enter the following command:
99+
[source,terminal]
100+
----
101+
$ cosign verify-blob-attestation --insecure-ignore-tlog --key path/to/cosign.pub --signature sig --type slsaprovenance --check-claims=false /dev/null <1>
102+
----
103+
<1> Replace `path/to/cosign.pub` with the path name of the public key file.
83104
+
105+
.Example output
84106
[source,terminal]
85107
----
86-
$ cosign verify-blob --key k8s://openshift-pipelines/signing-secrets --signature ./signature ./payload
87108
Verified OK
88109
----
89-
90-

‎modules/op-installing-pipelines-operator-in-web-console.adoc

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@ $ oc get tektonconfig config
7474
.Example output
7575
----
7676
NAME VERSION READY REASON
77-
config 1.9.2 True
77+
config 1.11.0 True
7878
----
7979
+
8080
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:
8383
+
8484
[source,terminal]
8585
----
86-
$ oc get tektonpipeline,tektontrigger,tektonaddon,pac
86+
$ oc get tektonpipeline,tektontrigger,tektonchain,tektonaddon,pac
8787
----
8888
+
8989
.Example output
9090
----
9191
NAME VERSION READY REASON
92-
tektonpipeline.operator.tekton.dev/pipeline v0.41.1 True
92+
tektonpipeline.operator.tekton.dev/pipeline v0.47.0 True
93+
9394
NAME VERSION READY REASON
94-
tektontrigger.operator.tekton.dev/trigger v0.22.2 True
95+
tektontrigger.operator.tekton.dev/trigger v0.23.1 True
96+
9597
NAME VERSION READY REASON
96-
tektonaddon.operator.tekton.dev/addon 1.9.2 True
98+
tektonchain.operator.tekton.dev/chain v0.16.0 True
99+
100+
NAME VERSION READY REASON
101+
tektonaddon.operator.tekton.dev/addon 1.11.0 True
102+
97103
NAME VERSION READY REASON
98-
openshiftpipelinesascode.operator.tekton.dev/pipelines-as-code v0.15.5 True
104+
openshiftpipelinesascode.operator.tekton.dev/pipelines-as-code v0.19.0 True
99105
----

0 commit comments

Comments
 (0)