Skip to content

Pruning The Image Cache

The compiled server binary can be used as a CLI to prune the cache on the file system.

The server can also be configured to prune as a continual background process. For information on that, see Prune Configuration in the Configuring the Server page. There is also a REST API for ad-hoc pruning the running server's cache. See the Administrative REST API document for information on that.

This page is about ad-hoc manual pruning using the server binary as a CLI.

Important

The server must be stopped while pruning using the binary as a CLI because the CLI only manipulates the file system, not the in-memory representation of the cache. Pruning removes manifest lists, manifests, and possibly blobs (more on blobs below.)

Note

As of version 2.0.0 the file system manifest storage scheme changed. The prune sub-command will detect whether the cache has been migrated from the pre-2.0.0 structure and if it has not, the prune sub-command will error with this message: "You must manually migrate the cache using the migrate-cache command, or run the serve command which automatically migrates the cache." The same applies to list and load.

List Images

Generally, it is expected that you will use the server binary as a CLI to list the images before deciding which images to prune. E.g.:

bin/ociregistry --image-path /my/image/cache list --pattern dashboard

Result (for example) truncated in the doc for readability:

docker.io/kubernetesui/dashboard-web@sha256:05ad8120...
docker.io/kubernetesui/dashboard-metrics-scraper@sha256:0cdefa04...
docker.io/kubernetesui/dashboard:v2.7.0
docker.io/kubernetesui/dashboard-metrics-scraper:1.2.2
docker.io/kubernetesui/dashboard-api:1.12.0
docker.io/kubernetesui/dashboard-web:1.6.2
docker.io/kubernetesui/dashboard-auth:1.2.4
docker.io/kubernetesui/dashboard@sha256:ca93706e...
docker.io/kubernetesui/dashboard-auth@sha256:d6dd67b7...
docker.io/kubernetesui/dashboard-api@sha256:dcc897f8...

Dry Run

Dry run is enabled by default. Therefore, to actually prune you must specify --dry-run false.

Count

As a safety, the CLI prunes at most --count matching manifests, which defaults to 5. Specify --count -1 to prune all the matches. Matches are taken in URL order, so a dry run shows exactly what the same command will prune with --dry-run false. When an image list manifest is pruned, its image manifests are pruned with it and don't add to the count (see below).

By Pattern

Specify --pattern with single parameter consisting of one or more manifest URL patterns separated by commas. The patterns are Golang regular expressions as documented in the regexp/syntax package documentation. The expressions on the command line are passed directly to the Golang regex parser as received from the shell, and are matched to manifest URLs. As such, shell expansion and escaping must be taken into consideration. Simplicity wins the day here. Examples:

bin/ociregistry prune --pattern kubernetesui/dashboard:v2.7.0
bin/ociregistry prune --pattern docker.io
bin/ociregistry prune --pattern curl,cilium

Add --dry-run false to the commands above to actually prune.

Patterns match the canonical URL. The server stores manifests in their canonical form. This is really only applicable to the docker/library case. For example, --pattern docker.io/hello-world won’t match the cached docker.io/library/hello-world manifest.

By Create Date/time

The --date option accepts a single parameter consisting of a UTC date/time in the form YYYY-MM-DDTHH:MM:SSZ. All manifests created before that time stamp will be selected. Example:

bin/ociregistry prune --date 2024-03-01T22:17:31Z

As of version 2.2.0, ociregistry stores manifest dates in UTC, and the list sub-command shows them in the same form. Manifests cached by earler versions of the server stored dates in local time. Those manifests are converted to UTC by the serve command of v2.2.0+ on start. Until conversion, the prune sub-command refuses to run.

The intended workflow is to use the CLI with list sub-command to determine desired a cutoff date and then to use that date as an input to the prune sub-command.

Important to know about pruning

Generally, but not always, image list manifests have tags, and image manifests have digests. This is because in most cases, upstream images are multi-architecture. For example, this command specifies a tag:

bin/ociregistry prune --pattern calico/typha:v3.27.0

In this case, on a Linux/amd64 machine running the server the CLI will find two manifests:

docker.io/calico/typha:v3.27.0
docker.io/calico/typha@sha256:eca01eab...

The first is a multi-arch image list manifest, and the second is the image manifest matching the OS and Architecture that was selected for download. In all cases, only image manifests have blob references. If your search finds only an image list manifest, the CLI logic will also look for cached image manifests (and associated blobs) for the specified image list manifest since that's probably the desired behavior. (The blobs consume the storage.)

Blob removal when pruning

Internally, the CLI begins by building a blob list with ref counts. As each image manifest is removed its referenced blobs have their count decremented. After all manifests are removed, any blob with zero refs is also removed. Removing an image manifest therefore won't remove blobs that are still referenced by un-pruned manifests.