Skip to content

RHDEVDOCS 6410 Chains automatic Cosign key pair #93507

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 27, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions modules/op-chains-generating-cosign-secret.adoc
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
// This module is included in the following assemblies:
// * secure/using-tekton-chains-for-openshift-pipelines-supply-chain-security.adoc

:_mod-docs-content-type: PROCEDURE
[id="chains-generating-cosign-secret_{context}"]
= Generating the cosign key pair by using the TektonConfig CR

To use the `cosign` signing scheme for {tekton-chains} secrets, you can generate a `cosign` key pair that uses ECDSA encryption by setting the `generateSigningSecret` field in the `TektonConfig` custom resource (CR) to `true`.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will the intended audience know what ECDSA stands for? If not, consider spelling it out.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It will, especially with the word "encryption".


.Prerequisites

* You installed the {oc-first} utility.
* You are logged in to your {OCP} cluster with administrative rights for the `openshift-pipelines` namespace.

.Procedure

. Edit the `TektonConfig` CR by running the following command:
+
[source,terminal]
----
$ oc edit TektonConfig config
----

. In the `TektonConfig` CR, set the `generateSigningSecret` value to `true`:
+
.Example of creating an ECDSA cosign key pair by using the TektonConfig CR
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since I've been tagged here, I tested the file to ensure it does convert to DITA without any issues and it does. The only thing that gets flagged during conversion is this block title which is assigned to a code block, something that DITA has no equivalent markup for. DITA does allow titles to be assigned to example blocks (would need to be marked up as such in AsciiDoc with the [Example] attribute headr or the ==== delimiter), but only allows one example in the main body of the task, not nested within a step.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! This is a good question but it's commonly used in docs, including RNs, so we'll have to come up with some way of converting them - or drop the titles on a case-by-case basis. This one can probably be dropped when moving to DITA. While we're on Asciidoc I want this one to be consistent with the rest of the docs.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I absolutely agree, and this is not a blocker and we have plenty of time to figure out what to do with titles like these, I just highlighted this for awareness. The module builds and the conversion tool falls back to using a paragraph with bold text and assigned output class to clearly identify where that text came from.

[source,yaml]
----
apiVersion: operator.tekton.dev/v1
kind: TektonConfig
metadata:
name: config
spec:
# ...
chain:
disabled: false
generateSigningSecret: true # <1>
# ...
----
<1> The default value is `false`. Setting the value to `true` generates the `ecdsa` key pair.

. After a few minutes, extract the public key from the secret and store it, so that you can use it to verify artifact attestations. Run the following command to extract the key:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will the phrase "artifact attestations" be familiar to the intended audience of this doc? I don't see similar phrasing when I search the openshift-docs repo.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+
[source,terminal]
----
$ oc extract -n openshift-pipelines secret/signing-secrets --keys=cosign.pub
----

.Result
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I haven't seen this type of heading used in a procedure before. See the procedure template from the modular documentation guidelines: https://raw.githubusercontent.com/redhat-documentation/modular-docs/master/modular-docs-manual/files/TEMPLATE_PROCEDURE_doing-one-procedure.adoc

I wonder if "Verification" would work here instead?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately Verification will not work as there is no verification procedure. I thought Result was added as this is a direct DITA reference; I'll double check

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have now checked with @jhradilek and Result is now supported


The {pipelines-shortname} Operator generates an `ecdsa` type `cosign` key pair and stores it in the `signing-secrets` secret in the `openshift-pipelines` namespace. The secret includes the following files:

* `cosign.key`: The private key
* `cosign.password`: The password for decrypting the private key
* `cosign.pub` The public key

If a `signing-secrets` secret already exists, the Operator does not overwrite the secret.

The `cosign.pub` file in your current directory contains the public key that is extracted from the secret.

[WARNING]
====
If you set the `generateSigningSecret` field from `true` to `false`, the {pipelines-title} Operator overrides and empties any value in the `signing-secrets` secret.
====

The {pipelines-title} Operator does not provide the following security functions:

* Key rotation
* Auditing key usage
* Proper access control to the key
54 changes: 0 additions & 54 deletions modules/op-chains-generating-x509-secret.adoc

This file was deleted.

2 changes: 1 addition & 1 deletion modules/op-chains-signing-secrets-cosign.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
:_mod-docs-content-type: PROCEDURE

[id="chains-signing-secrets-cosign_{context}"]
= Signing with the cosign tool
= Manually generating signing secrets with the cosign tool

You can use the `cosign` signing scheme with {tekton-chains} using the `cosign` tool.

Expand Down
4 changes: 2 additions & 2 deletions modules/op-chains-signing-secrets-skopeo.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@
:_mod-docs-content-type: PROCEDURE

[id="chains-signing-secrets-skopeo_{context}"]
= Signing with the skopeo tool
= Manually generating signing secrets with the skopeo tool

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.
* You installed the `skopeo` package on your Linux system.

.Procedure

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ include::modules/op-creating-mounting-kms-authentication-token-secret.adoc[level
include::modules/op-enabling-tekton-chains-to-operate-only-in-selected-namespaces.adoc[leveloffset=+2]

include::modules/op-signing-secrets-in-tekton-chains.adoc[leveloffset=+1]
include::modules/op-chains-generating-x509-secret.adoc[leveloffset=+2]
include::modules/op-chains-generating-cosign-secret.adoc[leveloffset=+2]
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]
Expand Down