Trusted Resources e2e tutorial

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

@@ -0,0 +1,359 @@
+<!--
+---
+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/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/
+