This page contains tips for troubleshooting problems that one may encounter when working with Chainguard Enforce.
How to disable admission control
There may be urgent situations where having admission control enabled is not desirable. For example, it could be preventing the cluster from functioning correctly or may be getting in the way of the operator.
In cases like this, you can completely disable the Chainguard Enforce admission webhook with the following commands.
kubectl delete validatingwebhookconfiguration enforcer kubectl delete mutatingwebhookconfiguration enforcer
After your urgent situation is over, reinstall Enforce in your cluster to restore the webhook to its normal operation.
Chainguard Enforce is unable to parse a given SBOM
One issue that may come up when working with Chainguard Enforce is that it won’t ingest an SBOM as expected. This section outlines several potential causes for this issue and how you can address them.
Check your permissions
Chainguard Enforce needs access to your images in order to parse the associated SBOMs. If your image is in a private repository, check out our guide on setting up cloud account associations to grant Enforce read access to the image.
SBOMs using older versions of CycloneDX
For CycloneDX, Chainguard Enforce currently only supports version 1.4.
SBOM included as an in-toto attestation
We are in the process of updating Chainguard Enforce so it can readily parse SBOM attestations out of the box. In the meantime, you can parse SBOMs through implementing specific policies that cover this use case.
You can create a policy covering your image through the Chainguard Enforce console or using the
chainctl command line tool. Additionally, you can check out our policy catalog for our collection of policies that work directly with Chainguard Enforce.
Policy does not cover a given image as expected
When working with the
ClusterImagePolicy, note that the glob wildcard
* does not cover the
/ character. For example, a glob pattern like
gcr.io/apple/* will cover paths like
gcr.io/apple/zebra, but not
To match everything — including the
/ character — use the
** wildcard instead.
Enforce does not block Pod creation as expected
The first thing to check is whether you labeled your namespace with
policy.sigstore.dev/include=true. You can double check whether the
default namespace is correctly labeled with the following command.
kubectl get ns -l policy.sigstore.dev/include=true
If it is indeed labeled like this, you’ll receive output like the following.
NAME STATUS AGE default Active 24s
If you need to label your namespace, you can do so with the following command. Note that this example labels the
kubectl label ns default policy.sigstore.dev/include=true --overwrite
Be sure to use the exact string, variations like
included won’t work.
Sometimes Chainguard Enforce is installed using the
observer profile. Essentially, this means that Enforce just has read-only permission for workload discovery, and it cannot actually enforce policies. You can run
chainctl cluster ls to find what profile the cluster is using.