Introduction
Docker Buildx is a CLI plugin that leverages BuildKit to build multi-platform images. BuildKit automatically caches build outputs locally to speed up rebuilds. Additionally, it supports exporting this cache to external destinations—such as cloud storage, Docker registries, or local disk—via the --cache-to option, and reusing it with --cache-from.
This external caching mechanism is especially useful in CI/CD environments where runners do not persist data between executions.
To export the BuildKit cache to a remote Docker registry and reuse it later, you can use a command like the following:
docker buildx build --platform linux/amd64,linux/arm64 \ --tag "<Artifactory-URL>/davidfa-docker/my-image:3.0.1" --push \ --cache-to=type=registry,ref="<Artifactory-URL>/davidfa-cache-layers-docker/build-cache:buildcache4" \ --cache-from=type=registry,ref="<Artifactory-URL>/davidfa-cache-layers-docker/build-cache:buildcache3" .
This command builds and pushes a multi-platform image to the davidfa-docker virtual repository on Artifactory while simultaneously exporting the build cache to the davidfa-cache-layers-docker repository under the tag buildcache3.
Explanation of --cache-to and --cache-from Options
--cache-to: Exports the BuildKit cache to a specified location.
Example:
type=registry,ref=my.artifactory/repo-cache/my-image:tag pushes a cache image to the Docker registry. The optional mode (e.g., max) determines whether all intermediate layers or only the final ones are included.
--cache-from: Imports previously stored cache layers from a remote registry.
It allows BuildKit to reuse layers from earlier builds by pointing to the same cache repository and tag.
Artifactory Behavior with Cache Layers
When using --cache-to, Artifactory treats the resulting cache layers as non-standard blobs rather than valid Docker images.
By default, Artifactory expects Docker manifests (Schema 2 or OCI-compliant) for proper image handling. However, cache components particularly the cacheconfig layer do not follow the traditional Docker mediaType. For example:
"mediaType": "application/vnd.oci.image.layer.v1.tar+gzip"
For instance, during the push process, you may observe a log entry such as:
2025-04-07T13:43:05.550Z [jfrt ] [DEBUG] [2bc58305af5ecbbc] [h.DockerManifestPutHandler:473] [http-nio-8081-exec-8] - Docker list manifest item: sha256:4f4fb700ef54461cfa02571ae0db9a0dc1e0cdb5577484a6d75e68dc38e8acc1 is not from a manifest media type: Schema1Signed. Syncing as a layer.
These BuildKit cache “images” are not intended to be executed, only reused by future builds. As such, they are treated differently by Artifactory and do not behave like standard Docker images from a retention or cleanup perspective.
Max Unique Tags Feature and Limitations
Artifactory supports automated cleanup policies for Docker repositories using the Max Unique Tags setting, which retains only a specific number of image tags per repository or path.
However, this feature does not apply to BuildKit cache artifacts pushed with --cache-to. The reasons include:
- Cache layers are pushed with a mediaType not recognized as valid Docker images.
- These layers are part of an OCI index structure specific to BuildKit, not linked to a standard Docker manifest.
- The artifacts are not tied to a recognized image tag that Artifactory uses for tag-based retention.
Consequences
Even if you push multiple BuildKit cache layers using different tags (e.g., build-cache:build1, build-cache:build2), they will not be affected by the Max Unique Tags logic, and will not be cleaned up automatically.
Conclusion
Using --cache-to and --cache-from with Docker Buildx and Artifactory can be considered as a potential approach. However, the artifacts generated by BuildKit’s caching mechanism are not valid Docker images, but rather OCI-compliant cache layers. As a result, they are excluded from tag-based retention policies such as Max Unique Tags.
Relevant links:
How to push multi-arch images to Artifactory using docker buildx?
Multi-Arch Docker Manifests with Buildx and Artifactory