deprecate old API versions (1.23 and lower) by thaJeztah · Pull Request #4796 · docker/cli

thaJeztah · 2024-01-16T15:33:19Z

The Docker Daemon provides a versioned API for backward compatibility with old clients. When a client connects, it can perform API-version negotiation to select the most recent API version supported by the daemon (downgrading to and older version of the API when necessary). API version negotiation was introduced in Docker v1.12.0 (API 1.24), and clients before that used a fixed API version.

Docker Engine up until v25.0 provide support for all API versions included in stable releases for a given platform. For Linux daemons, the oldest supported API version is 1.12 (corresponding with Docker Engine v1.0.0), whereas for Windows Daemons, the oldest supported API version is 1.24 (corresponding with Docker Engine v1.12.0).

Support for legacy API versions (providing old API versions on current versions of the Docker Engine) is primarily intended to provide compatibility with recent, but still supported versions of the client, which is a common scenario (the Docker Daemon may be updated to the latest release, but not all clients may be up-to-date or vice versa). Support for API versions before that (API versions provided by EOL versions of the Docker Daemon) is provided on a "best effort" base.

Use of old API versions is very rare, and support for legacy API versions involves significant complexity (Docker 1.0.0 was released 10 Years ago). Because of this, we'll start deprecating support for legacy API versions.

Docker Engine v25.0 by default disables API version older than 1.24 (aligning the minimum supported API version between Linux and Windows daemons). When connecting with a client that uses an API version version older than 1.24, the daemon returns an error. The following example configures the docker CLI to use API version 1.23, which produces an error:

DOCKER_API_VERSION=1.23 docker version
Error response from daemon: client version 1.23 is too old. Minimum supported API version is 1.24, please upgrade your client to a newer version

An environment variable (DOCKER_MIN_API_VERSION) is introduced that allows re-enabling older API versions in the daemon. This environment-variable must be set in the daemon's environment (for example, through a systemd override file), and the specified API version must be supported by the daemon (1.12 or higher on Linux, or 1.24 or higher on Windows).

Support for API versions lower than 1.24 will be permanently removed in Docker Engine v26, and the minimum supported API version will be incrementally raised in releases following that.

We do not recommend depending on the DOCKER_MIN_API_VERSION environment variable other than for exceptional cases where it's not possible to update old clients, and those clients must be supported.

- What I did

- How I did it

- How to verify it

- Description for the changelog

- A picture of a cute animal (not mandatory but encouraged)

codecov-commenter · 2024-01-16T15:35:22Z

Codecov Report

Merging #4796 (9791b23) into master (a18dad3) will not change coverage.
The diff coverage is n/a.

Additional details and impacted files

@@           Coverage Diff           @@
##           master    #4796   +/-   ##
=======================================
  Coverage   59.61%   59.61%           
=======================================
  Files         288      288           
  Lines       24785    24785           
=======================================
  Hits        14775    14775           
  Misses       9122     9122           
  Partials      888      888

thaJeztah · 2024-01-16T15:39:00Z

docs/deprecated.md

