Multi-arch docker with buildx

Multi-arch docker with buildx

Subscribe to my newsletter and never miss my upcoming articles

Introduction

Docker images can support multiple architectures, which means that a single image may contain variants for different architectures, and sometimes for different operating systems, such as Windows.

When running an image with multi-architecture support, docker automatically selects the image variant that matches your OS and architecture.

Most of the official images on Docker Hub provide a variety of architectures. For example, the busybox image supports amd64, arm32v5, arm32v6, arm32v7, arm64v8, i386, ppc64le, and s390x. When running this image on an x86_64 / amd64 machine, the x86_64 variant is pulled and run.

Tutorial

$ docker buildx ls                                                                                                                                                                                            

NAME/NODE     DRIVER/ENDPOINT STATUS                 PLATFORMS
desktop-linux                 protocol not available
default *     docker
  default     default         running                linux/amd64, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, linux/arm/v6
$ docker buildx version                                                                                                                                                                                       

github.com/docker/buildx v0.5.1-docker 11057da37336192bfc57d81e02359ba7ba848e4a
$ docker buildx create --use --name mybuilder                                                                                                   

mybuilder
$ docker buildx ls                                                                                                                              

NAME/NODE     DRIVER/ENDPOINT             STATUS                 PLATFORMS
mybuilder *   docker-container
  mybuilder0  unix:///var/run/docker.sock inactive
desktop-linux                             protocol not available
default       docker
  default     default                     running                linux/amd64, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/arm/v7, linux/arm/v6

main.go

package main

import (
        "fmt"
        "runtime"
)

func main() {
        fmt.Printf("Hello, %s!\n", runtime.GOARCH)
}

Dockerfile

FROM golang:alpine AS builder
RUN mkdir /app
ADD . /app/
WORKDIR /app
RUN go mod init example.com/m
RUN go build -o hello .

FROM alpine
RUN mkdir /app
WORKDIR /app
COPY --from=builder /app/hello .
CMD ["./hello"]
$ docker buildx build -t hello-go-arch --platform=linux/arm,linux/arm64,linux/amd64 .                                                           

