Pinning DOCKER_API_VERSION versus automatic negotiation for a client image running against variable Docker Engine versions

Compatibility Policy for Docker API Version in Multi-Daemon Environments

A single immutable client image is deployed against both self-hosted and managed Docker daemons that may expose different API version ranges. The client needs to reliably perform build, push, and container lifecycle operations without modification. Pinning DOCKER_API_VERSION locks the client to a specific API contract, ensuring identical behavior across daemon versions, but risks incompatibility when the daemon's minimum supported API version exceeds the pinned value. Automatic negotiation allows the client to use the highest mutually supported API version, maximizing feature availability on newer daemons, yet introduces non-deterministic code paths that can mask failures until an engine upgrade occurs.

The core constraint is maintaining operational consistency for CI workflows while supporting a range of daemon versions in production and managed CI environments. The decision hinges on whether compatibility guarantees should be enforced in the client image through explicit version pinning, or delegated to runtime negotiation with appropriate feature detection.

Two documented approaches exist: (1) setting DOCKER_API_VERSION explicitly in the client environment to a version known to be supported by all target daemons, or (2) omitting the variable and allowing the Docker client SDK to negotiate the highest compatible API version with each daemon. The trade-off centers on reproducibility versus feature access, with additional uncertainty around when pinned versions may be deprecated by the Docker ecosystem.

Which approach better balances the need for reproducible CI behavior against the requirement to support both legacy and modern Docker daemons without client image changes?