Clarify overlay2 support in Docker EE RHEL / CentOS (#5817)

install/linux/docker-ee/centos.md

@@ -28,17 +28,27 @@ Docker CE users should go to
 
 ### OS requirements
 
-To install Docker EE, you need a maintained version of CentOS 7. Archived
-versions aren't supported or tested.
+To install Docker EE, you need the 64-bit version of {{ linux-dist-long }}
+running on `x86_64`.
 
-The `centos-extras` repository must be enabled. This repository is enabled by
-default, but if you have disabled it, you need to
-[re-enable it](https://wiki.centos.org/AdditionalResources/Repositories){: target="_blank" class="_" }.
+In addition, you must use the `overlay2` or `devicemapper` storage driver.
+Beginning with Docker EE 17.06.2-ee-5 the `overlay2` storage driver is the
+recommended storage driver.
 
-In addition, you must use the `overlay2` or `devicemapper` storage driver if you
-use Docker EE. On production systems using `devicemapper`, you must use
-`direct-lvm` mode, which requires one or more dedicated block devices. Fast
-storage such as solid-state media (SSD) is recommended.
+The following limitations apply:
+
+**OverlayFS**:
+
+- The `overlay2` storage driver is only supported on CentOS 7 systems
+  using version 3.10.0-693 or high of the kernel.
+- If `selinux` is enabled, the `overlay2` storage driver is only supported on
+  RHEL 7.4 or higher.
+
+**Devicemapper**:
+
+- On production systems using `devicemapper`, you must use `direct-lvm` mode,
+  which requires one or more dedicated block devices. Fast storage such as
+  solid-state media (SSD) is recommended.
 
 ### Uninstall old versions
 

install/linux/docker-ee/rhel.md

@@ -39,7 +39,8 @@ The following limitations apply:
 
 **OverlayFS**:
 
-- The `overlay2` storage driver is only supported on RHEL 7.2 or higher.
+- The `overlay2` storage driver is only supported on RHEL 7.2 or higher systems
+  using version 3.10.0-693 or high of the kernel.
 - If `selinux` is enabled, the `overlay2` storage driver is only supported on
   RHEL 7.4 or higher.
 

storage/storagedriver/overlayfs-driver.md

@@ -15,7 +15,9 @@ storage driver as `overlay` or `overlay2`.
 
 > **Note**: If you use OverlayFS, use the `overlay2` driver rather than the
 > `overlay` driver, because it is more efficient in terms of inode utilization.
-> To use the new driver, you need version 4.0 or higher of the Linux kernel.
+> To use the new driver, you need version 4.0 or higher of the Linux kernel,
+> unless you are a Docker EE user on RHEL or CentOS, in which case you need
+> version 3.10.0-693 or higher of the kernel and to follow some extra steps.
 >
 > For more information about differences between `overlay` vs `overlay2`, refer
 > to [Select a storage driver](selectadriver.md#overlay-vs-overlay2).
@@ -29,8 +31,11 @@ OverlayFS is supported if you meet the following prerequisites:
 
 - The `overlay` driver is allowed but not recommended for Docker CE.
 
-- Version 4.0 or higher of the Linux kernel. If you use an older kernel, you
-  need to use the `overlay` driver, which is not recommended.
+- Version 4.0 or higher of the Linux kernel, or RHEL or CentOS using
+  version 3.10.0-693 of the kernel or higher. Docker EE users using kernels older
+  than 4.0 need to follow some extra steps, outlined below.
+  If you use an older kernel, you need to use the `overlay` driver, which is not
+  recommended.
 
 - The following backing filesystems are supported:
   - `ext4` (RHEL 7.1 only)
@@ -38,6 +43,13 @@ OverlayFS is supported if you meet the following prerequisites:
     `xfs_info` to verify that the `ftype` option is set to `1`. To format an
     `xfs` filesystem correctly, use the flag `-n ftype=1`.
 
+    > **Warning**: Running on XFS without d_type support inow canses Docker to
+    > skip the attempt to use the `overlay` or `overlay2` driver. Existing
+    > installs will continue to run, but produce an error. This is to allow
+    > users o migrate their data. In a future version, this will be a fatal
+    > error, which will prevent Docker from starting.
+    {:.warning}
+
 - Changing the storage driver makes any containers you have already
   created inaccessible on the local system. Use `docker save` to save containers,
   and push existing images to Docker Hub or a private repository, so that you
@@ -84,22 +96,27 @@ Before following this procedure, you must first meet all the
     }
     ```
 
+    > **Note**: RHEL and CentOS users on Docker EE 17.06
+    >
+    > You need to add a second option to the `daemon.json` to disable the check
+    > for version 4.0 or higher of the Linux kernel. Your `daemon.json` should
+    > look like the following. **This is only needed for Docker EE users of RHEL
+    > or CentOS.** Do not attempt to use `overlay2` with kernel versions older
+    > than 3.10.0-693.
+    >
+    > ```json
+    > {
+    >   "storage-driver": "overlay2",
+    >   "storage-opts": [
+    >     "overlay2.override_kernel_check=true"
+    >   ]
+    > }
+    > ```
+
     If you need to use the legacy `overlay` driver, specify it instead.
 
-    To use `overlay2` on CentOS (Docker CE only), you must also set the storage
-    option `overlay2.override_kernel_check`. In this case the `daemon.json`
-    would look like this:
-
-    ```json
-    {
-      "storage-driver": "overlay2",
-      "storage-opts": [
-        "overlay2.override_kernel_check=true"
-      ]
-    }
-    ```
-
-    See all storage options for each storage driver:
+    More storage options are available. See all storage options for each storage
+    driver:
 
     - [Stable](/engine/reference/commandline/dockerd.md#storage-driver-options)
     - [Edge](/edge/engine/reference/commandline/dockerd.md#storage-driver-options)