From cf7f4366d85665631e22eb416040d00bc5ae430d Mon Sep 17 00:00:00 2001 From: CrazyMax Date: Sat, 10 Sep 2022 14:17:06 +0200 Subject: [PATCH] build: rework and merge multi-arch content Signed-off-by: CrazyMax --- _data/toc.yaml | 2 - build/building/multi-platform.md | 200 ++++++++++++++++++++++++++++++- desktop/multi-arch.md | 176 --------------------------- 3 files changed, 197 insertions(+), 181 deletions(-) delete mode 100644 desktop/multi-arch.md diff --git a/_data/toc.yaml b/_data/toc.yaml index 357f8b0b39..93f046ae7d 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -1179,8 +1179,6 @@ manuals: title: Known issues for Mac - sectiontitle: Additional resources section: - - path: /desktop/multi-arch/ - title: Multi-arch support - path: /desktop/kubernetes/ title: Deploy on Kubernetes - path: /desktop/backup-and-restore/ diff --git a/build/building/multi-platform.md b/build/building/multi-platform.md index 6a61bb0c89..1d8a336303 100644 --- a/build/building/multi-platform.md +++ b/build/building/multi-platform.md @@ -4,11 +4,33 @@ description: Different strategies for building multi-platform images keywords: build, buildx, buildkit, multi-platform images redirect_from: - /build/buildx/multiplatform-images/ +- /docker-for-mac/multi-arch/ +- /mackit/multi-arch/ --- -BuildKit is designed to work well for building for multiple platforms and not -only for the architecture and operating system that the user invoking the build -happens to run. +Docker images can support multiple platforms, 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-platform support, `docker` automatically +selects the image that matches your OS and architecture. + +Most of the Docker Official Images on Docker Hub provide a [variety of architectures](https://github.com/docker-library/official-images#architectures-other-than-amd64){: target="_blank" rel="noopener" class="_" }. +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 `amd64` variant is pulled and run. + +## Building multi-platform images + +Docker is now making it easier than ever to develop containers on, and for Arm +servers and devices. Using the standard Docker tooling and processes, you can +start to build, push, pull, and run images seamlessly on different compute +architectures. In most cases, you don't have to make any changes to Dockerfiles +or source code to start building for Arm. + +BuildKit with [Buildx](../buildx/index.md) is designed to work well for +building for multiple platforms and not only for the architecture and +operating system that the user invoking the build happens to run. When you invoke a build, you can set the `--platform` flag to specify the target platform for the build output, (for example, `linux/amd64`, `linux/arm64`, or @@ -79,3 +101,175 @@ RUN echo "I am running on $BUILDPLATFORM, building for $TARGETPLATFORM" > /log FROM alpine COPY --from=build /log /log ``` + +## Getting started + +Run the [`docker buildx ls` command](../../engine/reference/commandline/buildx_ls.md) +to list the existing builders: + +```console +$ docker buildx ls +NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS +default * docker + default default running 20.10.17 linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 +``` + +This displays the default builtin driver, that uses the BuildKit server +components built directly into the docker engine, also known as the [`docker` driver](../buildx/drivers/docker.md). + +Create a new builder using the [`docker-container` driver](../buildx/drivers/docker-container.md) +which gives you access to more complex features like multi-platform builds +and the more advanced cache exporters, which are currently unsupported in the +default `docker` driver: + +```console +$ docker buildx create --name mybuilder --driver docker-container --bootstrap +mybuilder +``` + +Switch to the new builder and inspect it: + +```console +$ docker buildx use mybuilder +``` + +> **Note** +> +> Alternatively, run `docker buildx create --name mybuilder --driver docker-container --bootstrap --use` +> to create a new builder and switch to it using a single command. + +And inspect it: + +```console +$ docker buildx inspect +Name: mybuilder +Driver: docker-container + +Nodes: +Name: mybuilder0 +Endpoint: unix:///var/run/docker.sock +Status: running +Buildkit: v0.10.4 +Platforms: linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/mips64le, linux/mips64, linux/arm/v7, linux/arm/v6 +``` + +Now listing the existing builders again, we can see our new builder is +registered: + +```console +$ docker buildx ls +NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS +mybuilder docker-container + mybuilder0 unix:///var/run/docker.sock running v0.10.4 linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/arm64, linux/riscv64, linux/ppc64le, linux/s390x, linux/386, linux/mips64le, linux/mips64, linux/arm/v7, linux/arm/v6 +default * docker + default default running 20.10.17 linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 +``` + +## Example + +Test the workflow to ensure you can build, push, and run multi-platform images. +Create a simple example Dockerfile, build a couple of image variants, and push +them to Docker Hub. + +The following example uses a single `Dockerfile` to build an Alpine image with +cURL installed for multiple architectures: + +```dockerfile +# syntax=docker/dockerfile:1 +FROM alpine:3.16 +RUN apk add curl +``` + +Build the Dockerfile with buildx, passing the list of architectures to +build for: + +```console +$ docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t /:latest --push . +... +#16 exporting to image +#16 exporting layers +#16 exporting layers 0.5s done +#16 exporting manifest sha256:71d7ecf3cd12d9a99e73ef448bf63ae12751fe3a436a007cb0969f0dc4184c8c 0.0s done +#16 exporting config sha256:a26f329a501da9e07dd9cffd9623e49229c3bb67939775f936a0eb3059a3d045 0.0s done +#16 exporting manifest sha256:5ba4ceea65579fdd1181dfa103cc437d8e19d87239683cf5040e633211387ccf 0.0s done +#16 exporting config sha256:9fcc6de03066ac1482b830d5dd7395da781bb69fe8f9873e7f9b456d29a9517c 0.0s done +#16 exporting manifest sha256:29666fb23261b1f77ca284b69f9212d69fe5b517392dbdd4870391b7defcc116 0.0s done +#16 exporting config sha256:92cbd688027227473d76e705c32f2abc18569c5cfabd00addd2071e91473b2e4 0.0s done +#16 exporting manifest list sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 0.0s done +#16 ... + +#17 [auth] /:pull,push token for registry-1.docker.io +#17 DONE 0.0s + +#16 exporting to image +#16 pushing layers +#16 pushing layers 3.6s done +#16 pushing manifest for docker.io//:latest@sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 +#16 pushing manifest for docker.io//:latest@sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 1.4s done +#16 DONE 5.6s +``` + +> **Note** +> +> * `` must be a valid Docker ID and `` and valid repository on +> Docker Hub. +> * The `--platform` flag informs buildx to create Linux images for AMD 64-bit, +> Arm 64-bit, and Armv7 architectures. +> * The `--push` flag generates a multi-arch manifest and pushes all the images +> to Docker Hub. + +Inspect the image using [`docker buildx imagetools` command](../../engine/reference/commandline/buildx_imagetools.md): + +```console +$ docker buildx imagetools inspect /:latest +Name: docker.io//:latest +MediaType: application/vnd.docker.distribution.manifest.list.v2+json +Digest: sha256:f3b552e65508d9203b46db507bb121f1b644e53a22f851185d8e53d873417c48 + +Manifests: + Name: docker.io//:latest@sha256:71d7ecf3cd12d9a99e73ef448bf63ae12751fe3a436a007cb0969f0dc4184c8c + MediaType: application/vnd.docker.distribution.manifest.v2+json + Platform: linux/amd64 + + Name: docker.io//:latest@sha256:5ba4ceea65579fdd1181dfa103cc437d8e19d87239683cf5040e633211387ccf + MediaType: application/vnd.docker.distribution.manifest.v2+json + Platform: linux/arm64 + + Name: docker.io//:latest@sha256:29666fb23261b1f77ca284b69f9212d69fe5b517392dbdd4870391b7defcc116 + MediaType: application/vnd.docker.distribution.manifest.v2+json + Platform: linux/arm/v7 +``` + +The image is now available on Docker Hub with the tag `/:latest`. +You can use this image to run a container on Intel laptops, Amazon EC2 Graviton +instances, Raspberry Pis, and on other architectures. Docker pulls the correct +image for the current architecture, so Raspberry PIs run the 32-bit Arm version +and EC2 Graviton instances run 64-bit Arm. + +The digest identifies a fully qualified image variant. You can also run images +targeted for a different architecture on Docker Desktop. For example, when +you run the following on a macOS: + + ```console +$ docker run --rm docker.io//:latest@sha256:2b77acdfea5dc5baa489ffab2a0b4a387666d1d526490e31845eb64e3e73ed20 uname -m +aarch64 +``` + +```console +$ docker run --rm docker.io//:latest@sha256:723c22f366ae44e419d12706453a544ae92711ae52f510e226f6467d8228d191 uname -m +armv7l +``` + +In the above example, `uname -m` returns `aarch64` and `armv7l` as expected, +even when running the commands on a native macOS or Windows developer machine. + +## Support on Docker Desktop + +[Docker Desktop](../../desktop/index.md) provides `binfmt_misc` +multi-architecture support, which means you can run containers for different +Linux architectures such as `arm`, `mips`, `ppc64le`, and even `s390x`. + +This does not require any special configuration in the container itself as it +uses [qemu-static](https://wiki.qemu.org/Main_Page){: target="_blank" rel="noopener" class="_" } +from the **Docker for Mac VM**. Because of this, you can run an ARM container, +like the `arm32v7` or `ppc64le` variants of the busybox image. diff --git a/desktop/multi-arch.md b/desktop/multi-arch.md deleted file mode 100644 index be27e8b587..0000000000 --- a/desktop/multi-arch.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -description: Multi-CPU Architecture Support -keywords: mac, windows, Multi-CPU architecture support -redirect_from: -- /docker-for-mac/multi-arch/ -- /mackit/multi-arch/ -title: Leverage multi-CPU architecture support ---- - -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 Docker Official Images on Docker Hub provide a [variety of architectures](https://github.com/docker-library/official-images#architectures-other-than-amd64){: target="_blank" rel="noopener" class="_" }. -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 `amd64` variant is pulled and run. - -## Multi-arch support on Docker Desktop - -**Docker Desktop** provides `binfmt_misc` multi-architecture support, -which means you can run containers for different Linux architectures -such as `arm`, `mips`, `ppc64le`, and even `s390x`. - -This does not require any special configuration in the container itself as it uses -[qemu-static](https://wiki.qemu.org/Main_Page){: target="_blank" rel="noopener" class="_" } -from the **Docker for Mac VM**. Because of this, you can run an ARM container, -like the `arm32v7` or `ppc64le` variants of the busybox image. - -## Build multi-arch images with Buildx - -Docker is now making it easier than ever to develop containers on, and for Arm -servers and devices. Using the standard Docker tooling and processes, you can -start to build, push, pull, and run images seamlessly on different compute -architectures. In most cases, you don't have to make any changes to Dockerfiles -or source code to start building for Arm. - -Docker introduces a new CLI command called `buildx`. You can use the `buildx` -command on Docker Desktop for Mac and Windows to build multi-arch images, link -them together with a manifest file, and push them all to a registry using a -single command. With the included emulation, you can transparently build more -than just native images. Buildx accomplishes this by adding new builder -instances based on BuildKit, and leveraging Docker Desktop's technology stack -to run non-native binaries. - -For more information about the Buildx CLI command, see [Buildx](../build/buildx/index.md) -and the [`docker buildx` command line reference](../engine/reference/commandline/buildx.md). - -### Build and run multi-architecture images - -Run the `docker buildx ls` command to list the existing builders. This displays -the default builder, which is our old builder. - -```console -$ docker buildx ls - -NAME/NODE DRIVER/ENDPOINT STATUS PLATFORMS -default * docker - default default running linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 -``` - -Create a new builder which gives access to the new multi-architecture features. - -```console -$ docker buildx create --name mybuilder - -mybuilder -``` - -Alternatively, run `docker buildx create --name mybuilder --use` to create a new -builder and switch to it using a single command. - -Switch to the new builder and inspect it. - -```console -$ docker buildx use mybuilder - -$ docker buildx inspect --bootstrap - -[+] Building 2.5s (1/1) FINISHED - => [internal] booting buildkit 2.5s - => => pulling image moby/buildkit:master 1.3s - => => creating container buildx_buildkit_mybuilder0 1.2s -Name: mybuilder -Driver: docker-container - -Nodes: -Name: mybuilder0 -Endpoint: unix:///var/run/docker.sock -Status: running - -Platforms: linux/amd64, linux/arm64, linux/arm/v7, linux/arm/v6 -``` - -Test the workflow to ensure you can build, push, and run multi-architecture -images. Create a simple example Dockerfile, build a couple of image variants, -and push them to Docker Hub. - -The following example uses a single `Dockerfile` to build an Ubuntu image with cURL -installed for multiple architectures. - -Create a `Dockerfile` with the following: - -```dockerfile -FROM ubuntu:20.04 -RUN apt-get update && apt-get install -y curl -``` - -Build the Dockerfile with buildx, passing the list of architectures to build for: - -```console -$ docker buildx build --platform linux/amd64,linux/arm64,linux/arm/v7 -t username/demo:latest --push . - -[+] Building 6.9s (19/19) FINISHED -... - => => pushing layers 2.7s - => => pushing manifest for docker.io/username/demo:latest 2.2 -``` - -Where, `username` is a valid Docker username. - -> **Notes:** -> -> - The `--platform` flag informs buildx to generate Linux images for AMD 64-bit, -> Arm 64-bit, and Armv7 architectures. -> - The `--push` flag generates a multi-arch manifest and pushes all the images -> to Docker Hub. - -Inspect the image using `docker buildx imagetools`. - -```console -$ docker buildx imagetools inspect username/demo:latest - -Name: docker.io/username/demo:latest -MediaType: application/vnd.docker.distribution.manifest.list.v2+json -Digest: sha256:2a2769e4a50db6ac4fa39cf7fb300fa26680aba6ae30f241bb3b6225858eab76 - -Manifests: - Name: docker.io/username/demo:latest@sha256:8f77afbf7c1268aab1ee7f6ce169bb0d96b86f585587d259583a10d5cd56edca - MediaType: application/vnd.docker.distribution.manifest.v2+json - Platform: linux/amd64 - - Name: docker.io/username/demo:latest@sha256:2b77acdfea5dc5baa489ffab2a0b4a387666d1d526490e31845eb64e3e73ed20 - MediaType: application/vnd.docker.distribution.manifest.v2+json - Platform: linux/arm64 - - Name: docker.io/username/demo:latest@sha256:723c22f366ae44e419d12706453a544ae92711ae52f510e226f6467d8228d191 - MediaType: application/vnd.docker.distribution.manifest.v2+json - Platform: linux/arm/v7 -``` - -The image is now available on Docker Hub with the tag `username/demo:latest`. You -can use this image to run a container on Intel laptops, Amazon EC2 Graviton instances, -Raspberry Pis, and on other architectures. Docker pulls the correct image for the -current architecture, so Raspberry Pis run the 32-bit Arm version and EC2 Graviton -instances run 64-bit Arm. The SHA tags identify a fully qualified image variant. -You can also run images targeted for a different architecture on Docker Desktop. - -You can run the images using the SHA tag, and verify the architecture. For -example, when you run the following on a macOS: - - ```console -$ docker run --rm docker.io/username/demo:latest@sha256:2b77acdfea5dc5baa489ffab2a0b4a387666d1d526490e31845eb64e3e73ed20 uname -m -aarch64 -``` - -```console -$ docker run --rm docker.io/username/demo:latest@sha256:723c22f366ae44e419d12706453a544ae92711ae52f510e226f6467d8228d191 uname -m -armv7l -``` - -In the above example, `uname -m` returns `aarch64` and `armv7l` as expected, -even when running the commands on a native macOS or Windows developer machine.