From 277c36cd961ce608db7b24a3c234660ab4dd7646 Mon Sep 17 00:00:00 2001 From: Geri Ochoa Date: Thu, 13 Jul 2023 11:39:08 -0400 Subject: [PATCH] Trusted Resources e2e tutorial --- .../How-to-guides/use-trusted-resources.md | 213 ++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 content/en/docs/How-to-guides/use-trusted-resources.md diff --git a/content/en/docs/How-to-guides/use-trusted-resources.md b/content/en/docs/How-to-guides/use-trusted-resources.md new file mode 100644 index 00000000..12e837cc --- /dev/null +++ b/content/en/docs/How-to-guides/use-trusted-resources.md @@ -0,0 +1,213 @@ + + +This guide shows you how to: + +1. Sign Tekton Tasks and Pipelines with cosign. +1. Verify signed Tekton Tasks and Pipelines with cosign. +1. Sign Tekton Tasks and Pipelines with KMS keys. +1. Verify signed Tekton Tasks and Pipelines with KMS keys. + +## Prerequisites + +1. To follow this How-to you must have a Kubernetes cluster up and running and + [kubectl][kubectl] properly configured to issue commands to your cluster. + + +1. Install the latest release of Tekton Pipelines: + + ```bash + kubectl apply --filename \ + https://storage.googleapis.com/tekton-releases/pipeline/latest/release.yaml + ``` + + See the [Pipelines installation documentation][pipelines-inst] for other + installation options. + +1. Install the [Tekton CLI, `tkn`][tkn-inst], on your machine. + +1. Install [cosign][cosign]. + +## Signing Tasks and Pipelines + +You can use two different tools to sign Tasks and Pipelines, Cosign or a Key +Management System (KMS): + +{{% tabs %}} + +{{% tab "Cosign" %}} + +1. Generate a key pair to sign the artifact provenance: + + ```bash + cosign generate-key-pair k8s://tekton-chains/signing-secrets + ``` + + You are prompted to enter a password for the private key. For this guide, + leave the password empty and press *Enter* twice. A public key, `cosign.pub`, + is created in your current directory. + +1. Sing the resource YAML file with the private key using the Tekton CLI. + + + To sign a Task file named `task.yaml` run the following command: + + ```bash + tkn task sign task.yaml -K="cosign.key" -f="signed-task-cosign.yaml" + ``` + + The output is the signed Task `signed-task-cosign.yaml`. + + + To sign a Pipeline file name `pipeline.yaml` run the following command: + + ```bash + tkn pipeline sign pipeline.yaml -K="cosign.key" \ + -f="signed-pipeline-cosign.yaml" + ``` + + The output is the signed Pipeline `signed-pipeline-cosign.yaml`. + +1. You can now push the signed resources to a remote storage and use [remote + resolution][remote-reso] to use them. + +[remote-reso]: https://github.com/tektoncd/pipeline/blob/main/docs/resolution.md +{{% /tab %}} + +{{% tab "KMS" %}} + +This section uses Google Cloud's KMS. + +1. Set up a KMS asymmetric signing key. + +1. Log in to your GCP account: + + ```bash + gcloud auth application-default login + ``` + +1. Sing the resource YAML file with the KMS private key using the Tekton CLI. + + To sign a Task file named `task.yaml` run the following command: + + ```bash + tkn task sign task.yaml \ + -m="gcpkms://projects/yongxuan-test/locations/us/keyRings/trusted-task-demo/cryptoKeys/trusted-task/cryptoKeyVersions/1" \ + -f="signed-task-kms.yaml" + ``` + + To sign a Pipeline file name `pipeline.yaml` run the following command: + + ```bash + tkn pipeline sign pipeline.yaml \ + -m="gcpkms://projects/yongxuan-test/locations/us/keyRings/trusted-task-demo/cryptoKeys/trusted-task/cryptoKeyVersions/1" \ + -f="signed-pipeline-kms.yaml" + ``` + +1. You can now push the signed resources to a remote storage and use [remote + resolution][remote-reso] to use them. + +[remote-reso]: https://github.com/tektoncd/pipeline/blob/main/docs/resolution.md +{{% /tab %}} + +{{% /tabs %}} + +## Configure your cluster + +To verify the signatures you must enable policy verification on your cluster. +Write and apply a VerificationPolicy. + +{{% tabs %}} + +{{% tab "Cosign" %}} + +Verification policy for cosign + +```yaml +apiVersion: tekton.dev/v1alpha1 +kind: VerificationPolicy +metadata: + name: cosign-policy + namespace: trusted-resources +spec: + resources: + - pattern: "https://github.com/Yongxuanzhang/sample-tekton-task" + - pattern: "https://github.com/Yongxuanzhang/sample-tekton-pipeline" + authorities: + - name: cosign + key: + secretRef: + name: verification-secrets + namespace: tekton-pipelines + mode: enforce +``` + +{{% /tab %}} + +{{% tab "KMS" %}} + +Verification policy for KMS + +```yaml +apiVersion: tekton.dev/v1alpha1 +kind: VerificationPolicy +metadata: + name: kms-policy + namespace: trusted-resources +spec: + resources: + - pattern: "https://github.com/Yongxuanzhang/sample-tekton-task" + - pattern: "https://github.com/Yongxuanzhang/sample-tekton-pipeline" + authorities: + - name: kms + key: + kms: +gcpkms://projects/yongxuan-test/locations/us/keyRings/trusted-task-demo/cryptoKeys/trusted-task/cryptoKeyVersions/1 + mode: enforce +``` + +{{% /tab %}} + +{{% /tabs %}} + +Enable trusted resource verification on your cluster. Create the following +config map: + +```yaml +piVersion: v1 +kind: ConfigMap +metadata: + name: feature-flags + namespace: tekton-pipelines + labels: + app.kubernetes.io/instance: default + app.kubernetes.io/part-of: tekton-pipelines +data: + trusted-resources-verification-no-match-policy: "fail" +``` + +And apply it to your cluster. + + +## Code samples: + ++ **Sample Task** + ++ **Sample Pipeline** + ++ **Sample PipelineRun for Cosign-signed resource** + ++ **Sample PipelineRun for KMS-signed resources** + + + +[pipelines-inst]: /docs/pipelines/install/ +[tkn-inst]: /docs/cli/ +[kubectl]: https://kubernetes.io/docs/tasks/tools/#kubectl +[cosign]: https://docs.sigstore.dev/cosign/installation/ +