WARN[0000] No output specified for docker-container driver. Build result will only remain in the build cache. To push result image into registry use --push or to load image into docker use --load
[+] Building 56.1s (40/40) FINISHED
 => [internal] booting buildkit                                                                                                                5.3s
 => => pulling image moby/buildkit:buildx-stable-1                                                                                             4.3s
 => => creating container buildx_buildkit_mybuilder0                                                                                           1.0s
 => [internal] load build definition from Dockerfile                                                                                           0.1s
 => => transferring dockerfile: 253B                                                                                                           0.0s
 => [internal] load .dockerignore                                                                                                              0.1s
 => => transferring context: 2B                                                                                                                0.0s
 => [linux/amd64 internal] load metadata for docker.io/library/alpine:latest                                                                  12.0s
 => [linux/amd64 internal] load metadata for docker.io/library/golang:alpine                                                                  10.9s
 => [linux/arm64 internal] load metadata for docker.io/library/alpine:latest                                                                  11.6s
 => [linux/arm64 internal] load metadata for docker.io/library/golang:alpine                                                                  10.8s
 => [linux/arm/v7 internal] load metadata for docker.io/library/alpine:latest                                                                 11.6s
 => [linux/arm/v7 internal] load metadata for docker.io/library/golang:alpine                                                                 11.5s
 => [linux/arm/v7 builder 1/6] FROM docker.io/library/golang:alpine@sha256:8b27003087e1612c4a0ba06be640b2cfcebb5590c2de9869d88669f1a9da8286   31.5s
 => => resolve docker.io/library/golang:alpine@sha256:8b27003087e1612c4a0ba06be640b2cfcebb5590c2de9869d88669f1a9da8286                         0.1s
 => => sha256:e54b3edeab2b8da45b3e3b749ee47b38c7d2d96bf0fdc1abd0f59d42c9fd4acf 156B / 156B                                                     0.3s
 => => sha256:013899c35642552607b44e264c195a8a5cccff255eec04f422cd225eb3694d95 104.75MB / 104.75MB                                            26.0s
 => => sha256:edba13042e2b42dba9e7f0e57a60855dff15f2890b8d942f61fbdc4852a43854 154B / 154B                                                     0.3s
 => => sha256:adc7b26480300ed9c6eddb3c4eb897051a740425806a7edff4973e09fae2bb8f 280.81kB / 280.81kB                                             0.3s
 => => extracting sha256:adc7b26480300ed9c6eddb3c4eb897051a740425806a7edff4973e09fae2bb8f                                                      0.1s
 => => extracting sha256:edba13042e2b42dba9e7f0e57a60855dff15f2890b8d942f61fbdc4852a43854                                                      0.1s
 => => extracting sha256:013899c35642552607b44e264c195a8a5cccff255eec04f422cd225eb3694d95                                                      5.0s
 => => extracting sha256:e54b3edeab2b8da45b3e3b749ee47b38c7d2d96bf0fdc1abd0f59d42c9fd4acf                                                      0.2s
 => [internal] load build context                                                                                                              0.5s
 => => transferring context: 415B                                                                                                              0.0s
 => [linux/arm/v7 stage-1 1/4] FROM docker.io/library/alpine@sha256:eb3e4e175ba6d212ba1d6e04fc0782916c08e1c9d7b45892e9796141b1d379ae           1.0s
 => => resolve docker.io/library/alpine@sha256:eb3e4e175ba6d212ba1d6e04fc0782916c08e1c9d7b45892e9796141b1d379ae                                0.1s
 => => sha256:4ee0caa23b369b04827640a4be298bf4ff7bacd030c77e915f5d7fb8f987594a 2.43MB / 2.43MB                                                 0.8s
 => => extracting sha256:4ee0caa23b369b04827640a4be298bf4ff7bacd030c77e915f5d7fb8f987594a                                                      0.2s
 => [linux/amd64 builder 1/6] FROM docker.io/library/golang:alpine@sha256:8b27003087e1612c4a0ba06be640b2cfcebb5590c2de9869d88669f1a9da8286    32.0s
 => => resolve docker.io/library/golang:alpine@sha256:8b27003087e1612c4a0ba06be640b2cfcebb5590c2de9869d88669f1a9da8286                         0.2s
 => => sha256:4ac7b6f906a9a07f0beb34ac4a28ce0fbd7b6eb9a6039d6f9b74304a5abb3df9 155B / 155B                                                     0.3s
 => => sha256:6c2d8e2bae38638efd21358e67410e6e73f83f95eee95ad5e42d272b0effce94 110.09MB / 110.09MB                                            26.2s
 => => sha256:e4bc8fc554c31c0fb115880309eafbbdfcbeaa5259281e59b26346027eb06831 281.50kB / 281.50kB                                             0.8s
 => => sha256:803daa35ea4774c1839c77f23e37057a576d5cce3a041b2e2b5f700cf3f036b9 155B / 155B                                                     0.3s
 => => extracting sha256:e4bc8fc554c31c0fb115880309eafbbdfcbeaa5259281e59b26346027eb06831                                                      0.1s
 => => extracting sha256:803daa35ea4774c1839c77f23e37057a576d5cce3a041b2e2b5f700cf3f036b9                                                      0.0s
 => => extracting sha256:6c2d8e2bae38638efd21358e67410e6e73f83f95eee95ad5e42d272b0effce94                                                      4.9s
 => => extracting sha256:4ac7b6f906a9a07f0beb34ac4a28ce0fbd7b6eb9a6039d6f9b74304a5abb3df9                                                      0.3s
 => [linux/amd64 stage-1 1/4] FROM docker.io/library/alpine@sha256:eb3e4e175ba6d212ba1d6e04fc0782916c08e1c9d7b45892e9796141b1d379ae            1.1s
 => => resolve docker.io/library/alpine@sha256:eb3e4e175ba6d212ba1d6e04fc0782916c08e1c9d7b45892e9796141b1d379ae                                0.1s
 => => sha256:29291e31a76a7e560b9b7ad3cada56e8c18d50a96cca8a2573e4f4689d7aca77 2.81MB / 2.81MB                                                 0.9s
 => => extracting sha256:29291e31a76a7e560b9b7ad3cada56e8c18d50a96cca8a2573e4f4689d7aca77                                                      0.2s
 => [linux/arm64 builder 1/6] FROM docker.io/library/golang:alpine@sha256:8b27003087e1612c4a0ba06be640b2cfcebb5590c2de9869d88669f1a9da8286    30.5s
 => => resolve docker.io/library/golang:alpine@sha256:8b27003087e1612c4a0ba06be640b2cfcebb5590c2de9869d88669f1a9da8286                         0.1s
 => => sha256:461d32ee99a86d8cff5bd1794440f3943fd17d6a50c3eadb153b405fbf12a55b 155B / 155B                                                     0.3s
 => => sha256:9c101dd505adce3f3cb542dc55cd2884eaa419d3f5243d616d215c7b4a291246 104.32MB / 104.32MB                                            24.0s
 => => sha256:9781401cc20597a23238fc98d1ad29844622e5789f01f5bd8253a08a6862f758 155B / 155B                                                     0.8s
 => => sha256:52e4494067509f38a40cef1846fd0e7ff8752d93c2530c65c8522c39100d7353 281.68kB / 281.68kB                                             0.4s
 => => extracting sha256:52e4494067509f38a40cef1846fd0e7ff8752d93c2530c65c8522c39100d7353                                                      0.1s
 => => extracting sha256:9781401cc20597a23238fc98d1ad29844622e5789f01f5bd8253a08a6862f758                                                      0.0s
 => => extracting sha256:9c101dd505adce3f3cb542dc55cd2884eaa419d3f5243d616d215c7b4a291246                                                      5.4s
 => => extracting sha256:461d32ee99a86d8cff5bd1794440f3943fd17d6a50c3eadb153b405fbf12a55b                                                      0.0s
 => [linux/arm64 stage-1 1/4] FROM docker.io/library/alpine@sha256:eb3e4e175ba6d212ba1d6e04fc0782916c08e1c9d7b45892e9796141b1d379ae            1.0s
 => => resolve docker.io/library/alpine@sha256:eb3e4e175ba6d212ba1d6e04fc0782916c08e1c9d7b45892e9796141b1d379ae                                0.2s
 => => sha256:fd3acdcea5682abced546ec19fb6ebee725c5184e5d91614c469c0a79e67f2d0 2.71MB / 2.71MB                                                 0.8s
 => => extracting sha256:fd3acdcea5682abced546ec19fb6ebee725c5184e5d91614c469c0a79e67f2d0                                                      0.1s
 => [linux/arm/v7 stage-1 2/4] RUN mkdir /app                                                                                                  0.2s
 => [linux/arm64 stage-1 2/4] RUN mkdir /app                                                                                                   0.2s
 => [linux/amd64 stage-1 2/4] RUN mkdir /app                                                                                                   0.2s
 => [linux/arm/v7 stage-1 3/4] WORKDIR /app                                                                                                    0.1s
 => [linux/amd64 stage-1 3/4] WORKDIR /app                                                                                                     0.1s
 => [linux/arm64 stage-1 3/4] WORKDIR /app                                                                                                     0.1s
 => [linux/arm64 builder 2/6] RUN mkdir /app                                                                                                   1.4s
 => [linux/arm/v7 builder 2/6] RUN mkdir /app                                                                                                  0.5s
 => [linux/amd64 builder 2/6] RUN mkdir /app                                                                                                   0.2s
 => [linux/arm64 builder 3/6] ADD . /app/                                                                                                      0.1s
 => [linux/arm64 builder 4/6] WORKDIR /app                                                                                                     0.1s
 => [linux/arm/v7 builder 3/6] ADD . /app/                                                                                                     0.1s
 => [linux/amd64 builder 3/6] ADD . /app/                                                                                                      0.2s
 => [linux/arm64 builder 5/6] RUN go mod init example.com/m                                                                                    0.5s
 => [linux/arm/v7 builder 4/6] WORKDIR /app                                                                                                    0.1s
 => [linux/amd64 builder 4/6] WORKDIR /app                                                                                                     0.1s
 => [linux/arm/v7 builder 5/6] RUN go mod init example.com/m                                                                                   0.4s
 => [linux/amd64 builder 5/6] RUN go mod init example.com/m                                                                                    0.2s
 => [linux/amd64 builder 6/6] RUN go build -o hello .                                                                                          0.4s
 => [linux/arm64 builder 6/6] RUN go build -o hello .                                                                                          4.0s
 => [linux/arm/v7 builder 6/6] RUN go build -o hello .                                                                                         3.8s
 => [linux/amd64 stage-1 4/4] COPY --from=builder /app/hello .                                                                                 0.1s
 => [linux/arm/v7 stage-1 4/4] COPY --from=builder /app/hello .                                                                                0.1s
 => [linux/arm64 stage-1 4/4] COPY --from=builder /app/hello .

