How to copy multi-arch docker images to a different container registry?

Question

There's a well-known approach to have docker images copied from one container registry to another. In case the original registry is dockerhub, the typical workflow would be something like this:

docker pull <image:tag>
docker tag <image:tag> <new-reg-url/uid/image:tag>
docker push <new-reg-url/uid/image:tag>

Now, how do you the above when dealing with images with multi-architecture layers?

As per the information in this link, you can rely on buildx to construct multi-arch images, and while doing that, you can also upload those to whichever repo you wish, but how do i do this without having to first build the images?

Looks like buildx cli has unnecessarily (?) coupled the uploading process with the building one. Any suggestions?

Thanks!

Answer 1

2025 - Copy all image tags using skopeo

Here are a few scripts that use skopeo to copy all tags from one registry to another. It also supports getting a list of "sub-registries" from GitLab and copy all of them. As well as copying Helm charts from GitLab Helm repo to OCI.

https://gist.github.com/StianOvrevage/c5f7d0783edf6aa84494cfdcde5ac5b4

Answer 2

2022 docker built-in solution

It is now possible to perform the copy using the built-in docker buildx imagetools create command and specifying a --tag argument.

OLD_TAG=registry.example.com/namespaced/repository/example-image:old-tag
NEW_TAG=registry.example.com/namespaced/repository/example-image:new-tag

docker buildx imagetools create --tag "$NEW_TAG" "$OLD_TAG"

Reference documentation

Answer 3

There is an open-source tool skopeo.

Quote:

Copying an image from and to various storage mechanisms. For example you can copy images from one registry to another, without requiring privilege.

To just copy an image from one registry to another (from official examples):

skopeo copy --all docker://docker.io/skopeo/stable:latest docker://new-reg-url/skopeo:latest

Answer 4

While the docker pull ...; docker tag ...; docker push ... syntax is the easy way to move images between registries, it has a couple drawbacks. First, as you've seen, is that it dereferences a multi-platform image to a single platform. And the second is that it pulls all layers to the docker engine even if the remote registry already has those layers, making it a bad method for ephemeral CI workers that would always need to pull every layer.

To do this, I prefer talking directly to the registry servers rather than the docker engine itself. You don't need the functionality from the engine to run the images, all you need is the registry API. Docker has documented the original registry API and OCI recently went 1.0 on the distribution-spec which should get us some standardization.

There's a variety of tooling based on those specs, from the docker engine itself and containerd, to skopeo, google's crane, and I've also been working on regclient. Doing this with regclient's regctl command looks like:

regctl image copy <source_image:tag> <target_image:tag>

And the result is the various layers, image config, manifests, and multi-platform manifest list will be copied between registries, but only for the layers that don't already exist on the target registry.