Docker: QEMU emulation to run arm64 images from native amd64 host

If you want to use Docker to build cross-platform images, the first step is to enable QEMU to run images targeted at others architectures via emulation.

I assume you have installed Docker CE and its containerd runtime as described here, and are running on a x86_64 host.

Test current ability to emulate other architectures

# our current host architecture will report "x86_64"
uname -m

# trying to run ARM64 image will fail, "The requested image's platform does not match the detected host platform"
sudo docker run --rm -t arm64v8/alpine uname -m

# will not have binary format registration list
sudo ls -l /proc/sys/fs/binfmt_misc/qemu-*

Add ARM support

# add qemu packages required
sudo apt install -y qemu binfmt-support qemu-user-static

# flag value is 'POCF', binfmt not registered yet
sudo grep '^flags' /proc/sys/fs/binfmt_misc/qemu-arm

# invoke tool that registers binfmt with QEMU for different architectures
sudo docker run --rm --privileged multiarch/qemu-user-static --reset -p yes

# flag value is now 'F', registered correctly
sudo grep '^flags' /proc/sys/fs/binfmt_misc/qemu-arm

Validate ability to emulate other architectures

# ARM64 image should run now (aarch64 is arm64 family)
sudo docker run --rm --platform linux/arm64/v8 -t arm64v8/alpine uname -m

Let’s also test running the arm64 version of a multi-architecture manifest index list (fat manifest).

# targeting arm64 for multi-platform Dockerv2.2 manifest index 
sudo docker run --rm -i --platform linux/arm64/v8 fabianlee/tiny-tools-multi-archv22:2.0.0 uname -m

# targeting arm64 for multi-platform OCI schema manifest index
sudo docker run --rm -i --platform linux/arm64/v8 fabianlee/tiny-tools-multi-arch:2.0.0 uname -m

 

REFERENCES

docker, Official install doc

github docker buildx, documentation on building multi-platform images

docker, multi-platform building with QEMU

docker, multi-platform not necessary if your language provides cross-compliation

ubuntu.com, qemu-system-arm on Ubuntu20

qemu ARM on raspberrryPI

launchpad.net, qemu-user-static package for jammy

martin-grigorov, docker container that runs steps on host required to run foreign architectures

github bossjones, allows non-ARM hosts to run ARM containers, registers static QEMU library on host

github issue qemu-user-static, mention of docker tool above for registering

stackoverflow, explanation of nuances of multiarch/qemu-user-static behavior

wikipedia, binfmt flag explanation

hub.docker.com, arm64v8/alpine

hub.docker.com, tiny-tools-multi-arch

hub.docker.com, tiny-tools-multi-arch-dockerv22

github fabianlee, tiny-tools-multi-arch

danmanners.com, buildah for multi-arch

github buildah, docs for create manifest

andrewlock.net, ‘load’ can be used to pull up buildx images, but not local pull

aarch64 and arm64 are same family