fix(docker-agent): let the host lower the Docker API version

[FreZZZeR]

Problem

DockerAgent's collector config pins the docker_stats receiver to api_version: "1.44". A Docker daemon rejects a client newer than its own maximum, so on any host running an older Engine the receiver fails to start — and because a failed receiver aborts pipeline startup, the whole collector exits and the container restart-loops:

Error: cannot start pipelines: failed to start "docker_stats" receiver:
Error response from daemon: client version 1.44 is too new.
Maximum supported API version is 1.41

Reproduced on Docker Engine 20.10.17 (API 1.41, min 1.12) — the agent never collected anything on that host.

There was no clean way out. The value is a literal, and the config lives inside the image at /etc/otelcol-contrib/config.yaml, so the only workarounds are to replace the vendor's config wholesale or to layer a second --config over it — both of which require knowing an internal path of the image.

Fix

api_version now comes from DOCKER_API_VERSION, which the image defaults to 1.44. The pin that fixed the other direction stays in place (the receiver's own default 1.25 is rejected by modern daemons — the original comment explains this), while a host with an older daemon can pass its own maximum:

docker version --format '{{ .Server.APIVersion }}'   # e.g. 1.41 on Engine 20.10
docker run -d ... -e DOCKER_API_VERSION=1.41 ...

The setting keeps working after the daemon is upgraded, since newer daemons still serve older API versions, so operators can drop it on their own schedule instead of urgently.

Why ${env:DOCKER_API_VERSION} and not ${env:DOCKER_API_VERSION:-1.44}

Default-valued expansion depends on the confmap version, and nothing else in this repo relies on it. Declaring the default as ENV in the Dockerfile — the same pattern already used for DOCKER_HOST_NAME — works on any collector version and makes the default visible in docker inspect.

Changes

• DockerAgent/Dockerfile.tpl — ENV DOCKER_API_VERSION=1.44
• DockerAgent/otel-collector-config.yaml — api_version: "${env:DOCKER_API_VERSION}"
• DockerAgent/docker-compose.yml — passes DOCKER_API_VERSION through, defaulting to 1.44
• DockerAgent/README.md, docs/.../en/telemetry/docker-host.md — env-var row plus a troubleshooting entry that quotes the error text people will search for

Behaviour is unchanged for anyone who does not set the variable.

Verification

On the affected host (Engine 20.10.17) with DOCKER_API_VERSION=1.41:

• the collector starts and stays up — no restart loop;
• container.* metrics arrive on the 30s interval (container.memory.percent, container.pids.count, container.uptime, container.restarts);
• container logs arrive through the filelog receiver.

With the variable unset the image behaves exactly as before (1.44).

Notes

Only the English docs page is updated; the other locale copies of telemetry/docker-host.md still carry the old environment-variable table. Happy to extend it if you would rather keep them in step.

[simlarsen]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.