Guest24897
/
DockerCLI
mirror of https://github.com/docker/cli.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: reference: version: add info about API version negotiation 

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>
This commit is contained in:
Sebastiaan van Stijn 2022-04-30 14:30:19 +02:00
parent 99bb525f98
commit 2119f425b6
No known key found for this signature in database
GPG Key ID: 76698F39D527CE8C
1 changed files with 41 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
docs/reference/commandline/version.md
View File

@ -114,6 +114,41 @@ Server: Docker Engine - Community
GitCommit: fec3683
```
### API version and version negotiation
The API version used by the client depends on the Docker Engine that the Docker
CLI is connecting with. When connecting with the Docker Engine, the Docker CLI
and Docker Engine perform API version negotiation, and select the highest API
version that is supported by both the Docker CLI and the Docker Engine.
For example, if the CLI is connecting with a Docker 19.03 engine, it downgrades
to API version 1.40 (refer to the [API version matrix](https://docs.docker.com/engine/api/#api-version-matrix)
to learn about the supported API versions for Docker Engine):
```console
$ docker version --format '{{.Client.APIVersion}}'
1.40
```
Be aware that API version can also be overridden using the `DOCKER_API_VERSION`
environment variable, which can be useful for debugging purposes, and disables
API version negotiation. The following example illustrates an environment where
the `DOCKER_API_VERSION` environment variable is set. Unsetting the environment
variable removes the override, and re-enables API version negotiation:
```console
$ env | grep DOCKER_API_VERSION
DOCKER_API_VERSION=1.39
$ docker version --format '{{.Client.APIVersion}}'
1.39
$ unset DOCKER_API_VERSION
$ docker version --format '{{.Client.APIVersion}}'
1.41
```
## Examples
### <a name=format></a> Format the output (--format)
@ -133,12 +168,18 @@ $ docker version --format '{{.Server.Version}}'
### Get the client API version
The following example prints the API version that is used by the client:
```console
$ docker version --format '{{.Client.APIVersion}}'
1.41
```
The version shown is the API version that is negotiated between the client
and the Docker Engine. Refer to [API version and version negotiation](#api-version-and-version-negotiation)
above for more information.
### Dump raw JSON data
```console