From 76900c5fb21becc5a5ad8412d20d5437851b2c0d Mon Sep 17 00:00:00 2001
From: Roman Martsev <matrixur@gmail.com>
Date: Mon, 3 Jun 2024 12:49:58 +0300
Subject: [PATCH] docs(readme): append information

---
 README.md | 129 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 112 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 7f42db3..1a2f528 100644
--- a/README.md
+++ b/README.md
@@ -2,26 +2,32 @@
 
 ## Features
 
-- sign image with cosign local key and push it to container registry
+- Based on `cosign` local keys.
+- Signs images and pushes them to a container registry.
 
-## Documentation
+## How to Use
 
-- [Cosign](https://docs.sigstore.dev/)
-- [Cosign installer](https://github.com/sigstore/cosign-installer/)
+### Cosign Local Keys
 
-## Cosign keys
+#### Workflow
 
-First, you need to create/generate a password for private key. Then generate keys with:
+1. Generate a password for the private key.
+2. Generate a key pair.
+3. Store the private key and password in GitHub Actions Secrets.
 
-1. [Official binary](https://docs.sigstore.dev/system_config/installation/)
+#### Generate Key Pair
 
-    ```bash
+You can generate keys using:
+
+1. [Official Binary](https://docs.sigstore.dev/system_config/installation/)
+
+    ```sh
     COSIGN_PASSWORD=<your_private_key_password> cosign generate-key-pair
     ```
 
-2. [Docker image by VMware](https://hub.docker.com/r/bitnami/cosign/)
+2. [Docker Image by VMware](https://hub.docker.com/r/bitnami/cosign/)
 
-    ```bash
+    ```sh
     docker run --rm -it \
     -e COSIGN_PASSWORD=<your_private_key_password> \
     -v "$(pwd):/keys" \
@@ -30,19 +36,102 @@ First, you need to create/generate a password for private key. Then generate key
     generate-key-pair
     ```
 
-Store keys in GitHub Action Secrets:
+Default GitHub Action Secrets for keys:
 
-- COSIGN_PASSWORD - a password for private key
-- COSIGN_PUBLIC_KEY - content of the file cosign.pub
-- COSIGN_PRIVATE_KEY - content of the file cosign.key
+- `COSIGN_PASSWORD`: Password for the private key.
+- `COSIGN_PUBLIC_KEY`: Content of the file `cosign.pub`.
+- `COSIGN_PRIVATE_KEY`: Content of the file `cosign.key`.
 
-You can generate and store keys directly in GitHub Actions Secrets with command:
+You can generate and store keys directly in GitHub Actions Secrets with the command:
 
 ```bash
 GITHUB_TOKEN=xxx cosign generate-key-pair github://dodopizza/app
 ```
 
-But remember, you can't export public key with cosign from GitHub Action Secrets. 
+**Note:** You can't export the public key with `cosign` from GitHub Action Secrets.
+
+### GitHub Action
+
+#### Workflow
+
+1. Set up `cosign` (e.g., `sigstore/cosign-installer`).
+2. Log in to the container registry (e.g., `docker/login-action`).
+3. Sign the image using this action.
+
+#### Input Variables
+
+| Variable             | Required | Description                                                                                                               |
+| -------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `image-tags`         | Yes      | List of image tags. Tags are used to denote different versions or variants of an image, e.g., "latest", "v1.0", "stable". |
+| `image-digest`       | Yes      | Image digest. This is a unique identifier for the image, represented as a hash of its contents.                           |
+| `cosign-private-key` | Yes      | Cosign private key used for signing container images.                                                                     |
+| `cosign-password`    | Yes      | Password for the Cosign private key.                                                                                      |
+
+### Configure Kubernetes Cluster
+
+#### Workflow
+
+1. Add the Helm chart, configure values, and deploy the Policy Controller.
+2. Create policies.
+
+#### Helm Chart
+
+1. Add the Sigstore Helm repository:
+
+    ```sh
+    helm repo add sigstore https://sigstore.github.io/helm-charts
+    ```
+
+2. Update your local Helm chart repository cache:
+
+    ```sh
+    helm repo update
+    ```
+
+3. Install the `policy-controller` chart from the Sigstore repository:
+
+    ```sh
+    helm install policy-controller sigstore/policy-controller
+    ```
+
+    Using a `values.yaml` file:
+
+    ```sh
+    helm install policy-controller sigstore/policy-controller -f values.yaml
+    ```
+
+Helm chart documentation: [artifacthub.io/packages/helm/sigstore/policy-controller](https://artifacthub.io/packages/helm/sigstore/policy-controller)
+
+#### Create Policies
+
+Sample policy:
+
+```yaml
+apiVersion: policy.sigstore.dev/v1alpha1
+kind: ClusterImagePolicy
+metadata:
+  name: custom-key-attestation-sbom-spdxjson
+spec:
+  images:
+  - glob: "**"
+  authorities:
+  - name: custom-key
+    key:
+      data: |
+        -----BEGIN PUBLIC KEY-----
+        MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEOc6HkISHzVdUbtUsdjYtPuyPYBeg
+        4FCemyVurIM4KEORQk4OAu8ZNwxvGSoY3eAabYaFIPPQ8ROAjrbdPwNdJw==
+        -----END PUBLIC KEY-----
+    attestations:
+    - name: must-have-spdxjson
+      predicateType: https://spdx.dev/Document
+      policy:
+        type: cue
+        data: |
+          predicateType: "https://spdx.dev/Document"
+```
+
+For more documentation and sample policies, refer to: [docs.sigstore.dev/policy-controller/sample-policies](https://docs.sigstore.dev/policy-controller/sample-policies/)
 
 ## Usage example:
 
@@ -117,4 +206,10 @@ jobs:
         for tag in ${TAGS}; do
           echo "${tag}" >>$GITHUB_STEP_SUMMARY
         done
-```
\ No newline at end of file
+```
+
+## Reference links
+
+- [Cosign Documentation](https://docs.sigstore.dev/)
+- [Cosign Installer GitHub](https://github.com/sigstore/cosign-installer/)
+- [Helm Chart for Policy Controller](https://artifacthub.io/packages/helm/sigstore/policy-controller)