Merge pull request #43 from github/tweak-readme

Copy edits to README

README.md

@@ -1,67 +1,70 @@
 # Artifact Attestations Helm Charts
 
-This repository hosts GitHub's [Policy Controller](https://github.com/github/policy-controller) Helm charts.
+This repository hosts GitHub's Helm charts for deploying [a Kubernetes admission controller for Artifact Attestations](https://docs.github.com/en/actions/security-guides/enforcing-artifact-attestations-with-a-kubernetes-admission-controller). This admission controller allows you to enforce the provenance of artifacts deployed to your cluster by verifying their [Artifact Attestations](https://docs.github.com/en/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds#verifying-artifact-attestations-with-the-github-cli).
 
-The policy controller is an admission controller built to enforce policies
-on a Kubernetes cluster.
+The admission controller consists of:
+- The [`policy-controller` chart](https://github.com/github/artifact-attestations-helm-charts/tree/main/charts/policy-controller), which is used to deploy [our temporary fork](https://github.com/github/policy-controller) of the [Sigstore Policy Controller](https://github.com/sigstore/policy-controller)
+- The [`trust-policies` chart](https://github.com/github/artifact-attestations-helm-charts/tree/main/charts/trust-policies), which is used to deploy GitHub's `TrustRoot` and a default `ClusterImagePolicy`. This policy ensures that images installed on a cluster must have provenance attestations generated with the [Attest Build Provenance GitHub Action](https://github.com/actions/attest-build-provenance).
 
-The Helm charts included in this repository are configured to enforce that
-images installed on a cluster have provenance attestations generated with the
-[Attest Build Provenance GitHub Action](https://github.com/actions/attest-build-provenance).
+These charts are published to GitHub Container Registry (GHCR) as OCI images. Every release is attested with
+the [Attest Build Provenance Action](https://github.com/github/artifact-attestations-helm-charts/blob/a50f0ad3880a562892156ab8f4ed01a349807bb3/.github/workflows/release.yml#L50).
 
-The charts are published to GitHub Container Registry (GHCR) as OCI images. Each release is attested by
-the [Attest Build Provenance Action](https://github.com/actions/attest-build-provenance).
-
-You can verify these release with the `gh` CLI:
+You can verify these releases using the [`gh` CLI](https://cli.github.com/manual/gh_attestation_verify):
 ```bash
-gh attestation verify \
-    oci://ghcr.io/github/artifact-attestations-helm-charts/policy-controller:v0.9.0-github3 \
-    --owner github
+gh attestation verify --owner github \
+    oci://ghcr.io/github/artifact-attestations-helm-charts/policy-controller:v0.9.0-github3
 ```
 
-## Background
-
-See the [official documentation](https://docs.github.com/en/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds) on
-using artifact attestations to establish build provenance and
-the [blog post](https://github.blog/2024-05-02-introducing-artifact-attestations-now-in-public-beta/) introducing Artifact Attestations.
+For more information, see [our documentation](https://docs.github.com/en/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds) on using artifact attestations to establish build provenance and [our blog post](https://github.blog/2024-05-02-introducing-artifact-attestations-now-in-public-beta/) introducing Artifact Attestations.
 
-## Installing the Charts
+## Installation
+### 1. Install the Sigstore Policy Controller
 
-You will need to install two charts. First, install the policy controller:
+You will need to install two charts. First, install the Sigstore policy controller:
 
 ```bash
-helm install policy-controller \
-    oci://ghcr.io/github/artifact-attestations-helm-charts/policy-controller \
-    --create-namespace --namespace artifact-attestations \
-    --atomic --version v0.9.0-github3
+helm install policy-controller --atomic \
+  --create-namespace --namespace artifact-attestations \
+  oci://ghcr.io/github/artifact-attestations-helm-charts/policy-controller \
+  --version v0.9.0-github3
 ```
 
-The `--create-namespace` will create the release namespace if not present.
 The `--atomic` flag will delete the installation if failure occurs.
+The `--create-namespace` will create the release namespace if not present.
+
+### 2. Install GitHub's `TrustRoot` and a `ClusterImagePolicy`
 
-Next, install the default GitHub policy to be used with policy controller:
+Next, install the GitHub `TrustRoot` and our default `ClusterImagePolicy`:
 
 ```bash
-helm install trust-policies \
-    oci://ghcr.io/github/artifact-attestations-helm-charts/trust-policies \
-    --namespace artifact-attestations \
-    --atomic \
-    --set policy.enabled=true \
-    --set policy.organization=MYORG \
-    --version v0.4.0
+helm install trust-policies --atomic \
+ --namespace artifact-attestations \
+ oci://ghcr.io/github/artifact-attestations-helm-charts/trust-policies \
+ --version v0.4.0 \
+ --set policy.enabled=true \
+ --set policy.organization=MY-ORGANIZATION
 ```
 
-By setting `policy.organization` to a specific organization, the policy
-controller will verify the workflow that signed an image's attestation is hosted
-in a repository within the specified organization.
+By setting `policy.organization` to a specific organization, the Sigstore policy
+controller will verify that the workflow that signed an image's attestation is hosted
+in a repository owned by the specified organization `MY-ORGANIZATION`
 
-See [here](charts/policies/values.yaml) for a complete set of modifiable
-policy chart values.
+See the [`trust-policies` values.yaml file](charts/trust-policies/values.yaml) for the complete set of
+`ClusterImagePolicy` values that can be customized.
+
+### 3. Enable the policy in your namespace
+
+Now that the `ClusterImagePolicy` has been installed, we must enable it. The policy will not be enforced until you specify which namespaces it should apply to.
+
+Each namespace in your cluster can independently enforce policies. To enable enforcement in a namespace, you can add the following annotation to the namespace:
+
+```yaml
+metadata:
+  annotations:
+    policy.sigstore.dev/include: true
+```
+Alternatively, you may run:
 
-Once the charts are installed, policy controller should be running on your cluster.
-A namespace must be labeled with `policy.sigstore.dev/include=true` before
-policy controller can enforce the trust policy for any images we try to install
-on it. Label a namespace with the following:
 ```bash
 kubectl label namespace MYNAMESPACE policy.sigstore.dev/include=true
 ```

charts/trust-policies/README.md

@@ -1,9 +1,5 @@
-# policies
+# Trust policies
 
-The Helm chart for Policy Controller Policies
+This helm chart installs GitHub's `TrustRoot` and a default `ClusterImagePolicy` meant to be used with the <https://github.com/github/policy-controller>, and which can be used to enforce that images installed in your Kubernetes cluster originated within a given repository, organization, or were generated by a given reusable workflow.
 
-**Homepage:** <https://github.com/github/policy-controller>
-
-## Source Code
-
-* <https://github.com/github/policy-controller>
+See the [values.yaml](./values.yaml) file for more information on which fields can be customized.