+Error response from daemon: client version 1.23 is too old. Minimum supported API version is 1.24, please upgrade your client to a newer version
+```
+
+An environment variable (`DOCKER_MIN_API_VERSION`) is introduced that allows


FWIW, I decided to not (yet?) document this env-var in the dockerd reference; https://docs.docker.com/engine/reference/commandline/dockerd/#environment-variables

My motivation;

This is not a recommended env-var

We could add a separate table "for debugging purposes" (or similar) to better separate "ok to use" and "not recommended, other than exceptional cases" env-vars

☝️ while looking at that, I also discovered various other undocumented or (almost not documented) env-vars, such as DEBUG, DOCKER_WINDOWSFILTER_NOREEXEC, DOCKER_CLI_PLUGIN_USE_DIAL_STDIO, ROOTLESSKIT_STATE_DIR), some of which are for the "daeemon", some for the "cli", and some are intentionally un-documented (intended for use in CI, e.g.), so we need to collect all of those, and decide whether to document them, and "how".

ugh. We really need to do an inventory of all env vars and ensure they are properly and consistently prefixed with a namespace e.g. DOCKER_.

ROOTLESSKIT_STATE_DIR
vs
DOCKERD_ROOTLESS_ROOTLESSKIT_NET

(nothing wrong with DOCKER_MIN_API_VERSION, this is just a drive-by complaint)

I think the ROOTLESSKIT one may be because the library we're using defined it, but yes; leaning toward documenting all of them even if they should NOT be used (but doing so gives us a clear way to tell users "don't use this!")

Technically ROOTLESSKIT is because it's a "third party" (read: re-used in multiple places) codebase being configured, and the uniformity makes sense (especially when you consider it is an external binary that multiple packages may re-use).

Yup, and there will be more env-vars like that (only think of OTEL, or AWS env-vars consumed by their SDK / logging-drivers, etc).

This was just a 2-second grep for os.GetEnv in our code

neersighted · 2024-01-16T15:49:43Z

docs/deprecated.md

+introduced in Docker v1.12.0 (API 1.24), and clients before that used a fixed
+API version.
+
+Docker Engine up until v25.0 provide support for all [API versions](https://docs.docker.com/engine/api/#api-version-matrix)


Suggested change

Docker Engine up until v25.0 provide support for all [API versions](https://docs.docker.com/engine/api/#api-version-matrix)

Docker Engine versions through v25.0 provide support for all [API versions](https://docs.docker.com/engine/api/#api-version-matrix)

neersighted · 2024-01-16T15:50:00Z

docs/deprecated.md

+but still supported versions of the client, which is a common scenario (the Docker
+Daemon may be updated to the latest release, but not all clients may be up-to-date
+or vice versa). Support for API versions before that (API versions provided by EOL
+versions of the Docker Daemon) is provided on a "best effort" base.


Suggested change

versions of the Docker Daemon) is provided on a "best effort" base.

versions of the Docker Daemon) is provided on a "best effort" basis.

neersighted · 2024-01-16T15:50:15Z

docs/deprecated.md

+versions of the Docker Daemon) is provided on a "best effort" base.
+
+Use of old API versions is very rare, and support for legacy API versions
+involves significant complexity (Docker 1.0.0 was released 10 Years ago).


Suggested change

involves significant complexity (Docker 1.0.0 was released 10 Years ago).

involves significant complexity (Docker 1.0.0 having been released 10 years ago).

neersighted · 2024-01-16T15:51:44Z

docs/deprecated.md

+```
+
+An environment variable (`DOCKER_MIN_API_VERSION`) is introduced that allows
+re-enabling older API versions in the daemon. This environment-variable must


Suggested change

re-enabling older API versions in the daemon. This environment-variable must

re-enabling older API versions in the daemon. This environment variable must

dvdksn · 2024-01-16T15:53:59Z

docs/deprecated.md

+**Deprecated in Release: v25.0**
+**Target For Removal In Release: v26.0**
+
+The Docker Daemon provides a versioned API for backward compatibility with old


Suggested change

The Docker Daemon provides a versioned API for backward compatibility with old

The Docker daemon provides a versioned API for backward compatibility with old

dvdksn · 2024-01-16T15:54:21Z

docs/deprecated.md

+**Target For Removal In Release: v26.0**
+
+The Docker Daemon provides a versioned API for backward compatibility with old
+clients. When a client connects, it can perform API-version negotiation to


Suggested change

clients. When a client connects, it can perform API-version negotiation to

clients. Docker clients can perform API-version negotiation to

dvdksn · 2024-01-16T15:56:22Z

docs/deprecated.md

