Deprecate overlay driver

[bermudezmt]

Problem description

Relates to #7433 @thaJeztah: Thinking we should start deprecating the overlay driver; IIRC, with the Red Hat kernels now supporting overlay2, every supported distro that supports overlay now also supports overlay2, and I cannot think of any reason to use overlay instead of overlay2 for those.

Problem location

• Future updates: storage/storagedriver/index.md

[kolyshkin]

For RHEL

• overlay (but not overlay2) is supported by RHEL 7.1 and 7.2.
• overlay2 is supported since RHEL 7.3.
  Meaning that if we deprecate overlay we deprecate RHEL/CentOS < 7.3

[andrewhsu]

This looks like a good idea to me. cc @mataneja

[mataneja]

RHEL/CentOS < 7.3 are already deprecated. Is there some other OS variant that supports overlay that we still support?

[thaJeztah]

No, this would only be for older debian versions (which we dropped in 18.09).

RHEL, and thus RHEL < 7.3 was only built for Docker EE, which never had overlay in the list of supported storage drivers (it "worked" but was not supported).

[mataneja]

Is there a place where we called out overlay support that now needs to be cleaned up? As in, what does deprecation of overlay actually mean in terms of what needs to to done?

[thaJeztah]

Deprecation means we'll remove it in a future release. We may want to add a "deprecated" warning at the top of the overlay storage driver page (describing that if your system supports overlay, it most likely supports overlay2, and has all the advantages, and none of the negatives of overlay)

[thaJeztah]

Main reason for deprecating things is to give people notice, and a chance to prepare for the feature to be removed. That was also the reason for the introduction of the feature deprecation policy;
https://docs.docker.com/engine/#feature-deprecation-policy (although that originates from the open source maintainers, well before there even was CE/EE)

[mataneja]

@thaJeztah I understand the need for deprecation and am fully supportive of this. I am just curious what steps we need to take in order to accomplish this. From your comments above, it seems that it may simply be a warning on the overlay storage driver page? Can you plz link to it here? Also, is that the extent of the work?

[thaJeztah]

@mataneja From a documentation perspective; yes, I would make sure to;

• Add a deprecation warning on https://github.com/docker/docker.github.io/blob/master/storage/storagedriver/overlayfs-driver.md . There's already a "recomendation" to use overlay2 instead of overlay, so I think that section should be rephrased a bit, and turned into a deprecation warning.
• In a follow up; think about removing the sections that are explaining how the legacy "overlay" driver works (there's a lot of detail about how it uses hardlinks, which is all irrelevant for overlay2)
• Update the "select a storage driver" page; https://github.com/docker/docker.github.io/blob/master/storage/storagedriver/select-storage-driver.md
  • I was already working on a PR to update this page a bit, because it really is outdated, and there are some really bad recomendations in there (such as calling out "vfs" a recommended driver, which it definitely is not)

I would also recommend (if we do a patch release) to include these changes:

• [18.09 backport] deprecate legacy "overlay", and "devicemapper" storage drivers  docker-archive/engine#85 [18.09 backport] deprecate legacy "overlay", and "devicemapper" storage drivers
• [18.09 backport] Skip deprecated storage-drivers in auto-selection docker-archive/engine#90 [18.09 backport] Skip deprecated storage-drivers in auto-selection

Those changes will;

• Add a warning to the output of docker info that notifies the user that they're using a deprecated storage driver
• Skip overlay (and devicemapper) when performing automatic selection of storage-drivers on a fresh install
  • the storage driver can still be used, and will still be used on existing installations (so when upgrading an older engine) but won't be used automatically on a fresh install

[ahh-docker]

@thaJeztah @mataneja I'll take care of this. Do you mind reviewing it when I'm done?

[ahh-docker]

@thaJeztah It looks like there was a PR merged that relates to this. Does it fix this, or is there more work to do? Either way is fine, just lemme know. thanks!

[andrewhsu]

Looks like we still need changes to the docs to complete this issue:

• The storagedriver page should not list overlay as a storage driver to use (but overlay2 is ok) and that overlay is deprecated and will be removed in a future version https://docs.docker.com/storage/storagedriver/
• The overlayfs page should specifically say overlay is deprecated and will be removed in a future version https://docs.docker.com/storage/storagedriver/overlayfs-driver/

[ahh-docker]

Waiting for @mataneja, @mark-church, and @andrewhsu to review.

[docker-robott]

There hasn't been any activity on this issue for a long time.
If the problem is still relevant, mark the issue as fresh with a /remove-lifecycle stale comment.
If not, this issue will be closed in 14 days. This helps our maintainers focus on the active issues.

Prevent issues from auto-closing with a /lifecycle frozen comment.

/lifecycle stale

[thaJeztah]

.

[mat007]

/remove-lifecycle stale
/lifecycle frozen