Multi-platform builds and containerd image store sections are ambiguous, overlap, and missing info

[thaJeztah]

Is this a docs issue?

• My issue is about the documentation content or website

Type of issue

Information is incorrect

Description

• relates to containerd-snapshotter snapshotter not loaded moby/moby#46254 (comment)

The "Multi-platform builds" section is confusing, and has some parts that are ambiguous;

• It outlines prerequisites
• But due to how they are presented, are easy to be interpreted as "you must enable the containerd image store" AND "create a custom builder"

That's incorrect, because creating a custom builder is only needed if the containerd image-store is NOT enabled. There's information in the first paragraphs, but the "make sure that your builder and Docker Engine support multi-platform build" makes it easy to interpret it as "I need to configure both to make this work".

There's duplicate content as well;

• the "multi-platform images" page has a short form of switching to the containerd image-store, but doesn't mention all the details; https://docs.docker.com/build/building/multi-platform/#enable-the-containerd-image-store
• the containerd image-store section in desktop has more details for desktop https://docs.docker.com/desktop/containerd/
• and there's a third section in the engine section; https://docs.docker.com/engine/storage/containerd/

Missing information

QEMU as prerequisite

As an important use of the containerd image-store is to facilitate multi-platform builds, we should also consider;

• Adding steps to enable the QEMU userland-emulation in the install steps
• ☝️ this could cross-reference the https://docs.docker.com/build/building/multi-platform/#qemu section
• ☝️ probably make it more clear in that section that its NOT needed when running Docker Desktop

Storage drivers

Given that the containerd image-store uses different drivers than graphdrivers, we may want to mention this, and perhaps include an example that specifies the default driver to use, e.g.;

{
  "features": {
    "containerd-snapshotter": true
  },
  "storage-driver": "overlayfs"
}

• Perhaps the storage-drivers section should also include information about snapshotters
• Mention which pages do NOT apply to the containerd image-store

Location

https://docs.docker.com/build/building/multi-platform/#prerequisites

Suggestion

See above

[docker-robot]

There hasn't been any activity on this issue for a long time.
If the problem is still relevant, mark the issue as fresh with a /remove-lifecycle stale comment.
If not, this issue will be closed in 14 days. This helps our maintainers focus on the active issues.

Prevent issues from auto-closing with a /lifecycle frozen comment.

/lifecycle stale