From a546042b91f655c7cf53484cdb0c5c8b3cf12d33 Mon Sep 17 00:00:00 2001 From: Derek McGowan Date: Mon, 13 Jun 2016 11:06:47 -0700 Subject: [PATCH] Add documentation for using overlay2 Add mention in dockerd command line and storage driver selection documentation. Signed-off-by: Derek McGowan (github: dmcgowan) --- docs/reference/commandline/dockerd.md | 11 ++-- docs/userguide/storagedriver/selectadriver.md | 51 +++++++++++++------ man/dockerd.8.md | 2 +- 3 files changed, 44 insertions(+), 20 deletions(-) diff --git a/docs/reference/commandline/dockerd.md b/docs/reference/commandline/dockerd.md index a170e1c726..b91d0165a9 100644 --- a/docs/reference/commandline/dockerd.md +++ b/docs/reference/commandline/dockerd.md @@ -142,7 +142,7 @@ precedence over `HTTP_PROXY`. ### Daemon storage-driver option The Docker daemon has support for several different image layer storage -drivers: `aufs`, `devicemapper`, `btrfs`, `zfs` and `overlay`. +drivers: `aufs`, `devicemapper`, `btrfs`, `zfs`, `overlay` and `overlay2`. The `aufs` driver is the oldest, but is based on a Linux kernel patch-set that is unlikely to be merged into the main kernel. These are also known to cause @@ -180,9 +180,14 @@ Linux kernel as of [3.18.0](https://lkml.org/lkml/2014/10/26/137). Call > inode consumption (especially as the number of images grows), as well as > being incompatible with the use of RPMs. +The `overlay2` uses the same fast union filesystem but takes advantage of +[additional features](https://lkml.org/lkml/2015/2/11/106) added in Linux +kernel 4.0 to avoid excessive inode consumption. Call `dockerd -s overlay2` +to use it. + > **Note:** -> It is currently unsupported on `btrfs` or any Copy on Write filesystem -> and should only be used over `ext4` partitions. +> Both `overlay` and `overlay2` are currently unsupported on `btrfs` or any +> Copy on Write filesystem and should only be used over `ext4` partitions. ### Storage driver options diff --git a/docs/userguide/storagedriver/selectadriver.md b/docs/userguide/storagedriver/selectadriver.md index f34e5e8dbf..baa7238a33 100644 --- a/docs/userguide/storagedriver/selectadriver.md +++ b/docs/userguide/storagedriver/selectadriver.md @@ -34,14 +34,14 @@ and all containers created by that daemon instance use the same storage driver. The table below shows the supported storage driver technologies and their driver names: -|Technology |Storage driver name | -|--------------|---------------------| -|OverlayFS |`overlay` | -|AUFS |`aufs` | -|Btrfs |`btrfs` | -|Device Mapper |`devicemapper` | -|VFS |`vfs` | -|ZFS |`zfs` | +|Technology |Storage driver name | +|--------------|-----------------------| +|OverlayFS |`overlay` or `overlay2`| +|AUFS |`aufs` | +|Btrfs |`btrfs` | +|Device Mapper |`devicemapper` | +|VFS |`vfs` | +|ZFS |`zfs` | To find out which storage driver is set on the daemon, you use the `docker info` command: @@ -71,14 +71,15 @@ For example, the `btrfs` storage driver on a Btrfs backing filesystem. The following table lists each storage driver and whether it must match the host's backing file system: -|Storage driver |Commonly used on |Disabled on | -|---------------|-----------------|-----------------------------------------| -|`overlay` |`ext4` `xfs` |`btrfs` `aufs` `overlay` `zfs` `eCryptfs`| -|`aufs` |`ext4` `xfs` |`btrfs` `aufs` `eCryptfs` | -|`btrfs` |`btrfs` _only_ | N/A | -|`devicemapper` |`direct-lvm` | N/A | -|`vfs` |debugging only | N/A | -|`zfs` |`zfs` _only_ | N/A | +|Storage driver |Commonly used on |Disabled on | +|---------------|-----------------|----------------------------------------------------| +|`overlay` |`ext4` `xfs` |`btrfs` `aufs` `overlay` `overlay2` `zfs` `eCryptfs`| +|`overlay2` |`ext4` `xfs` |`btrfs` `aufs` `overlay` `overlay2` `zfs` `eCryptfs`| +|`aufs` |`ext4` `xfs` |`btrfs` `aufs` `eCryptfs` | +|`btrfs` |`btrfs` _only_ | N/A | +|`devicemapper` |`direct-lvm` | N/A | +|`vfs` |debugging only | N/A | +|`zfs` |`zfs` _only_ | N/A | > **Note** @@ -198,6 +199,24 @@ the guidance offered by the table below along with the points mentioned above. ![](images/driver-pros-cons.png) +### Overlay vs Overlay2 + +OverlayFS has 2 storage drivers which both make use of the same OverlayFS +technology but with different implementations and incompatible on disk +storage. Since the storage is incompatible, switching between the two +will require re-creating all image content. The `overlay` driver is the +original implementation and the only option in Docker 1.11 and before. +The `overlay` driver has known limitations with inode exhaustion and +commit performance. The `overlay2` driver addresses this limitation, but +is only compatible with Linux kernel 4.0 and later. For users on a pre-4.0 +kernel or with an existing `overlay` graph, it is recommended to stay +on `overlay`. For users with at least a 4.0 kernel and no existing or required +`overlay` graph data, then `overlay2` may be used. + +> **Note** +> `overlay2` graph data will not interfere with `overlay` graph data. However +> when switching to `overlay2`, the user is responsible for removing +> `overlay` graph data to avoid storage duplication. ## Related information diff --git a/man/dockerd.8.md b/man/dockerd.8.md index 9f980310e4..6fa985913c 100644 --- a/man/dockerd.8.md +++ b/man/dockerd.8.md @@ -226,7 +226,7 @@ output otherwise. Force the Docker runtime to use a specific storage driver. **--selinux-enabled**=*true*|*false* - Enable selinux support. Default is false. SELinux does not presently support the overlay storage driver. + Enable selinux support. Default is false. SELinux does not presently support either of the overlay storage drivers. **--storage-opt**=[] Set storage driver options. See STORAGE DRIVER OPTIONS.