+API version.
+
+Docker Engine up until v25.0 provide support for all [API versions](https://docs.docker.com/engine/api/#api-version-matrix)
+included in stable releases for a given platform. For Linux daemons, the oldest


https://docs.docker.com/contribute/style/recommended-words/#earlier

Suggested change

included in stable releases for a given platform. For Linux daemons, the oldest

included in stable releases for a given platform. For Linux daemons, the earliest

dvdksn · 2024-01-16T15:56:32Z

docs/deprecated.md

+Docker Engine up until v25.0 provide support for all [API versions](https://docs.docker.com/engine/api/#api-version-matrix)
+included in stable releases for a given platform. For Linux daemons, the oldest
+supported API version is 1.12 (corresponding with Docker Engine v1.0.0), whereas
+for Windows Daemons, the oldest supported API version is 1.24 (corresponding


Suggested change

for Windows Daemons, the oldest supported API version is 1.24 (corresponding

for Windows Daemons, the earliest supported API version is 1.24 (corresponding

dvdksn · 2024-01-16T15:58:39Z

docs/deprecated.md

+Support for legacy API versions (providing old API versions on current versions
+of the Docker Engine) is primarily intended to provide compatibility with recent,
+but still supported versions of the client, which is a common scenario (the Docker
+Daemon may be updated to the latest release, but not all clients may be up-to-date


Suggested change

Daemon may be updated to the latest release, but not all clients may be up-to-date

daemon may be updated to the latest release, but not all clients may be up-to-date

The Docker daemon provides a versioned API for backward compatibility with old clients. Docker clients can perform API-version negotiation to select the most recent API version supported by the daemon (downgrading to and older version of the API when necessary). API version negotiation was introduced in Docker v1.12.0 (API 1.24), and clients before that used a fixed API version. Docker Engine versions through v25.0 provide support for all [API versions](https://docs.docker.com/engine/api/#api-version-matrix) included in stable releases for a given platform. For Docker daemons on Linux, the earliest supported API version is 1.12 (corresponding with Docker Engine v1.0.0), whereas for Docker daemons on Windows, the earliest supported API version is 1.24 (corresponding with Docker Engine v1.12.0). Support for legacy API versions (providing old API versions on current versions of the Docker Engine) is primarily intended to provide compatibility with recent, but still supported versions of the client, which is a common scenario (the Docker daemon may be updated to the latest release, but not all clients may be up-to-date or vice versa). Support for API versions before that (API versions provided by EOL versions of the Docker Daemon) is provided on a "best effort" basis. Use of old API versions is very rare, and support for legacy API versions involves significant complexity (Docker 1.0.0 having been released 10 years ago). Because of this, we'll start deprecating support for legacy API versions. Docker Engine v25.0 by default disables API version older than 1.24 (aligning the minimum supported API version between Linux and Windows daemons). When connecting with a client that uses an API version version older than 1.24, the daemon returns an error. The following example configures the docker CLI to use API version 1.23, which produces an error: DOCKER_API_VERSION=1.23 docker version Error response from daemon: client version 1.23 is too old. Minimum supported API version is 1.24, please upgrade your client to a newer version An environment variable (`DOCKER_MIN_API_VERSION`) is introduced that allows re-enabling older API versions in the daemon. This environment variable must be set in the daemon's environment (for example, through a [systemd override file](https://docs.docker.com/config/daemon/systemd/)), and the specified API version must be supported by the daemon (`1.12` or higher on Linux, or `1.24` or higher on Windows). Support for API versions lower than `1.24` will be permanently removed in Docker Engine v26, and the minimum supported API version will be incrementally raised in releases following that. We do not recommend depending on the `DOCKER_MIN_API_VERSION` environment variable other than for exceptional cases where it's not possible to update old clients, and those clients must be supported. Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

thaJeztah · 2024-01-16T17:19:04Z

@dvdksn @neersighted I THINK I addressed your comments, but take a good look to see if I did 🤗

thaJeztah · 2024-01-16T18:42:11Z

Thanks! I'll bring this one in, but happy to touch-up things in a follow up where we see a need 👍

thaJeztah added impact/changelog impact/deprecation kind/docs status/3-docs-review area/api labels Jan 16, 2024

thaJeztah added this to the 25.0.0 milestone Jan 16, 2024

thaJeztah self-assigned this Jan 16, 2024

thaJeztah commented Jan 16, 2024

View reviewed changes

thaJeztah requested review from dvdksn and neersighted January 16, 2024 15:39

neersighted reviewed Jan 16, 2024

View reviewed changes

dvdksn reviewed Jan 16, 2024

View reviewed changes

thaJeztah force-pushed the deprecate_old_api_versions branch from 9791b23 to d2efc5b Compare January 16, 2024 17:16

neersighted approved these changes Jan 16, 2024

View reviewed changes

thaJeztah merged commit 5fde1f2 into docker:master Jan 16, 2024

thaJeztah deleted the deprecate_old_api_versions branch January 16, 2024 18:42

thaJeztah mentioned this pull request Jan 19, 2024

engine: add release notes for v25.0.0 docker/docs#18253

Merged

	Docker Engine up until v25.0 provide support for all [API versions](https://docs.docker.com/engine/api/#api-version-matrix)
	Docker Engine versions through v25.0 provide support for all [API versions](https://docs.docker.com/engine/api/#api-version-matrix)

	versions of the Docker Daemon) is provided on a "best effort" base.
	versions of the Docker Daemon) is provided on a "best effort" basis.

	involves significant complexity (Docker 1.0.0 was released 10 Years ago).
	involves significant complexity (Docker 1.0.0 having been released 10 years ago).

	re-enabling older API versions in the daemon. This environment-variable must
	re-enabling older API versions in the daemon. This environment variable must

	clients. When a client connects, it can perform API-version negotiation to
	clients. Docker clients can perform API-version negotiation to

	included in stable releases for a given platform. For Linux daemons, the oldest
	included in stable releases for a given platform. For Linux daemons, the earliest

	for Windows Daemons, the oldest supported API version is 1.24 (corresponding
	for Windows Daemons, the earliest supported API version is 1.24 (corresponding

	Daemon may be updated to the latest release, but not all clients may be up-to-date
	daemon may be updated to the latest release, but not all clients may be up-to-date

Conversation

thaJeztah commented Jan 16, 2024

Uh oh!

codecov-commenter commented Jan 16, 2024

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dvdksn Jan 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

neersighted Jan 16, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

thaJeztah commented Jan 16, 2024

Uh oh!

thaJeztah commented Jan 16, 2024

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dvdksn Jan 16, 2024 •

edited

Loading

neersighted Jan 16, 2024 •

edited

Loading