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..3486ea9e --- /dev/null +++ b/content/en/docs/How-to-guides/use-trusted-resources.md @@ -0,0 +1,359 @@ + + +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/user-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/user-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 + +1. To verify the signatures, enable policy verification on your cluster. Create + a ConfigMap: + + ```yaml + apiVersion: 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" + ``` + + To customize how the feature behaves, use one of the following values for + `trusted-resources-verification-no-match-policy`: + + + `ignore`: Use it if you want to verify signed resources and skip unsigned + resources. If no matching policies are found, skip the verification and + don't log. This won't fail the TaksRun or PipelineRun. + + `warn`: If no matching policies are found, skipe the verification and log + a warning. Dont' fail the Taskrun or PipelineRun. + + `fail`: Fail the TaskRun or PipelineRun if no matching policies are found. + + +1. 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/user/sample-tekton-task" + - pattern: "https://github.com/user/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/user/sample-tekton-task" + - pattern: "https://github.com/user/sample-tekton-pipeline" + authorities: + - name: kms + key: + kms: + gcpkms://projects/user-test/locations/us/keyRings/trusted-task-demo/cryptoKeys/trusted-task/cryptoKeyVersions/1 + mode: enforce + ``` + + {{% /tab %}} + + {{% /tabs %}} + +## Artifact Verification + +Submit your PipelineRun: + +```bash +kubectl apply -f pipelinerun.yaml +``` + +The verification was completed successfully: + +```none +Status: + Child References: + API Version: tekton.dev/v1beta1 + Kind: TaskRun + Name: example-pipelinerun-example-task + Pipeline Task Name: example-task + Completion Time: 2023-06-16T19:30:17Z + Conditions: + Last Transition Time: 2023-06-16T19:30:17Z + Message: Tasks Completed: 1 (Failed: 0, Cancelled 0), Skipped: 0 + Reason: Succeeded + Status: True + Type: Succeeded + Last Transition Time: 2023-06-16T19:30:07Z + Status: True + Type: TrustedResourcesVerified +``` + +The `Status: True` of the `Type: TrustedResourcesVerified` confirms that the +resources passed the verification. + +If the verification fails, the output is similar to the following: + +```none +Status: + Completion Time: 2023-06-16T21:29:08Z + Conditions: + Last Transition Time: 2023-06-16T21:29:08Z + Message: PipelineRun trusted-resources/example-pipelinerun-kms referred resource example-pipeline failed signature verification: resource verification failed: resource example-pipeline in namespace trusted-resources fails verification + Reason: ResourceVerificationFailed + Status: False + Type: Succeeded + Last Transition Time: 2023-06-16T21:29:08Z + Message: PipelineRun trusted-resources/example-pipelinerun-kms referred resource example-pipeline failed signature verification: resource verification failed: resource example-pipeline in namespace trusted-resources fails verification + Status: Falsenone +Status: + Completion Time: 2023-06-16T21:29:08Z + Conditions: + Last Transition Time: 2023-06-16T21:29:08Z + Message: PipelineRun trusted-resources/example-pipelinerun-kms +referred resource example-pipeline failed signature verification: resource +verification failed: resource example-pipeline in namespace trusted-resources +fails verification + Reason: ResourceVerificationFailed + Status: False + Type: Succeeded + Last Transition Time: 2023-06-16T21:29:08Z + Message: PipelineRun trusted-resources/example-pipelinerun-kms +referred resource example-pipeline failed signature verification: resource +verification failed: resource example-pipeline in namespace trusted-resources +fails verification + Status: False + Type: TrustedResourcesVerified + Type: TrustedResourcesVerified +``` + +## Code samples: + ++ **Sample Task** + + ```yaml + kind: Task + apiVersion: tekton.dev/v1beta1 + metadata: + name: example-task + namespace: trusted-resources + spec: + steps: + - image: ubuntu + name: echo + command: + - echo + args: + - "Hello World" + ``` + ++ **Sample Pipeline** + + ```yaml + apiVersion: tekton.dev/v1beta1 + kind: Pipeline + metadata: + name: example-pipeline + namespace: trusted-resources + spec: + tasks: + - name: example-task + taskRef: + resolver: git + params: + - name: url + value: https://github.com/user/sample-tekton-task + - name: revision + value: main + - name: pathInRepo + value: signed-task.yaml + ``` + ++ **Sample PipelineRun for Cosign-signed resource** + + ```yaml + apiVersion: tekton.dev/v1 + kind: PipelineRun + metadata: + name: example-pipelinerun + namespace: trusted-resources + spec: + pipelineRef: + resolver: git + params: + - name: url + value: https://github.com/Yongxuanzhang/sample-tekton-pipeline + - name: revision + value: main + - name: pathInRepo + value: signed-pipeline-cosign.yaml + ``` + ++ **Sample PipelineRun for KMS-signed resources** + + ```yaml + apiVersion: tekton.dev/v1 + kind: PipelineRun + metadata: + name: example-pipelinerun-kms + namespace: trusted-resources + spec: + pipelineRef: + resolver: git + params: + - name: url + value: https://github.com/Yongxuanzhang/sample-tekton-pipeline + - name: revision + value: main + - name: pathInRepo + value: signed-pipeline-kms.yaml + ``` + + + +[pipelines-inst]: /docs/pipelines/install/ +[tkn-inst]: /docs/cli/ +[kubectl]: https://kubernetes.io/docs/tasks/tools/#kubectl +[cosign]: https://docs.sigstore.dev/cosign/installation/ +