From 874da85e66eeb25a9c51ea90faaf1a50b368516b Mon Sep 17 00:00:00 2001 From: cpanato Date: Thu, 18 Jul 2024 17:01:56 +0200 Subject: [PATCH] sync readme for policy-controller Signed-off-by: cpanato --- charts/policy-controller/Chart.yaml | 2 +- charts/policy-controller/README.md | 140 ++++++++++---------- charts/policy-controller/README.md.gotmpl | 148 ++++++++++++++++++++++ 3 files changed, 225 insertions(+), 65 deletions(-) create mode 100644 charts/policy-controller/README.md.gotmpl diff --git a/charts/policy-controller/Chart.yaml b/charts/policy-controller/Chart.yaml index 0ad3c0fd..58a96f79 100644 --- a/charts/policy-controller/Chart.yaml +++ b/charts/policy-controller/Chart.yaml @@ -8,7 +8,7 @@ sources: type: application name: policy-controller -version: 0.6.8 +version: 0.6.9 appVersion: 0.8.2 maintainers: diff --git a/charts/policy-controller/README.md b/charts/policy-controller/README.md index b9e1c651..c64cb857 100644 --- a/charts/policy-controller/README.md +++ b/charts/policy-controller/README.md @@ -1,77 +1,17 @@ # policy-controller -![Version: 0.6.8](https://img.shields.io/badge/Version-0.6.8-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 0.8.2](https://img.shields.io/badge/AppVersion-0.8.2-informational?style=flat-square) + + +![Version: 0.6.9](https://img.shields.io/badge/Version-0.6.9-informational?style=flat-square) ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square) ![AppVersion: 0.8.2](https://img.shields.io/badge/AppVersion-0.8.2-informational?style=flat-square) The Helm chart for Policy Controller **Homepage:** -## Maintainers - -| Name | Email | Url | -| ---- | ------ | --- | -| dlorenc | | | -| hectorj2f | | | - ## Source Code * -## Values - -| Key | Type | Default | Description | -|-----|------|---------|-------------| -| commonAnnotations | object | `{}` | | -| commonNodeSelector | object | `{}` | | -| commonTolerations | list | `[]` | | -| cosign.cosignPub | string | `""` | | -| cosign.webhookName | string | `"policy.sigstore.dev"` | | -| imagePullSecrets | list | `[]` | | -| installCRDs | bool | `true` | | -| leasescleanup.image.pullPolicy | string | `"IfNotPresent"` | | -| leasescleanup.image.repository | string | `"cgr.dev/chainguard/kubectl"` | | -| leasescleanup.image.version | string | `"latest-dev"` | | -| loglevel | string | `"info"` | | -| serviceMonitor.enabled | bool | `false` | | -| webhook.configData | object | `{}` | | -| webhook.customLabels | object | `{}` | | -| webhook.env | object | `{}` | | -| webhook.extraArgs | object | `{}` | | -| webhook.failurePolicy | string | `"Fail"` | | -| webhook.image.pullPolicy | string | `"IfNotPresent"` | | -| webhook.image.repository | string | `"ghcr.io/sigstore/policy-controller/policy-controller"` | | -| webhook.image.version | string | `"sha256:f291fce5b9c1a69ba54990eda7e0fe4114043b1afefb0f4ee3e6f84ec9ef1605"` | `"v0.8.2"` | -| webhook.name | string | `"webhook"` | | -| webhook.namespaceSelector.matchExpressions[0].key | string | `"policy.sigstore.dev/include"` | | -| webhook.namespaceSelector.matchExpressions[0].operator | string | `"In"` | | -| webhook.namespaceSelector.matchExpressions[0].values[0] | string | `"true"` | | -| webhook.podDisruptionBudget.enabled | bool | `true` | | -| webhook.podDisruptionBudget.minAvailable | int | `1` | | -| webhook.podSecurityContext.allowPrivilegeEscalation | bool | `false` | | -| webhook.podSecurityContext.capabilities.drop[0] | string | `"ALL"` | | -| webhook.podSecurityContext.enabled | bool | `true` | | -| webhook.podSecurityContext.readOnlyRootFilesystem | bool | `true` | | -| webhook.podSecurityContext.runAsUser | int | `1000` | | -| webhook.registryCaBundle | object | `{}` | | -| webhook.replicaCount | int | `1` | | -| webhook.resources.limits.cpu | string | `"200m"` | | -| webhook.resources.limits.memory | string | `"512Mi"` | | -| webhook.resources.requests.cpu | string | `"100m"` | | -| webhook.resources.requests.memory | string | `"128Mi"` | | -| webhook.securityContext.enabled | bool | `false` | | -| webhook.securityContext.runAsUser | int | `65532` | | -| webhook.service.annotations | object | `{}` | | -| webhook.service.port | int | `443` | | -| webhook.service.type | string | `"ClusterIP"` | | -| webhook.serviceAccount.annotations | object | `{}` | | -| webhook.serviceAccount.create | bool | `true` | | -| webhook.serviceAccount.name | string | `""` | | -| webhook.volumeMounts | list | `[]` | | -| webhook.volumes | list | `[]` | | -| webhook.webhookNames.defaulting | string | `"defaulting.clusterimagepolicy.sigstore.dev"` | | -| webhook.webhookNames.validating | string | `"validating.clusterimagepolicy.sigstore.dev"` | | - - ### Deploy `policy-controller` Helm Chart Install `policy-controller` using Helm: @@ -182,7 +122,79 @@ Creating a deployment referencing images that are not signed will yield the foll pod/pod1-signed created ``` - ## More info You can find more information about the policy-controller in [here](https://docs.sigstore.dev/policy-controller/overview/). + +## Uninstallation + +To uninstall the Helm chart run following command. + +```shell +helm uninstall [RELEASE_NAME] +``` + +## Maintainers + +| Name | Email | Url | +| ---- | ------ | --- | +| dlorenc | | | +| hectorj2f | | | + +## Source Code + +* + +## Values + +| Key | Type | Default | Description | +|-----|------|---------|-------------| +| commonAnnotations | object | `{}` | | +| commonNodeSelector | object | `{}` | | +| commonTolerations | list | `[]` | | +| cosign.cosignPub | string | `""` | | +| cosign.webhookName | string | `"policy.sigstore.dev"` | | +| imagePullSecrets | list | `[]` | | +| installCRDs | bool | `true` | | +| leasescleanup.image.pullPolicy | string | `"IfNotPresent"` | | +| leasescleanup.image.repository | string | `"cgr.dev/chainguard/kubectl"` | | +| leasescleanup.image.version | string | `"latest-dev"` | | +| loglevel | string | `"info"` | | +| serviceMonitor.enabled | bool | `false` | | +| webhook.configData | object | `{}` | | +| webhook.customLabels | object | `{}` | | +| webhook.env | object | `{}` | | +| webhook.extraArgs | object | `{}` | | +| webhook.failurePolicy | string | `"Fail"` | | +| webhook.image.pullPolicy | string | `"IfNotPresent"` | | +| webhook.image.repository | string | `"ghcr.io/sigstore/policy-controller/policy-controller"` | | +| webhook.image.version | string | `"sha256:f291fce5b9c1a69ba54990eda7e0fe4114043b1afefb0f4ee3e6f84ec9ef1605"` | | +| webhook.name | string | `"webhook"` | | +| webhook.namespaceSelector.matchExpressions[0].key | string | `"policy.sigstore.dev/include"` | | +| webhook.namespaceSelector.matchExpressions[0].operator | string | `"In"` | | +| webhook.namespaceSelector.matchExpressions[0].values[0] | string | `"true"` | | +| webhook.podDisruptionBudget.enabled | bool | `true` | | +| webhook.podDisruptionBudget.minAvailable | int | `1` | | +| webhook.podSecurityContext.allowPrivilegeEscalation | bool | `false` | | +| webhook.podSecurityContext.capabilities.drop[0] | string | `"ALL"` | | +| webhook.podSecurityContext.enabled | bool | `true` | | +| webhook.podSecurityContext.readOnlyRootFilesystem | bool | `true` | | +| webhook.podSecurityContext.runAsUser | int | `1000` | | +| webhook.registryCaBundle | object | `{}` | | +| webhook.replicaCount | int | `1` | | +| webhook.resources.limits.cpu | string | `"200m"` | | +| webhook.resources.limits.memory | string | `"512Mi"` | | +| webhook.resources.requests.cpu | string | `"100m"` | | +| webhook.resources.requests.memory | string | `"128Mi"` | | +| webhook.securityContext.enabled | bool | `false` | | +| webhook.securityContext.runAsUser | int | `65532` | | +| webhook.service.annotations | object | `{}` | | +| webhook.service.port | int | `443` | | +| webhook.service.type | string | `"ClusterIP"` | | +| webhook.serviceAccount.annotations | object | `{}` | | +| webhook.serviceAccount.create | bool | `true` | | +| webhook.serviceAccount.name | string | `""` | | +| webhook.volumeMounts | list | `[]` | | +| webhook.volumes | list | `[]` | | +| webhook.webhookNames.defaulting | string | `"defaulting.clusterimagepolicy.sigstore.dev"` | | +| webhook.webhookNames.validating | string | `"validating.clusterimagepolicy.sigstore.dev"` | | diff --git a/charts/policy-controller/README.md.gotmpl b/charts/policy-controller/README.md.gotmpl new file mode 100644 index 00000000..123449b5 --- /dev/null +++ b/charts/policy-controller/README.md.gotmpl @@ -0,0 +1,148 @@ +{{ template "chart.header" . }} + + + +{{ template "chart.deprecationWarning" . }} + +{{ template "chart.badgesSection" . }} + +{{ template "chart.description" . }} + +{{ template "chart.homepageLine" . }} + +## Source Code + +* + + +### Deploy `policy-controller` Helm Chart + +Install `policy-controller` using Helm: + +```shell +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 --devel +``` + +The `policy-controller` enforce images matching the defined list of `ClusterImagePolicy` for the labeled namespaces. + +Note that, by default, the `policy-controller` offers a configurable behavior defining whether to allow, deny or warn whenever an image does not match a policy in a specific namespace. This behavior can be configured using the `config-policy-controller` ConfigMap created under the release namespace, and by adding an entry with the property `no-match-policy` and its value `warn|allow|deny`. +By default, any image that does not match a policy is rejected whenever `no-match-policy` is not configured in the ConfigMap. + +As supported in previous versions, you could create your own key pair: + +```shell +export COSIGN_PASSWORD= +cosign generate-key-pair +``` + +This command generates two key files `cosign.key` and `cosign.pub`. Next, create a secret to validate the signatures: + +```shell +kubectl create secret generic mysecret -n \ +cosign-system --from-file=cosign.pub=./cosign.pub +``` + +**IMPORTANT:** The `cosign.secretKeyRef` flag is not supported anymore. Finally, you could reuse your secret `mysecret` by creating a `ClusterImagePolicy` that sets it as listed authorities, as shown below. + +```yaml +apiVersion: policy.sigstore.dev/v1alpha1 +kind: ClusterImagePolicy +metadata: + name: cip-key-secret +spec: + images: + - glob: "**your-desired-value**" + authorities: + - key: + secretRef: + name: mysecret +``` +#### Configuring Custom Certificate Authorities (CA) + +The `policy-controller` can be configured to use custom CAs to communicate to container registries, for example, when you have a private registry with a self-signed TLS certificate. + +To configure `policy-controller` to use custom CAs, follow these steps: + +1. Make sure the `policy-controller` namespace exists: + + ```shell + kubectl create namespace cosign-system + ``` + +2. Create a bundle file with all the root and intermediate certificates and name it `ca-bundle.crt`. + +3. Create a `ConfigMap` from the bundle: + ```shell + kubectl -n cosign-system create cm ca-bundle-config \ + --from-file=ca-bundle.crt="ca-bundle.crt" + ``` + +4. Install the `policy-controller`: + + ```shell + helm install -n cosign-system \ + --set webhook.registryCaBundle.name=ca-bundle-config \ + --set webhook.registryCaBundle.key=ca-bundle.crt \ + policy-controller sigstore/policy-controller + ``` + +### Enabling Admission control + +To enable the `policy admission webhook` to check for signed images, you will need to add the following label in each namespace that you would want the webhook triggered: + +Label: `policy.sigstore.dev/include: "true"` + +```yaml +apiVersion: v1 +kind: Namespace +metadata: + labels: + policy.sigstore.dev/include: "true" + kubernetes.io/metadata.name: my-namespace + name: my-namespace +spec: + finalizers: + - kubernetes +``` + +### Testing the webhook + +1. Using Unsigned Images: +Creating a deployment referencing images that are not signed will yield the following error and no resources will be created: + + ```shell + kubectl apply -f my-deployment.yaml + Error from server (BadRequest): error when creating "my-deployment.yaml": admission webhook "policy.sigstore.dev" denied the request: validation failed: invalid image signature: spec.template.spec.containers[0].image + ``` + +2. Using Signed Images: Assuming a signed `nginx` image with a tag `signed` exists on a registry, the resource will be successfully created. + + ```shell + kubectl run pod1-signed --image=< REGISTRY_USER >/nginx:signed -n testns + pod/pod1-signed created + ``` + + +## More info + +You can find more information about the policy-controller in [here](https://docs.sigstore.dev/policy-controller/overview/). + + +## Uninstallation + +To uninstall the Helm chart run following command. + +```shell +helm uninstall [RELEASE_NAME] +``` + +{{ template "chart.maintainersSection" . }} + +{{ template "chart.sourcesSection" . }} + +{{ template "chart.requirementsSection" . }} + +{{ template "chart.valuesSection" . }}