Trusted Resources e2e tutorial

content/en/docs/How-to-guides/use-trusted-resources.md

@@ -0,0 +1,213 @@
+<!--
+---
+title: "Use Trusted Resources with Tekton"
+linkTitle: "Use Trusted Resources"
+weight: 3
+description: >
+  How to sign and verify Tekton resources
+---
+-->
+
+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/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 %}}
+
+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/
+