Skip to main content
Version: 0.8

ImageAllowRules [Alpha]

ImageAllowRules (IARs) are an alpha-feature of Acorn, currently hidden behind a feature flag. To enable them in your Acorn installation, use acorn install --features image-allow-rules=true.


Please read this page to completion before enabling IARs, as they can be quite disruptive.

How ImageAllowRules work

The principle behind IARs is to make your cluster more secure. If you enable this feature, you won't be able to deploy any Acorn image anymore without allowing it. To do that, you have to create an ImageAllowRule resource. If the app image is allowed by a single IAR in your project, it's good to run.


Removing an IAR won't stop your running app, but will update the image-allowed status condition on the app.

What makes up an ImageAllowRule

Currently, IARs have two parts:

  1. The images scope (required) denotes which images the rule applies to. It uses the same syntax as the auto-upgrade pattern. Examples below.
  2. The signatures rules (optional) define a set of image signatures and annotations on those signatures to make sure that an image was actually approved by someone or something, e.g. by your QA team. We're using sigstore/cosign for everything related to signatures.


kind: ImageAllowRule
name: example-iar
namespace: acorn # your project name
-** # ** matches everything, * matches a single path item, # matches a number
- signedBy:
anyOf: # one match is good enough
- |
-----END PUBLIC KEY-----
allOf: [] # all signatures required
annotations: # those annotations have to be present on all signatures
match: # simple key-value pairs
qa: approved
expressions: # just like Kubernetes label selectors
- key: tests
operator: In # In, NotIn, Exists, DoesNotExist
- passed
- ok

About Signatures

To sign an image, you can use sigstore/cosign via the CLI. You can download or build an Acorn image, sign it with cosign, annotate the signature (optional), then upload it to an OCI registry. Afterwards, when you try to run that image in a protected cluster where the image is in scope of an IAR, Acorn will first ensure that:

  • it matches the provided public keys
  • matching signatures also have the required annotations

If one or both of these conditions aren't met, Acorn will refuse to run the image.


Here's a full walkthrough to use Acorn with the ImageAllowRules feature in a fresh installation and with cosign signatures. Please note that the exact output may be different for you, especially depending on the version of cosign you use.

# 1. Create a fresh cluster and install Acorn - doesn't have to be k3d, you may also update your existing installation
$ k3d cluster create acorn

$ acorn install --features image-allow-rules=true

# 2. Pull some Acorn image and push it to another registry that you have push access to (Alternatively, build it from an Acornfile)
$ acorn pull
$ acorn tag my.registry.local/acorn/hello-world:latest
$ acorn push my.registry.local/acorn/hello-world:latest

# 2.1 Faster using crane:
$ crane copy my.registry.local/acorn/hello-world:latest

# 3. Get the digest
$ crane digest my.registry.local/acorn/hello-world:latest

# 4. Generate a keypair if you don't have one already
$ cosign generate-key-pair
Enter password for private key:
Enter password for private key again:
WARNING: File cosign.key already exists. Overwrite?
Are you sure you would like to continue? [y/N] y
Private key written to cosign.key
Public key written to

# 5. Sign the image with the newly generated key and an annotation that says `tag=notok`
$ cosign sign --key cosign.key -a tag=notok my.registry.local/acorn/hello-world@sha256:1a6c64d2ccd0bb035f9c8196d3bfe72a7fdbddc4530dfcb3ab2a0ab8afb57eeb
Enter password for private key:

Note that there may be personally identifiable information associated with this signed artifact.
This may include the email address associated with the account with which you authenticate.
This information will be used for signing this artifact and will be stored in public transparency logs and cannot be removed later.

By typing 'y', you attest that you grant (or have permission to grant) and agree to have this information stored permanently in transparency logs.
Are you sure you would like to continue? [y/N] y
tlog entry created with index: 15549911
Pushing signature to: my.registry.local/acorn/hello-world

# 6. Deploy a cluster-level image allow rule that will deny this image
$ cat << EOF | kubectl apply -f -
pipe heredoc> apiVersion:
kind: ImageAllowRule
name: testrule
namespace: acorn
- my.registry.local/**
- signedBy:
- |
!!! Put your Public Key here !!!
-----END PUBLIC KEY-----
tag: ok
EOF configured

# 7. Try to run the image -> it should fail (because the annotation is wrong)

$ acorn run my.registry.local/acorn/hello-world:latest
• WARNING: This application would like to use the image 'my.registry.local/acorn/hello-world:latest'.
This image is not trusted by any image allow rules in this project.
This could be VERY DANGEROUS to the cluster if you do not trust this
application. If you are unsure say no.

? Do you want to allow this app to use this (POTENTIALLY DANGEROUS) image? [Use arrows to move, type to filter]
> NO
yes (this tag only)
repository (all images in this repository)
registry (all images in this registry)
all (all images out there)

# Here, as an admin, you get to choose to have Acorn automatically generate an IAR for you to allow this image (without signatures)
# Repeating Step 5 with `-a tag=notok` and then continuing with steps 6 and 7, should make it work

No need for YAML

As you have seen in the last section, Acorn also prompts admins to allow an image that is not yet allowed to run. That's quite basic and will create an ImageAllowRule with only the images scope populated, no signatures required.