diff --git a/.vscode/docker.code-snippets b/.vscode/docker.code-snippets index 3be817d524d..8d86bc0fd7f 100644 --- a/.vscode/docker.code-snippets +++ b/.vscode/docker.code-snippets @@ -54,4 +54,27 @@ "body": ["{{< button url=\"$1\" text=\"$2\" >}}"], "description": "Insert a Hugo button", }, + "Insert a Summary Bar": { + "prefix": ["summary-bar"], + "body": [ + "{{< summary-bar feature_name=\"$1\" >}}", + "", + "$2", + ], + "description": "Insert a Hugo summary bar with a feature name and content. Define your summary key in data/summary.yaml.", + }, + "Insert Title": { + "prefix": ["insert title", "frontmatter", "title"], + "body": [ + "---", + "title: $1", + "weight: $2", + "description: $3", + "keywords: $4", + "aliases:", + " - $5", + "---" + ], + "description": "Insert a frontmatter block with title, weight, description, keywords, and aliases." + } } \ No newline at end of file diff --git a/_vale/config/vocabularies/Docker/accept.txt b/_vale/config/vocabularies/Docker/accept.txt index 8fde615fd50..412c1dd0472 100644 --- a/_vale/config/vocabularies/Docker/accept.txt +++ b/_vale/config/vocabularies/Docker/accept.txt @@ -149,6 +149,7 @@ Qualcomm Quickview rebalance reimplement +repull rollback rootful runc @@ -157,7 +158,6 @@ S3 scrollable SELinux Slack -snapshotters? Snyk Solr SonarQube @@ -239,6 +239,7 @@ Zsh [Rr]untimes? [Ss]andbox(ed)? [Ss]eccomp +[sS]napshotters? [Ss]ubmounts? [Ss]ubnet [Ss]ubpaths? diff --git a/assets/css/components.css b/assets/css/components.css index 1e3f897903f..d98f3f224fc 100644 --- a/assets/css/components.css +++ b/assets/css/components.css @@ -101,6 +101,9 @@ .summary-bar { @apply my-1 mt-4 flex flex-col rounded-sm border-1 border-gray-100 bg-gray-50 p-4 dark:border-gray-800 dark:bg-gray-900; } +.summary-bar:has(.deprecated) { + @apply bg-red-100 dark:bg-red-950; +} .tabs { @apply bg-blue/2 rounded-sm p-2; diff --git a/content/manuals/admin/company/owners.md b/content/manuals/admin/company/owners.md index c3afa9a6510..9079e50d4dd 100644 --- a/content/manuals/admin/company/owners.md +++ b/content/manuals/admin/company/owners.md @@ -13,6 +13,7 @@ entire company and can manage settings that apply to all organizations under that company. They also have the same access rights as organization owners but don’t need to be members of any individual organization. + > [!IMPORTANT] > > Company owners do not occupy a seat unless one of the following is true: diff --git a/content/manuals/engine/storage/_index.md b/content/manuals/engine/storage/_index.md index d616e302867..9c8899791c7 100644 --- a/content/manuals/engine/storage/_index.md +++ b/content/manuals/engine/storage/_index.md @@ -18,6 +18,17 @@ container if another process needs it. The writable layer is unique per container. You can't easily extract the data from the writeable layer to the host, or to another container. +> [!IMPORTANT] +> Starting with Docker Engine v29, Docker uses +> [containerd](./containerd.md) for managing container storage and images. + +## Image storage + +Docker offers two implementation of image storage: + +- Default/current implementation: [Containerd](./containerd.md) +- Legacy/deprecated implementation: [Storage drivers](./drivers/_index.md) + ## Storage mount options Docker supports the following types of storage mounts for storing data outside diff --git a/content/manuals/engine/storage/containerd.md b/content/manuals/engine/storage/containerd.md index 00ceed979dd..bfb18924ea0 100644 --- a/content/manuals/engine/storage/containerd.md +++ b/content/manuals/engine/storage/containerd.md @@ -8,24 +8,49 @@ aliases: - /storage/containerd/ --- -{{< summary-bar feature_name="containerd" >}} +Starting with Docker Engine v29, Docker uses [`containerd`](https://containerd.io/) +for managing container storage and images. `containerd` is the industry-standard container runtime. -containerd, the industry-standard container runtime, uses snapshotters instead -of the classic storage drivers for storing image and container data. -While the `overlay2` driver still remains the default driver for Docker Engine, -you can opt in to using containerd snapshotters as an experimental feature. +## Main benefits -To learn more about the containerd image store and its benefits, refer to +containerd offers the following benefits: + +- Shared maintenance: containerd is an open-source project maintained by a large community. +- Customizability: use [snapshotters](snapshotters.md) + with unique characteristics, such as: + - [stargz](https://github.com/containerd/stargz-snapshotter) for lazy-pulling images on container + startup. + - [nydus](https://github.com/containerd/nydus-snapshotter) or [dragonfly](https://github.com/dragonflyoss/nydus) for peer-to-peer image distribution. +- Portability: containerd is lighter and more modular. +- Multi-platform support: Build multi-platform images and images with attestations. +- WebAssembly: Ability to run Wasm containers. + +For more information about the containerd image store and its benefits, refer to [containerd image store on Docker Desktop](/manuals/desktop/features/containerd.md). -## Enable containerd image store on Docker Engine +## Migrate to containerd image store on Docker Engine + +When you update to Docker Engine v29 and enable the containerd feature, you are +automatically migrated. The migration mechanism handles overlay and vfs images. Switching to containerd snapshotters causes you to temporarily lose images and -containers created using the classic storage drivers. -Those resources still exist on your filesystem, and you can retrieve them by -turning off the containerd snapshotters feature. +containers created using the classic storage drivers. If you use other graph storage, repull or rebuild your images. + +> [!TIP] +> Those resources still exist on your filesystem, and you can retrieve them by +> turning off the containerd snapshotters feature. + +Docker Engine uses the `overlayfs` containerd snapshotter by default. + +To display which driver you are using, run: + +```console +$ docker info -f '{{ .DriverStatus }}' +``` + +## Disabling containerd image store -The following steps explain how to enable the containerd snapshotters feature. +The following steps explain how to disable the containerd snapshotters feature. 1. Add the following configuration to your `/etc/docker/daemon.json` configuration file: @@ -33,24 +58,21 @@ The following steps explain how to enable the containerd snapshotters feature. ```json { "features": { - "containerd-snapshotter": true + "containerd-snapshotter": false } } ``` 2. Save the file. + 3. Restart the daemon for the changes to take effect. ```console $ sudo systemctl restart docker ``` -After restarting the daemon, running `docker info` shows that you're using -containerd snapshotter storage drivers. - -```console -$ docker info -f '{{ .DriverStatus }}' -[[driver-type io.containerd.snapshotter.v1]] -``` +4. Verify which driver you are using: -Docker Engine uses the `overlayfs` containerd snapshotter by default. + ```console + $ docker info -f '{{ .DriverStatus }}' + ``` diff --git a/content/manuals/engine/storage/drivers/_index.md b/content/manuals/engine/storage/drivers/_index.md index c6241730936..af6c22f65b0 100644 --- a/content/manuals/engine/storage/drivers/_index.md +++ b/content/manuals/engine/storage/drivers/_index.md @@ -2,13 +2,15 @@ description: Learn the technologies that support storage drivers. keywords: container, storage, driver, btrfs, overlayfs, vfs, zfs title: Storage drivers -weight: 40 aliases: - /storage/storagedriver/imagesandcontainers/ - /storage/storagedriver/ - /engine/userguide/storagedriver/imagesandcontainers/ --- +{{< summary-bar feature_name="StorageDrivers" +text="Use [containerd](../containerd.md) instead.">}} + To use storage drivers effectively, it's important to know how Docker builds and stores images, and how these images are used by containers. You can use this information to make informed choices about the best way to persist data from @@ -170,7 +172,7 @@ docker.io/library/ubuntu:22.04 Each of these layers is stored in its own directory inside the Docker host's local storage area. To examine the layers on the filesystem, list the contents -of `/var/lib/docker/`. This example uses the `overlay2` +of `/var/lib/docker/`. This example uses the `overlay2` storage driver: ```console @@ -326,7 +328,7 @@ layers are the same. Before BuildKit, the "classic" builder would produce a new "intermediate" image for each step for caching purposes, and the `IMAGE` column would show the ID of that image. - + BuildKit uses its own caching mechanism, and no longer requires intermediate images for caching. Refer to [BuildKit](/manuals/build/buildkit/_index.md) to learn more about other enhancements made in BuildKit. @@ -343,7 +345,7 @@ layers are the same. "sha256:07b4a9068b6af337e8b8f1f1dae3dd14185b2c0003a9a1f0a6fd2587495b204a" ] ``` - + ```console $ docker image inspect --format "{{json .RootFS.Layers}}" acme/my-final-image:1.0 [ @@ -363,7 +365,7 @@ layers are the same. > [!TIP] > > Format output of Docker commands with the `--format` option. - > + > > The examples above use the `docker image inspect` command with the `--format` > option to view the layer IDs, formatted as a JSON array. The `--format` > option on Docker commands can be a powerful feature that allows you to @@ -412,7 +414,7 @@ in a `copy_up` operation, therefore duplicating the file to the writable layer. > applications, for example write-intensive databases, are known to be > problematic particularly when pre-existing data exists in the read-only > layer. -> +> > Instead, use Docker volumes, which are independent of the running container, > and designed to be efficient for I/O. In addition, volumes can be shared > among containers and don't increase the size of your container's writable @@ -449,7 +451,7 @@ examines how much room they take up. 2. Run the `docker ps` command with the `--size` option to verify the 5 containers are running, and to see each container's size. - + ```console $ docker ps --size --format "table {{.ID}}\t{{.Image}}\t{{.Names}}\t{{.Size}}" @@ -460,35 +462,35 @@ examines how much room they take up. a5ff32e2b551 acme/my-final-image:1.0 my_container_2 0B (virtual 7.75MB) 40ebdd763416 acme/my-final-image:1.0 my_container_1 0B (virtual 7.75MB) ``` - + The output above shows that all containers share the image's read-only layers (7.75MB), but no data was written to the container's filesystem, so no additional storage is used for the containers. {{< accordion title="Advanced: metadata and logs storage used for containers" >}} - + > [!NOTE] > > This step requires a Linux machine, and doesn't work on Docker Desktop, as > it requires access to the Docker Daemon's file storage. - + While the output of `docker ps` provides you information about disk space consumed by a container's writable layer, it doesn't include information about metadata and log-files stored for each container. - + More details can be obtained by exploring the Docker Daemon's storage location (`/var/lib/docker` by default). - + ```console $ sudo du -sh /var/lib/docker/containers/* - + 36K /var/lib/docker/containers/3ed3c1a10430e09f253704116965b01ca920202d52f3bf381fbb833b8ae356bc 36K /var/lib/docker/containers/40ebdd7634162eb42bdb1ba76a395095527e9c0aa40348e6c325bd0aa289423c 36K /var/lib/docker/containers/939b3bf9e7ece24bcffec57d974c939da2bdcc6a5077b5459c897c1e2fa37a39 36K /var/lib/docker/containers/a5ff32e2b551168b9498870faf16c9cd0af820edf8a5c157f7b80da59d01a107 36K /var/lib/docker/containers/cddae31c314fbab3f7eabeb9b26733838187abc9a2ed53f97bd5b04cd7984a5a ``` - + Each of these containers only takes up 36k of space on the filesystem. {{< /accordion >}} @@ -502,13 +504,13 @@ examines how much room they take up. ```console $ for i in {1..3}; do docker exec my_container_$i sh -c 'printf hello > /out.txt'; done ``` - + Running the `docker ps` command again afterward shows that those containers now consume 5 bytes each. This data is unique to each container, and not shared. The read-only layers of the containers aren't affected, and are still shared by all containers. - + ```console $ docker ps --size --format "table {{.ID}}\t{{.Image}}\t{{.Names}}\t{{.Size}}" diff --git a/content/manuals/engine/storage/snapshotters.md b/content/manuals/engine/storage/snapshotters.md new file mode 100644 index 00000000000..aa480e7446f --- /dev/null +++ b/content/manuals/engine/storage/snapshotters.md @@ -0,0 +1,25 @@ +--- +title: containerd snapshotters +description: Learn how to use containerd snapshotters in Docker Engine. +keywords: containerd, snapshotters, storage, overlayfs, fuse, docker, engine, filesystem, performance +--- + +containerd snapshotters are components responsible for managing the filesystem +layers of containers. They provide the mechanism for storing, mounting, and +manipulating container filesystems using different backends such as overlayfs or +fuse. + +By abstracting the storage implementation, snapshotters allow Docker Engine to +efficiently manage container images and their writable layers, enabling features +like fast image pulls, efficient storage usage, and support for advanced +filesystems. + +For more information, see +the [containerd repository](https://github.com/containerd/containerd/tree/main/docs/snapshotters). + +| Snapshotter | Description | +|-----------------------|----------------------------------------------------------------------------------------| +| `overlayfs` (default) | OverlayFS. The containerd implementation of the Docker/Moby `overlay2` storage driver. | +| `native` | Native file copying driver. Akin to Docker/Moby's "vfs" driver. | + + diff --git a/data/summary.yaml b/data/summary.yaml index b7d498eb232..3a423d7f95b 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -133,8 +133,6 @@ Composefile include: requires: Docker Compose [2.20.0](/manuals/compose/releases/release-notes.md#2200) and later Compose sbom: requires: Docker Compose [2.39.0](/manuals/compose/releases/release-notes.md#2390) and later -containerd: - availability: Experimental Dev Environments: availability: Beta Docker Build Cloud: @@ -250,3 +248,5 @@ Wasm workloads: availability: Beta Wasmtime: availability: Experimental +StorageDrivers: + availability: Deprecated diff --git a/hugo_stats.json b/hugo_stats.json index a87826249e0..c166c5aca8f 100644 --- a/hugo_stats.json +++ b/hugo_stats.json @@ -148,6 +148,7 @@ "Without-systemd", "[display:none]", "absolute", + "access", "admonition", "admonition-content", "admonition-danger", @@ -159,6 +160,7 @@ "admonition-warning", "aspect-video", "bake-action", + "beta", "bg-amber-500", "bg-background-toc", "bg-black/100", @@ -268,6 +270,7 @@ "dark:text-magenta-dark", "dark:text-white", "dark:to-blue-400", + "deprecated", "docker/bake-action", "docker/build-push-action", "download-links", @@ -275,6 +278,8 @@ "drop-shadow", "dropdown-base", "duration-300", + "early", + "experimental", "fill-blue", "fixed", "flex", diff --git a/layouts/shortcodes/summary-bar.html b/layouts/shortcodes/summary-bar.html index 172f81c6196..b694c484722 100644 --- a/layouts/shortcodes/summary-bar.html +++ b/layouts/shortcodes/summary-bar.html @@ -1,4 +1,5 @@ {{ $featureName := .Get "feature_name" }} +{{ $text := .Get "text" }} {{ $feature := index site.Data.summary $featureName }} {{ if not $feature }} {{ errorf "[summary-bar] invalid feature: %s %v" $featureName .Position }} @@ -18,6 +19,7 @@ "Early Access" "rocket_launch" "GA" "check_circle" "Retired" "package_2" + "Deprecated" "warning" }} {{ $requiresIcon := "browser_updated" }} {{ $forIcon := "admin_panel_settings" }} @@ -30,7 +32,6 @@
Subscription: {{ range . }} - {{ . }} {{ $icon := index $subscriptionIcons . }} {{ if $icon }} @@ -39,44 +40,52 @@ {{ partial "icon" "default_icon" }} {{ end }} + {{ . }} {{ end }}
{{ end }} {{ with $feature.availability }} {{ $availabilityText := . }} -
+
+ {{ range $key, $icon := $availabilityIcons }} + {{ if in $availabilityText $key }} + {{ partial "icon" $icon }} + {{ end }} + {{ end }} Availability: {{ $availabilityText }} - {{ range $key, $icon := $availabilityIcons }} - {{ if in $availabilityText $key }} - {{ partial "icon" $icon }} - {{ end }} - {{ end }} +
+ + {{- if $text -}} + . {{ $text | markdownify }} + {{- end -}} + +
{{ end }} {{ with $feature.requires }}
- Requires: - {{ . | markdownify }} {{ partial "icon" $requiresIcon }} + Requires: + {{ . | markdownify }}
{{ end }} {{ with $feature.for }}
- For: - {{ . }} {{ if eq . "Administrators" }} {{ partial "icon" $forIcon }} {{ end }} + For: + {{ . }}
{{ end }}