docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #19349 from dvdksn/c8d-improve-docs 

containerd: refresh docs and add to build guide
This commit is contained in:
David Karlsson 2024-02-08 20:36:22 +01:00 committed by GitHub
parent 6337344440 7e2d301155
commit 7b5bfd6a97
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 86 additions and 197 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
content/build/building/multi-platform.md
View File

@ -61,7 +61,7 @@ loads it through a binary registered in the `binfmt_misc` handler.
> Use [multiple native nodes](#multiple-native-nodes) or
> [cross-compilation](#cross-compilation) instead, if possible.
## Support on Docker Desktop
#### Support on Docker Desktop
[Docker Desktop](../../desktop/index.md) provides `binfmt_misc`
multi-architecture support, which means you can run containers for different

92
content/build/guide/multi-platform.md
View File

@ -21,70 +21,58 @@ $ docker build --target=server --platform=linux/arm/v7 .
```
You can also use emulation to produce outputs for multiple platforms at once.
However, the default build driver doesn't support concurrent multi-platform
builds. So first, you need to switch to a different builder, that uses a driver
However, the default image store in Docker Engine doesn't support building
and loading multi-platform images. You need to enable the containerd image store
which supports concurrent multi-platform builds.
To switch to using a different driver, you're going to need to use the Docker
Buildx. Buildx is the next generation build client, and it provides a similar
user experience to the regular `docker build` command that you’re used to, while
supporting additional features.
## Enable the containerd image store
## Buildx setup
{{< tabs >}}
{{< tab name="Docker Desktop" >}}
Buildx comes pre-bundled with Docker Desktop, and you can invoke this build
client using the `docker buildx` command. No need for any additional setup. If
you installed Docker Engine manually, you may need to install the Buildx plugin
separately. See
[Install Docker Engine](../../engine/install/index.md) for instructions.
To enable the containerd image store in Docker Desktop,
go to **Settings** and select **Use containerd for pulling and storing images**
in the **General** tab.
Verify that the Buildx client is installed on your system, and that you’re able
to run it:
Note that changing the image store means you'll temporarily lose access to
images and containers in the classic image store.
Those resources still exist, but to view them, you'll need to
disable the containerd image store.
```console
$ docker buildx version
github.com/docker/buildx v0.10.3 79e156beb11f697f06ac67fa1fb958e4762c0fab
{{< /tab >}}
{{< tab name="Docker Engine" >}}
If you're not using Docker Desktop,
enable the containerd image store by adding the following feature configuration
to your `/etc/docker/daemon.json` configuration file.
```json {hl_lines=3}
{
"features": {
"containerd-snapshotters": true
}
}
```
Next, create a builder that uses the `docker-container`. Run the following
`docker buildx create` command:
Restart the daemon after updating the configuration file.
```console
$ docker buildx create --driver=docker-container --name=container
$ systemctl restart docker
```
This creates a new builder with the name `container`. You can list available
builders with `docker buildx ls`.
```console
$ docker buildx ls
NAME/NODE DRIVER/ENDPOINT STATUS
container docker-container
container_0 unix:///var/run/docker.sock inactive
default * docker
default default running
desktop-linux docker
desktop-linux desktop-linux running
```
The status for the new `container` builder is inactive. That's fine - it's
because you haven't started using it yet.
{{< /tab >}}
{{< /tabs >}}
## Build using emulation
To run multi-platform builds with Buildx, invoke the `docker buildx build`
command, and pass it the same arguments as you did to the regular `docker build`
command before. Only this time, also add:
To run multi-platform builds, invoke the `docker build` command,
and pass it the same arguments as you did before.
Only this time, also add a `--platform` flag specifying multiple architectures.
- `--builder=container` to select the new builder
- `--platform=linux/amd64,linux/arm/v7,linux/arm64/v8` to build for multiple
architectures at once
```console
$ docker buildx build \
```console {hl_lines=4}
$ docker build \
--target=binaries \
--output=bin \
--builder=container \
--platform=linux/amd64,linux/arm64,linux/arm/v7 .
```
@ -104,8 +92,8 @@ bin
└── server
```
When you build using a builder that supports multi-platform builds, the builder
runs all of the build steps under emulation for each platform that you specify.
When you build for multiple platforms concurrently,
BuildKit runs all of the build steps under emulation for each platform that you specify.
Effectively forking the build into two concurrent processes.
![Build pipelines using emulation](./images/emulation.png)
@ -222,10 +210,9 @@ illustrates how to build, and export, binaries for Mac (ARM64), Windows, and
Linux:
```console
$ docker buildx build \
$ docker build \
--target=binaries \
--output=bin \
--builder=container \
--platform=darwin/arm64,windows/amd64,linux/amd64 .
```
@ -253,9 +240,8 @@ using emulation and cross-compilation.
Related information:
- [Multi-platfom images](../building/multi-platform.md)
- [Drivers overview](../drivers/index.md)
- [Docker container driver](../drivers/docker-container.md)
- [`docker buildx create` CLI reference](../../engine/reference/commandline/buildx_create.md)
- [containerd image store (Docker Desktop)](../../desktop/containerd.md)
- [containerd image store (Docker Engine)](../../storage/containerd.md)
You may also want to consider checking out
[xx - Dockerfile cross-compilation helpers](https://github.com/tonistiigi/xx).

2
content/build/guide/next-steps.md
View File

@ -31,4 +31,4 @@ extension or ad blocker, if you use one.
You can also submit an issue on
[the docs GitHub repository](https://github.com/docker/docs/issues/new),
if you prefer.
if you prefer.

187
content/desktop/containerd.md
View File

@ -8,173 +8,76 @@ toc_max: 3
This page provides information about the ongoing integration of `containerd` for
image and file system management in the Docker Engine.
## What is the containerd image store?
## What is containerd?
`containerd` is a container runtime that manages the container lifecycle, and
provides image and filesystem management. It's a low-level building block,
designed to be integrated into other systems, such as Docker and Kubernetes.
`containerd` is an abstraction of the low-level kernel features
used to run and manage containers on a system.
It's a platform used in container software like Docker and Kubernetes.
Docker Engine already uses `containerd` for container lifecycle management, which
includes creating, starting, and stopping containers. This page describes the
next step of containerd integration for Docker Engine: the image store.
Docker Engine already uses `containerd` for container lifecycle management,
which includes creating, starting, and stopping containers.
This page describes the next step of the containerd integration for Docker:
the containerd image store.
The image store is the component responsible for pushing, pulling, and storing
images. Integrating the containerd image store enables many new features in the
Docker Engine, including:
## Image store
- containerd snapshotters, such as [stargz][1] for lazy-pulling images on startup,
The image store is the component responsible for pushing, pulling,
and storing images on the filesystem.
The classic Docker image store is limited in the types of images that it supports.
For example, it doesn't support image indices, containing manifest lists.
When you create multi-platform images, for example,
the image index resolves all the platform-specific variants of the image.
An image index is also required when building images with attestations.
The containerd image store extends range of image types
that the Docker Engine can natively interact with.
While this is a low-level architectural change,
it's a prerequisite for unlocking a range of new use cases, including:
- [Build multi-platform images](#build-multi-platform-images) and images with attestations
- Support for using containerd snapshotters with unique characteristics,
such as [stargz][1] for lazy-pulling images on container startup,
or [nydus][2] and [dragonfly][3] for peer-to-peer image distribution.
- Natively store and build multi-platform images, and other OCI content types
that may emerge in the future.
- Ability to run [Wasm](wasm.md) containers
[1]: https://github.com/containerd/stargz-snapshotter
[2]: https://github.com/containerd/nydus-snapshotter
[3]: https://github.com/dragonflyoss/image-service
The image store integration is still at an early stage, so not all features are
yet supported.
## Enable the containerd image store
## Turn on the containerd image store feature
After switching to the containerd image store,
images and containers in the classic image store won't be visible.
All of those containers and images still exist.
To see them again, turn off the containerd image store feature.
The containerd image store isn't turned on by default. To start using the
feature:
The containerd image store isn't enabled by default.
To enable the feature for Docker Desktop:
1. Navigate to **Settings**.
1. Navigate to **Settings** in Docker Desktop.
2. In the **General** tab, check **Use containerd for pulling and storing images**.
3. Select **Apply & Restart**
3. Select **Apply & Restart**.
To turn off this feature, clear the **Use containerd for pulling and storing
images** checkbox.
To disable the containerd image store,
clear the **Use containerd for pulling and storing images** checkbox.
> **Tip**
>
> After switching to the containerd image store, images and containers from the
> default image store won't be visible. All of those containers and images
> still exist. To see them again, turn off the containerd image store feature.
{ .tip }
## Build multi-platform images
## Building multi-platform images
The term multi-platform image refers to a bundle of images that can run on different architectures.
The term multi-platform image refers to a bundle of images for multiple different architectures.
Out of the box, the default builder for Docker Desktop doesn't support building multi-platform images.
```console
$ docker buildx ls | grep "DRIVER\|*"
NAME/NODE DRIVER/ENDPOINT STATUS BUILDKIT PLATFORMS
default * docker
$ docker buildx build --platform=linux/amd64,linux/arm64 .
$ docker build --platform=linux/amd64,linux/arm64 .
[+] Building 0.0s (0/0)
ERROR: multiple platforms feature is currently not supported for docker driver. Please switch to a different driver (eg. "docker buildx create --use")
ERROR: Multi-platform build is not supported for the docker driver.
Switch to a different driver, or turn on the containerd image store, and try again.
Learn more at https://docs.docker.com/go/build-multi-platform/
```
Normally, building multi-platform images requires you to create a new builder,
using a driver that supports multi-platform builds.
But even then, you can't load the multi-platform images to your local image store.
Enabling the containerd image store lets you build multi-platform images
and load them to your local image store:
```console
$ docker buildx create --bootstrap
[+] Building 2.4s (1/1) FINISHED
=> [internal] booting buildkit
=> => pulling image moby/buildkit:buildx-stable-1
=> => creating container buildx_buildkit_objective_blackburn0
objective_blackburn
$ docker buildx build --quiet \
--platform=linux/amd64,linux/arm64 \
--builder=objective_blackburn \
--load .
ERROR: docker exporter does not currently support exporting manifest lists
```
Turning on the containerd image store lets you build, and load, multi-platform images
to your local image store, all while using the default builder.
```console
$ docker info --format="{{ .Driver }}"
stargz
$ docker buildx build \
--platform=linux/arm64,linux/amd64 \
--tag=user/containerd-multiplatform .
[+] Building 6.2s (11/11) FINISHED
...
=> [internal] load build definition from Dockerfile 0.0s
=> => transferring dockerfile: 115B 0.0s
=> [linux/arm64 internal] load metadata for docker.io/library/alpine:latest 2.0s
=> [linux/amd64 internal] load metadata for docker.io/library/alpine:latest 2.1s
=> [linux/amd64 1/1] FROM docker.io/library/alpine@sha256:124c7d2707904e... 0.0s
=> => resolve docker.io/library/alpine@sha256:124c7d2707904eea7431fffe91... 0.0s
=> [linux/arm64 1/1] FROM docker.io/library/alpine@sha256:124c7d2707904e... 0.0s
=> => resolve docker.io/library/alpine@sha256:124c7d2707904eea7431fffe91... 0.0s
=> exporting to image 0.0s
=> => exporting layers 0.0s
...
=> => naming to docker.io/user/containerd-multiplatform:latest 0.0s
=> => unpacking to docker.io/user/containerd-multiplatform:latest 0.0s
$ docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
user/containerd-multiplatform latest 7401bb14c229 14 seconds ago 3.38MB
user/containerd-multiplatform latest 7401bb14c229 14 seconds ago 3.26MB
```
You can push the multi-platform image to Docker Hub.
```console
$ docker push user/containerd-multiplatform
Using default tag: latest
699c4e744ab4: Pushed
878d877e4f70: Pushed
f56be85fc22e: Pushed
a579f49700dc: Pushed
c41833b44d91: Pushed
ee79e74f9211: Pushed
d28bdb47b683: Pushed
```
Inspecting the tag on Docker Hub shows that the image is available for multiple platforms.
![Multiplatform image tag on Docker Hub](images/containerd_multiplatform.png)
## Known issues
### Docker Desktop 4.13.0 release
- Listing images with `docker images` returns the error
`content digest not found` on ARM machines after running or pulling an image
with the `--platform` parameter.
### Docker Desktop 4.12.0 release
- The containerd image store feature requires Buildx version 0.9.0 or newer.
- On Docker Desktop for Linux (DD4L), validate if your locally installed
version meets this requirement.
> **Note**
>
> If you're using an older version, the Docker daemon reports the following
> error:
> `Multiple platforms feature is currently not supported for docker driver.`
> `Please switch to a different driver`.
>
> Install a newer version of Buildx following the instructions on
> [how to manually download Buildx](../../build/architecture.md#install-buildx).
- In Docker Desktop 4.12.0, the containerd image store feature is incompatible
with the Kubernetes cluster support. Turn off the containerd image store
feature if you are using the Kubernetes from Docker Desktop.
- Local registry mirror configuration isn't implemented yet with the containerd
image store. The `registry-mirrors` and `insecure-registries` aren't taken
into account by the Docker daemon.
- The `reference` filter isn't implemented yet and will return the error
`invalid filter 'reference'` when listing images.
- Pulling an image may fail with the error
`pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed`,
in the situation where the image does not contain a manifest list. To
workaround this issue run the `docker login` command and pull the image again.
<script async id="asciicast-ZSUI4Mi2foChLjbevl2dxt5GD" src="https://asciinema.org/a/ZSUI4Mi2foChLjbevl2dxt5GD.js"></script>
## Feedback