From d0bd33399aef3a5e9e00a502e2ea73c536edd7a0 Mon Sep 17 00:00:00 2001 From: Nedunchezhiyan-M Date: Fri, 17 Apr 2026 21:01:15 +0530 Subject: [PATCH] engine: remove Vale-flagged meta-commentary in storage driver docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - storage/drivers/_index.md: "it's important to know" → "you need to know" - storage/drivers/aufs-driver.md: "it is worth noting that" removed --- .../manuals/engine/storage/drivers/_index.md | 50 +++++++++---------- .../engine/storage/drivers/aufs-driver.md | 23 ++++----- 2 files changed, 35 insertions(+), 38 deletions(-) diff --git a/content/manuals/engine/storage/drivers/_index.md b/content/manuals/engine/storage/drivers/_index.md index 1bef91efea..3f7a88029f 100644 --- a/content/manuals/engine/storage/drivers/_index.md +++ b/content/manuals/engine/storage/drivers/_index.md @@ -19,7 +19,7 @@ aliases: > implementation details differ. For information about the containerd image > store, see [containerd image store](../containerd.md). -To use storage drivers effectively, it's important to know how Docker builds and +To use storage drivers effectively, you need 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 your applications and avoid performance problems along the way. @@ -180,7 +180,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 @@ -336,7 +336,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. @@ -353,7 +353,7 @@ layers are the same. "sha256:07b4a9068b6af337e8b8f1f1dae3dd14185b2c0003a9a1f0a6fd2587495b204a" ] ``` - + ```console $ docker image inspect --format "{{json .RootFS.Layers}}" acme/my-final-image:1.0 [ @@ -373,7 +373,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 @@ -393,16 +393,16 @@ layer. This means that the writable layer is as small as possible. When an existing file in a container is modified, the storage driver performs a copy-on-write operation. The specific steps involved depend on the specific -storage driver. For the `overlay2` driver, the copy-on-write operation follows +storage driver. For the `overlay2` driver, the copy-on-write operation follows this rough sequence: -* Search through the image layers for the file to update. The process starts - at the newest layer and works down to the base layer one layer at a time. - When results are found, they're added to a cache to speed future operations. -* Perform a `copy_up` operation on the first copy of the file that's found, to - copy the file to the container's writable layer. -* Any modifications are made to this copy of the file, and the container can't - see the read-only copy of the file that exists in the lower layer. +- Search through the image layers for the file to update. The process starts + at the newest layer and works down to the base layer one layer at a time. + When results are found, they're added to a cache to speed future operations. +- Perform a `copy_up` operation on the first copy of the file that's found, to + copy the file to the container's writable layer. +- Any modifications are made to this copy of the file, and the container can't + see the read-only copy of the file that exists in the lower layer. Btrfs, ZFS, and other drivers handle the copy-on-write differently. You can read more about the methods of these drivers later in their detailed @@ -422,7 +422,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 @@ -459,7 +459,6 @@ 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}}" @@ -470,35 +469,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 >}} @@ -512,13 +511,12 @@ 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}}" @@ -545,5 +543,5 @@ driver, a full copy of the image's data is created for each container. ## Related information -* [Volumes](../volumes.md) -* [Select a storage driver](select-storage-driver.md) +- [Volumes](../volumes.md) +- [Select a storage driver](select-storage-driver.md) diff --git a/content/manuals/engine/storage/drivers/aufs-driver.md b/content/manuals/engine/storage/drivers/aufs-driver.md index b966b5530a..2761989cb9 100644 --- a/content/manuals/engine/storage/drivers/aufs-driver.md +++ b/content/manuals/engine/storage/drivers/aufs-driver.md @@ -1,6 +1,6 @@ --- description: Learn how to optimize your use of AUFS driver. -keywords: 'container, storage, driver, AUFS ' +keywords: "container, storage, driver, AUFS " title: AUFS storage driver sitemap: false aliases: @@ -14,7 +14,7 @@ aliases: > before upgrading to Docker Engine v24.0. Read the [Docker storage drivers](select-storage-driver.md) > page for supported storage drivers. -AUFS is a *union filesystem*. The `aufs` storage driver was previously the default +AUFS is a _union filesystem_. The `aufs` storage driver was previously the default storage driver used for managing images and layers on Docker for Ubuntu, and for Debian versions prior to Stretch. If your Linux kernel is version 4.0 or higher, and you use Docker Engine - Community, consider using the newer @@ -26,7 +26,7 @@ potential performance advantages over the `aufs` storage driver. - For Docker Engine - Community, AUFS is supported on Ubuntu, and on Debian versions prior to Stretch. - If you use Ubuntu, you need to add the AUFS module to the kernel. If you do - not install these packages, you need to use `overlay2`. + not install these packages, you need to use `overlay2`. - AUFS cannot use the following backing filesystems: `aufs`, `btrfs`, or `ecryptfs`. This means that the filesystem which contains `/var/lib/docker/aufs` cannot be one of these filesystem types. @@ -66,7 +66,7 @@ storage driver is configured, Docker uses it by default. ## How the `aufs` storage driver works -AUFS is a *union filesystem*, which means that it layers multiple directories on +AUFS is a _union filesystem_, which means that it layers multiple directories on a single Linux host and presents them as a single directory. These directories are called _branches_ in AUFS terminology, and _layers_ in Docker terminology. @@ -74,7 +74,7 @@ The unification process is referred to as a _union mount_. The diagram below shows a Docker container based on the `ubuntu:latest` image. -![Layers of an Ubuntu container](images/aufs_layers.webp) +![Layers of an Ubuntu container](images/aufs_layers.webp) Each image layer, and the container layer, are represented on the Docker host as subdirectories within `/var/lib/docker/`. The union mount provides the unified @@ -126,7 +126,7 @@ If a container is running, the contents of `/var/lib/docker/aufs/` change in the following ways: - `diff/`: Differences introduced in the writable container layer, such as new - or modified files. + or modified files. - `layers/`: Metadata about the writable container layer's parent layers. - `mnt/`: A mount point for each running container's unified filesystem, exactly as it appears from within the container. @@ -160,7 +160,7 @@ Consider some scenarios where files in a container are modified. - **Writing to a file for the first time**: The first time a container writes to an existing file, that file does not exist in the container (`upperdir`). - The `aufs` driver performs a *copy_up* operation to copy the file from the + The `aufs` driver performs a _copy_up_ operation to copy the file from the image layer where it exists to the writable container layer. The container then writes the changes to the new copy of the file in the container layer. @@ -169,13 +169,12 @@ Consider some scenarios where files in a container are modified. very large and only a small part of it is being modified. This can have a noticeable impact on container write performance. AUFS can suffer noticeable latencies when searching for files in images with many layers. - However, it is worth noting that the copy_up operation only occurs the first - time a given file is written to. Subsequent writes to the same file operate - against the copy of the file already copied up to the container. + However, the copy_up operation only occurs the first time a given file is + written to. Subsequent writes to the same file operate against the copy of + the file already copied up to the container. - **Deleting files and directories**: - - - When a _file_ is deleted within a container, a *whiteout* file is created + - When a _file_ is deleted within a container, a _whiteout_ file is created in the container layer. The version of the file in the image layer is not deleted (because the image layers are read-only). However, the whiteout file prevents it from being available to the container.