How do I import and run a multi-platform OCI image in Docker for macOS?

Question

I have a go web service that I've been building with docker build and running with docker run on my M1 Mac and on various Linux machines for a while. It's a simple binary installed on a distroless base and works great. Now I want to make a multi-platform image export to send to co-workers to run on their computers (M1 and Intel Macs). I've made an OC export like so:

docker buildx build --platform linux/amd64,linux/arm64 -t toy -o type=oci,dest=toy.oci .

And importing works fine:

docker image import toy.oci toy
sha256:02f7342d9d6ec2a1b66440aedb8d9a6ae0e968373fc8f2b698f7c8e73e6747e0

Running it is another matter:

docker run -d --name toy -p 4242:4242 toy:latest
docker: Error response from daemon: No command specified.
See 'docker run --help'.

This is odd, because my Dockerfile has an ENTRYPOINT . Whatever, I try to tell it the command to run:

docker run -d --name toy -p 4242:4242 toy:latest /bin/toy
docker: Error response from daemon: failed to create shim task: OCI runtime create failed: runc create failed: unable to start container process: exec: "/bin/toy": stat /bin/toy: no such file or directory: unknown.

It's almost as if the container has no files in it! docker image ls shows my 32MB image, so I know there's something there, but where is it? Is there a layer missing?

FWIW I tried type=tar , too, and got the same result.

I assume I'm missing a step, but my DuckDuckGo-foo fails me. How does one build exportable multi-platform Docker images that actually work?

Answer 1

Several things happening at once here:

• You can only import a single platform image.
• To import an image, you should use docker load . The docker import command loads a filesystem export from a container, and will not have any image metadata.
• The docker load command expects its own metadata that is different from an OCI Layout.

I have functionality in regctl to pull out the specific platform and do the conversion that just got checked into main (so it will be released in v0.4.5, or you can pull the binaries direct from GHA if you don't want to build it yourself). The commands to do this look like:

# regclient works with directories rather than tars, so import the OCI tar to a directory
regctl image import ocidir://toy toy.oci
# get the digest from your local platform, you can also change "local" to "linux/amd64"
dig="$(regctl image digest --platform local ocidir://toy)"
# export the single platform image using the digest
regctl image export "ocidir://toy@${dig}" toy-docker.tar
# load into docker
docker load <toy-docker.tar

Answer 2

@BMitch's answer nicely addresses the various issues here, enough to get me to where I could get things to work purely with Docker. The kicker is the lack of support for loading multiplatform images, so there must be separate images per platform. The incantation for that is:

docker buildx build --platform linux/amd64 -t toy -o type=docker,dest=toy-amd64.tar .
docker buildx build --platform linux/arm64 -t toy -o type=docker,dest=toy-arm64.tar .

Then the individual tar files can be shared with whomever, and loaded with:

docker load <toy-arm64.tar
docker run -d --name toy -p 4242:4242 toy:latest /bin/toy

Switch to toy-amd64.tar on AMD64 platforms.

For kicks, I made make targets to do the builds and load like so:

docker-export: $(patsubst %,toy-%.tar, arm64 amd64)

toy-%.tar: vendor cmd/toy/toy.go schema/*.schema.json corpus/user/valid/*.json
    docker buildx build --platform linux/$* -t nytimes/toy -o type=docker,dest=$@ .

# Import an exported docker image for the current architecture.
docker-import: toy-$(patsubst aarch64,$(shell docker --debug info | grep Architecture | awk '{print $2}'),arm64).tar
    docker load <toy-$(patsubst aarch64,$(shell docker --debug info | grep Architecture | awk '{print $2}'),arm64).tar

Answer 3

The way that I've been building images with multi-arch support on my M1 is:

• Run docker buildx create --bootstrap
• Ensure that the node is up and running with the appropriate platforms docker buildx ls and that is selected, there is an asterisk next to the name of the node, otherwise run: docker buildx use [node] .
• Start building your image: docker buildx build --platform linux/amd64,linux/arm64 -t sample:v1 . --push docker buildx build --platform linux/amd64,linux/arm64 -t sample:v1 . --push . This will push the images to a registry.

Once the image is in the registry, your co-workers can start pulling it. This is the simplest way, as I've had issues in the past trying other destination outputs.