How does this buildx magic work, you ask? Well, behind the scenes, buildx builds three Docker images (one for each of arm, arm64, and amd64) using QEMU and binfmt_misc as needed. When it's done building, it will create a Docker manifest list which contains pointers to the three images. In other words, a "multi-arch image" is really just a manifest list with links to images built per architecture.

Now that the images for the specified architectures are built, we can either push them all to DockerHub or we can load a specific architecture to our local docker image registry and try it out

$ docker buildx build --load --platform=linux/arm64 -t hello-go-arch .    

[+] Building 3.3s (17/17) FINISHED
 => [internal] load build definition from Dockerfile                                                                                           0.0s
 => => transferring dockerfile: 253B                                                                                                           0.0s
 => [internal] load .dockerignore                                                                                                              0.0s
 => => transferring context: 2B                                                                                                                0.0s
 => [internal] load metadata for docker.io/library/alpine:latest                                                                               2.1s
 => [internal] load metadata for docker.io/library/golang:alpine                                                                               1.8s
 => [builder 1/6] FROM docker.io/library/golang:alpine@sha256:8b27003087e1612c4a0ba06be640b2cfcebb5590c2de9869d88669f1a9da8286                 0.0s
 => => resolve docker.io/library/golang:alpine@sha256:8b27003087e1612c4a0ba06be640b2cfcebb5590c2de9869d88669f1a9da8286                         0.0s
 => [stage-1 1/4] FROM docker.io/library/alpine@sha256:eb3e4e175ba6d212ba1d6e04fc0782916c08e1c9d7b45892e9796141b1d379ae                        0.1s
 => => resolve docker.io/library/alpine@sha256:eb3e4e175ba6d212ba1d6e04fc0782916c08e1c9d7b45892e9796141b1d379ae                                0.1s
 => [internal] load build context                                                                                                              0.0s
 => => transferring context: 59B                                                                                                               0.0s
 => CACHED [stage-1 2/4] RUN mkdir /app                                                                                                        0.0s
 => CACHED [stage-1 3/4] WORKDIR /app                                                                                                          0.0s
 => CACHED [builder 2/6] RUN mkdir /app                                                                                                        0.0s
 => CACHED [builder 3/6] ADD . /app/                                                                                                           0.0s
 => CACHED [builder 4/6] WORKDIR /app                                                                                                          0.0s
 => CACHED [builder 5/6] RUN go mod init example.com/m                                                                                         0.0s
 => CACHED [builder 6/6] RUN go build -o hello .                                                                                               0.0s
 => CACHED [stage-1 4/4] COPY --from=builder /app/hello .                                                                                      0.0s
 => exporting to oci image format                                                                                                              1.0s
 => => exporting layers                                                                                                                        0.3s
 => => exporting manifest sha256:ad8af91a831fccf968a97c29b0a66503cc3261dffb0868e40b6aa1f158a79b4c                                              0.0s
 => => exporting config sha256:599b39d80749dd5e1e69be31d0cb7aaaea4e7721796347b22d61be376f83a931                                                0.0s
 => => sending tarball                                                                                                                         0.6s
 => importing to docker

And now we can run the image,

$ docker run --platform=linux/arm64 hello-go-arch                                                                                                                      
Hello, arm64!

Also we can try the arm platform

$ docker buildx build --load --platform=linux/arm -t hello-go-arch .                                                                            
$ docker run --platform=linux/arm hello-go-arch                                                                                                 
Hello, arm!

Conclusion

To summarise, we saw how without making a single change to our Dockerfile we were able to build the sample application with multi-arch support, multiple docker images for arm, arm64 and amd64 were generated, and then we can load the architecture we want and run it. Its likely that in the future all of this would get automated and even more easier to use, just stuff it in in some yaml file and docker will make the required images for you, and buildx will become a standard part of docker.

 
Share this