improve docs on "emulated" vs "native" multi-arch builds

[thaJeztah]

Looking at the https://docs.docker.com/build/building/multi-platform/ page, we describe how multi-arch images are built with (container)builders. As there's advantages / disadvantages on using QEMU emulation and native builders (QEMU easier to set up, but at a performance penalty, and it's a "best effort"), perhaps we should have a section outlining the pros/cons of

• docker builder (currently: without containerd-integration)
• container builder (using QEMU)
• native builders

Relates to the commend posted by @jedevc in #1507 (comment)

/cc @dvdksn

[bubenkoff]

Would be great if it was possible to have an 'official' way of building and pushing multiarch images via docker/build-push-action github action so that the workaround to avoid the quemu performance penalty mentioned in docker/build-push-action#755 (comment) is not needed

[polarathene]

@thaJeztah

FWIW since this issue was opened, the page has received an update that better communicates several strategies and their pros/cons (within their respective sections). The first strategy QEMU, highlights ease of use while raising awareness of performance concerns, and encouraging cross-compilation strategy if viable. The Native builder nodes section also highlights its performance advantage (additionally linking to advice for distributing a build to multiple CI runners with Github Actions).

Related, for Github Actions the multi-platform CI example has since moved to its own page and has received two new examples:

• https://docs.docker.com/build/ci/github-actions/multi-platform/#distribute-build-across-multiple-runners
• https://docs.docker.com/build/ci/github-actions/multi-platform/#with-bake

Those are a little messy and could maybe benefit from some revision in future, but big improvement 👍

---

@bubenkoff

Would be great if it was possible to have an 'official' way of building and pushing multiarch images via docker/build-push-action github action so that the workaround to avoid the qemu performance penalty

Does the above resolve your concern? Without native runners to distribute a build to, you'll still hit a qemu performance penalty.

• The official docs still help mitigate that with a matrix build so each platform is built in platform despite the emulation overhead, which is much better than sequential.
• If you have access to native nodes, you can likewise follow the official guide for that to avoid any qemu overhead.

---

If you'd like something in-between those two

I have been using Github Actions reusable workflows to separate build and publish responsibilities.

• They can take inputs for platforms, allowing for building platforms separately (parallel) or sequentially (eg: for PR tests we're only interested in our native AMD64 build and successful build of ARM64 image).
  • We defer the ARM64 build until AMD64 is successful, and run tests in parallel to the ARM64 build. This way the tests begin ASAP, but we don't waste time building ARM64 if the AMD64 image has a build issue that'd probably affect ARM64 too.
  • While our CI behaves differently for merged PRs to the default branch, which builds + tests and additionally publishes.
• The reusable publish workflow avoids the referenced manifest workaround by leveraging the CI cache from the earlier build workflow (which can run across multiple runners). It doesn't need the flexibility with platform selection, so both are hard-coded.

That's not the greatest example, and I still need to get around to updating the cache approach to also support the ARM64 build (likely via the GH cache feature that was brand new at the time).

I just wanted to illustrate another approach that is very similar to the distributed example with digests, except instead:

• upload-artifact + download-artifact, it used actions-cache.
• buildx imagetools create to construct a multi-platform manifest, it just does a rebuild with docker/build-push-action leveraging the build cache.

It could definitely be simplified (and not split build + publish, using an expression to enable push). I think it'd be easier to grok.

I'm not quite sure how much the digest upload/download example uses bandwidth wise. I assume that's lightweight vs the cache approach, so my approach may be less efficient but maybe more flexible (nothing gets pushed to a registry until the final step too, useful for local image testing with the same reusable workflow).

I'm working on a revision of this approach, so let me know if it'd interest you and I'll share it once I'm done 👍

[dvdksn]

as @polarathene said, we've had multiple revisions of this page since this issue was originally created, and I think it now better answers the pros and cons about the different multi-platform strategies (among other things). So I'm closing this issue as done, feel free to raise a new issue if you would like to see additional improvements.