Product Docs
Open Source
Education
The Sigstore Policy Controller is a Kubernetes admission controller that can verify image signatures and policies. You can define policies using the CUE or Rego policy languages.
This guide will demonstrate how to install the Policy Controller in your Kubernetes cluster and enable policy enforcement.
To follow along with this guide outside of the terminal that is embedded on this page, you will need the following:
kubectl
If you are using the terminal that is embedded on this page, then all the prerequsites are installed for you.
Once you have everything in place you can continue to the next step and install the Policy Controller.
cosign-system
The first step that you need to complete is to create a Kubernetes namespace for the Policy Controller to run in. Call it cosign-system and run the following command to create it:
namespace
kubectl create namespace cosign-system
Now you can move on to the next step, which is installing the Policy Controller into the namespace you just created.
In this step we’ll use the helm command line tool to install the Policy Controller.
helm
First, add the Sigstore Helm Repository to your system with the following command:
helm repo add sigstore https://sigstore.github.io/helm-charts
You should receive output like this:
"sigstore" has been added to your repositories
Next, update your local Helm repository information using the helm repo update comand:
helm repo update
You’ll receive output like the following:
Hang tight while we grab the latest from your chart repositories... ...Successfully got an update from the "sigstore" chart repository Update Complete. ⎈Happy Helming!⎈
Now install the Policy Controller into the cosign-system namespace that you created in the first step of this guide:
helm install policy-controller -n cosign-system sigstore/policy-controller --devel
The --devel flag will include any alpha, beta, or release candidate versions of a chart. You can specify a particular version with the --version flag if you prefer.
--devel
--version
It may take a few minutes for your cluster to deploy all of the manifests needed for the Policy Controller. Check the status of your cluster using the kubectl wait command like this:
kubectl wait
kubectl -n cosign-system wait --for=condition=Available deployment/policy-controller-webhook && \ kubectl -n cosign-system wait --for=condition=Available deployment/policy-controller-policy-webhook
Once the Policy Controller deployments are done you will receive output like the following:
deployment.apps/policy-controller-webhook condition met deployment.apps/policy-controller-policy-webhook condition met
A full list of the resources that the Policy Controller deploys into your cluster is available at the end of this guide in Appendix — Resource Types.
You have now deployed the Policy Controller into your cluster. The next step is to enable it for the namespaces that you want to enforce policies in.
Now that you have the Policy Controller installed into your cluster, the next step is to decide which namespaces should use it. By default, namespaces must enroll into enforcement, so you will need to label any namespace that you will use with the Policy Controller.
Run the following command to include the default namespace in image validation and policy enforcement:
default
kubectl label namespace default policy.sigstore.dev/include=true
Apply the same label to any other namespace that you want to use with the Policy Controller.
Now you can test enforcement by running a sample pod:
kubectl run --image cgr.dev/chainguard/nginx:latest nginx
The Policy Controller will deny the admission request with a message like the following:
Error from server (BadRequest): admission webhook "policy.sigstore.dev" denied the request: validation failed: no matching policies: spec.containers[0].image cgr.dev/chainguard/nginx@sha256:628a01724b84d7db2dc3866f645708c25fab8cce30b98d3e5b76696291d65c4a
The image is not admitted into the cluster because there are no ClusterImagePolicy (CIP) definitions that match it. In the next step you will define a policy that allows specific images and apply it to your cluster.
ClusterImagePolicy
Now that you have the Policy Controller running in your cluster, and have the default namespace configured to use it, you can now define a ClusterImagePolicy to admit images.
The following policy will allow any Chainguard Image hosted on the cgr.dev/chainguard registry to run on a cluster, while denying any other images.
cgr.dev/chainguard
Open a new file with nano or your preferred editor:
nano
nano /tmp/cip.yaml
Copy the following policy to the /tmp/cip.yaml file:
/tmp/cip.yaml
apiVersion: policy.sigstore.dev/v1beta1 kind: ClusterImagePolicy metadata: name: chainguard-image-policy spec: images: - glob: "cgr.dev/chainguard/**" authorities: - static: action: pass
The glob: "cgr.dev/chainguard/**" line in combination with the action: pass portion of the authorities section will allow any image in the cgr.dev/chainguard image registry to be admitted into your cluster.
glob: "cgr.dev/chainguard/**"
action: pass
authorities
Save the file and then apply the policy:
kubectl apply -f /tmp/cip.yaml
You will receive output showing the policy is created:
clusterimagepolicy.policy.sigstore.dev/chainguard-image-policy created
Now run the cgr.dev/chainguard/nginx:latest image again:
cgr.dev/chainguard/nginx:latest
Since the image matches the policy, you will receive a message that the pod was created successfully:
pod/nginx created
Delete the pod once you’re done experimenting with it:
kubectl delete pod nginx
To learn more about how the Policy Controller admits images, review the Admission of images page Sigstore documentation.
While it is useful to use the Policy Controller to manage admission into a cluster, once a workload is running any vulnerability or policy violations that occur after containers are running will not be detected.
Chainguard Enforce is designed to address this issue by continuously verifying whether a container or cluster contains any vulnerabilities or policy violations over time. This includes what packages are deployed, SBOMs (software bills of materials), provenance, signature data, and more.
If you’re interested in learning more about Chainguard Enforce, you can request access to the product by selecting Chainguard Enforce on the inquiry form.
A complete Policy Controller installation consists of the following resources in a cluster:
policy-controller-policy-webhook
policy-controller-webhook
config-image-policies
config-policy-controller
policy-controller-policy-webhook-logging
policy-controller-webhook-logging
clusterimagepolicies.policy.sigstore.dev
defaulting.clusterimagepolicy.sigstore.dev
policy.sigstore.dev
policy-webhook-certs
webhook-certs
policy-webhook
policy-controller-policy-webhook-metrics
policy-controller-webhook-metrics
webhook
validating.clusterimagepolicy.sigstore.dev