diff --git a/content/en/policy-controller/installation.md b/content/en/policy-controller/installation.md index 0000a36e..939223bf 100644 --- a/content/en/policy-controller/installation.md +++ b/content/en/policy-controller/installation.md @@ -6,28 +6,116 @@ title: Installation weight: 905 --- -The -[`policy-controller`](https://github.com/sigstore/policy-controller) project contains -an admission controller for Kubernetes, which can be installed on -your Kubernetes cluster in a form of a -[`helm chart`](https://github.com/sigstore/helm-charts/tree/main/charts/policy-controller). - -If you run a private instance of Sigstore components, you can specify your own -`TUF` root by mounting your TUF root.json file into the container (for example -by mounting a Secret) and then pointing to it with --tuf-root argument as well -as using --tuf-mirror argument to point to where the TUF mirror is. There's -an optional Secret `tuf-root` that you can create with key `root` that you can -put the `root.json` file in that gets mounted as `/var/run/tuf/root.json`. - -The webhook can be used to automatically validate that all the container images have been signed. -The webhook also resolves the image tags to ensure the image being ran is not different from when it was admitted. - -The `policy-controller` admission controller will only validate resources in -namespaces that have chosen to opt-in. See the -[Enable policy-controller Admission Controller for Namespaces](/policy-controller/overview/#enable-policy-controller-admission-controller-for-namespaces) instructions for more details. - -The `policy-controller` resyncs `ClusterImagePolicies` by default every 10 hours. -Customize the resync period by using the `--policy-resync-period` argument and -defining a duration for the `policy-webhook` deployment. See the [Golang time package's ParseDuration](https://pkg.go.dev/time#example-ParseDuration) for example duration string formats. - -See the [Configuring policy-controller ClusterImagePolicy](/policy-controller/overview/#configuring-policy-controller-clusterimagepolicy) instructions for more details on configuration. +The [`policy-controller`](https://github.com/sigstore/policy-controller) is a Kubernetes admission controller that enforces image signing policies at deploy time. Install it on your cluster via a [Helm chart](https://github.com/sigstore/helm-charts/tree/main/charts/policy-controller). + +## Prerequisites + +- Kubernetes cluster — policy-controller `> 0.10.x` supports Kubernetes 1.27, 1.28, and 1.29; starting with v0.12.0, supported versions are Kubernetes 1.29, 1.30, 1.31, and 1.32. See the [policy-controller support matrix](https://github.com/sigstore/policy-controller#support-policy). +- [Helm](https://helm.sh/docs/intro/install/) 3.x +- `kubectl` configured to access your cluster + +## Install with Helm + +Add the Sigstore Helm repository and install the chart into the `cosign-system` namespace: + +```bash +helm repo add sigstore https://sigstore.github.io/helm-charts +helm repo update +kubectl create namespace cosign-system +helm install policy-controller -n cosign-system sigstore/policy-controller +``` + +The chart installs the `ClusterImagePolicy` and `TrustRoot` Custom Resource Definitions (CRDs) automatically. + +## Enable Policy Enforcement for Namespaces + +The admission controller validates resources only in namespaces that have opted in. Label the namespaces you want protected: + +```bash +kubectl label namespace my-namespace policy.sigstore.dev/include=true +``` + +See [Enable policy-controller Admission Controller for Namespaces](/policy-controller/overview/#enable-policy-controller-admission-controller-for-namespaces). + +## Configure Image Validation Behavior + +### Unmatched images + +Images that do not match any `ClusterImagePolicy` are **denied** by default. Edit the `config-policy-controller` ConfigMap to change this: + +```bash +kubectl patch configmap config-policy-controller -n cosign-system \ + --type merge \ + -p '{"data":{"no-match-policy":"warn"}}' +``` + +Valid values: `deny` (default), `warn`, `allow`. + +### Policy resync period + +The controller resyncs `ClusterImagePolicy` resources every 10 hours by default. Adjust this with `--policy-resync-period` on the `policy-webhook` deployment: + +```bash +helm upgrade policy-controller -n cosign-system sigstore/policy-controller \ + --set webhook.extraArgs.policy-resync-period=2h +``` + +See [time.ParseDuration](https://pkg.go.dev/time#example-ParseDuration) for valid duration string formats. The `TrustRoot` resync period defaults to 24 hours and is controlled by `--trustroot-resync-period`. + +## Using a Private Sigstore Instance + +If you run a private instance of Sigstore components, mount your [TUF (The Update Framework)](https://theupdateframework.io/) `root.json` into the webhook container and point to it at startup. + +Create a Secret with your root: + +```bash +kubectl create secret generic tuf-root -n cosign-system \ + --from-file=root=./root.json +``` + +Mount the Secret into the webhook container via your Helm values file: + +```yaml +webhook: + volumes: + - name: tuf-root + secret: + secretName: tuf-root + volumeMounts: + - name: tuf-root + mountPath: /var/run/tuf + readOnly: true +``` + +Then point the webhook at the mounted root: + +```bash +helm upgrade policy-controller -n cosign-system sigstore/policy-controller \ + -f your-values.yaml \ + --set webhook.extraArgs.tuf-root=/var/run/tuf/root \ + --set webhook.extraArgs.tuf-mirror=https://tuf.example.com +``` + +To disable TUF entirely (for air-gapped environments or when using only `sigstoreKeys`-based `TrustRoot` resources): + +```bash +helm upgrade policy-controller -n cosign-system sigstore/policy-controller \ + --set webhook.extraArgs.disable-tuf=true +``` + +## Test a Policy Without a Cluster + +The `policy-tester` tool validates a `ClusterImagePolicy` against an image locally without a running cluster. Clone the repository and build it: + +```bash +git clone https://github.com/sigstore/policy-controller +cd policy-controller +make policy-tester +./policy-tester --policy=my-policy.yaml --image=ghcr.io/example/app:v1.0.0 +``` + +## Next Steps + +- [Configuring policy-controller ClusterImagePolicy](/policy-controller/overview/#configuring-policy-controller-clusterimagepolicy) +- [Overview](/policy-controller/overview/) +