From 3ab6c496645df542faf5d2c70827dbc259b4ba97 Mon Sep 17 00:00:00 2001 From: Phill MV Date: Tue, 25 Jun 2024 10:55:51 -0400 Subject: [PATCH 1/5] First pass at tweaking README --- README.md | 55 ++++++++++++++++++++++++++----------------------------- 1 file changed, 26 insertions(+), 29 deletions(-) diff --git a/README.md b/README.md index f0bbc08..992c586 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,51 @@ # 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 used to deploy [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: +- A Helm chart for our [temporary fork](https://github.com/github/policy-controller) of the [Sigstore Policy Controller](https://github.com/github/artifact-attestations-helm-charts/tree/main/charts/policy-controller) +- A Helm chart for deploying [GitHub's TrustRoot and a default ClusterImagePolicy](https://github.com/github/artifact-attestations-helm-charts/tree/main/charts/trust-policies) -The Helm charts included in this repository are configured to enforce that -images installed on a cluster have provenance attestations generated with the +These charts 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). -The charts are published to GitHub Container Registry (GHCR) as OCI images. Each release is attested by +These 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 with 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 +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 the [blog post](https://github.blog/2024-05-02-introducing-artifact-attestations-now-in-public-beta/) introducing Artifact Attestations. -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. +## Installation +### Install the Sigstore Policy Controller -## Installing the Charts - -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. + +### Install GitHub's `TrustRoot` and a `ClusterImagePolicy` Next, install the default GitHub policy to be used with policy controller: ```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 From a50f0ad3880a562892156ab8f4ed01a349807bb3 Mon Sep 17 00:00:00 2001 From: Phill MV Date: Tue, 25 Jun 2024 15:52:44 -0400 Subject: [PATCH 2/5] Fixed links, tweaked copy, improved installation instructions --- README.md | 46 ++++++++++++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 992c586..cc6b531 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,24 @@ # Artifact Attestations Helm Charts -This repository hosts GitHub's Helm charts used to deploy [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). +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 admission controller consists of: -- A Helm chart for our [temporary fork](https://github.com/github/policy-controller) of the [Sigstore Policy Controller](https://github.com/github/artifact-attestations-helm-charts/tree/main/charts/policy-controller) -- A Helm chart for deploying [GitHub's TrustRoot and a default ClusterImagePolicy](https://github.com/github/artifact-attestations-helm-charts/tree/main/charts/trust-policies) - -These charts 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). +- 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). These 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 releases with the [`gh` CLI](https://cli.github.com/manual/gh_attestation_verify): +You can verify these releases using the [`gh` CLI](https://cli.github.com/manual/gh_attestation_verify): ```bash gh attestation verify --owner github \ oci://ghcr.io/github/artifact-attestations-helm-charts/policy-controller:v0.9.0-github3 ``` -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 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. ## Installation -### Install the Sigstore Policy Controller +### 1. Install the Sigstore Policy Controller You will need to install two charts. First, install the Sigstore policy controller: @@ -35,9 +32,9 @@ helm install policy-controller --atomic \ The `--atomic` flag will delete the installation if failure occurs. The `--create-namespace` will create the release namespace if not present. -### Install GitHub's `TrustRoot` and a `ClusterImagePolicy` +### 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 --atomic \ @@ -48,17 +45,26 @@ helm install trust-policies --atomic \ --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 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 -See [here](charts/policies/values.yaml) for a complete set of modifiable -policy chart values. +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 ``` From bad23ed5f9524bdd3208b864098d7495a6aa7489 Mon Sep 17 00:00:00 2001 From: Phill MV Date: Tue, 25 Jun 2024 15:54:22 -0400 Subject: [PATCH 3/5] Linked to the workflow performing the attestaiton --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cc6b531..e8429f2 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,8 @@ 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). -These 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). +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). You can verify these releases using the [`gh` CLI](https://cli.github.com/manual/gh_attestation_verify): ```bash From adff96206c6dccfd242cbc0cf5b6d56d2765ae20 Mon Sep 17 00:00:00 2001 From: Phill MV Date: Tue, 25 Jun 2024 15:57:48 -0400 Subject: [PATCH 4/5] Update trust-policies README.md --- charts/trust-policies/README.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/charts/trust-policies/README.md b/charts/trust-policies/README.md index 49427ef..5f0e3ea 100644 --- a/charts/trust-policies/README.md +++ b/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 , 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:** - -## Source Code - -* +See the [values.yaml](./values.yaml) file for more information on which fields can be customied. From c524b9cb1c5f3e7cff0ef72f30143ce05a19fda9 Mon Sep 17 00:00:00 2001 From: Phill MV Date: Tue, 25 Jun 2024 15:58:18 -0400 Subject: [PATCH 5/5] Update README.md --- charts/trust-policies/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/charts/trust-policies/README.md b/charts/trust-policies/README.md index 5f0e3ea..e25199b 100644 --- a/charts/trust-policies/README.md +++ b/charts/trust-policies/README.md @@ -2,4 +2,4 @@ This helm chart installs GitHub's `TrustRoot` and a default `ClusterImagePolicy` meant to be used with the , 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. -See the [values.yaml](./values.yaml) file for more information on which fields can be customied. +See the [values.yaml](./values.yaml) file for more information on which fields can be customized.