Breaking Key Change in Docker CLI Version Response

[superslowsoftware]

Summary

With ansible community.docker the docker_compose_v2 module fails with KeyError: 'ApiVersion' when running against Docker Engine 29.0.0. The module's version detection logic in common_cli.py is incompatible with the new JSON output format from Docker 29.x.

Issue Type

• Bug Report

Component Name

• docker_compose_v2 module
• common_cli.py (module_utils)

Ansible Version

ansible-core 2.16.5

Collection Version

community.docker: 4.2.0 & 5.0.1 (same behavior)

Docker Version (Target Host)

Client: Docker Engine - Community
 Version:           29.0.0
 API version:       1.52
 Go version:        go1.25.4
 Built:             Mon Nov 10 21:49:39 2025

Server: Docker Engine - Community
 Engine:
  Version:          29.0.0
  API version:      1.52 (minimum version 1.44)

OS / Environment

• Target Host: RHEL 9 / CentOS 9 (kernel 5.14.0-631.el9.x86_64)
• Target Python: 3.9
• Docker Compose: v2.40.3

Steps to Reproduce

1. Install Docker 29.0.0 on target host
2. Run playbook with community.docker.docker_compose_v2 module:

- name: Start docker compose cluster
  community.docker.docker_compose_v2:
    project_src: "/path/to/compose"
    files: "docker-compose.yml"
    project_name: "test_stack"
    state: "present"

3. Module fails with KeyError

Expected Results

Module successfully detects Docker version and executes compose commands.

Actual Results

KeyError: 'ApiVersion'
  File "ansible_collections/community/docker/plugins/modules/docker_compose_v2.py", line 625, in main
  File "ansible_collections/community/docker/plugins/module_utils/common_cli.py", line 303, in __init__
  File "ansible_collections/community/docker/plugins/module_utils/common_cli.py", line 83, in __init__
KeyError: 'ApiVersion'

Root Cause

Docker 29.0.0 changed the JSON output structure of docker version --format json. The parsing logic expects a consistent ApiVersion key, but Docker 29.x returns:

Client section:

{
  "Client": {
    "ApiVersion": "1.52",  // Still lowercase 'p'
    "DefaultAPIVersion": "1.52"
  }
}

Server section:

{
  "Server": {
    "APIVersion": "1.52",  // Now all-caps "API"
    "MinAPIVersion": "1.44",
    "Components": [
      {
        "Name": "Engine",
        "Details": {
          "ApiVersion": "1.52"  // Also exists here
        }
      }
    ]
  }
}

The module's parsing in common_cli.py line 83 needs to be updated to handle both the old and new JSON structures.

Workaround

Downgrade to Docker 27.x (stable LTS version) or use shell commands instead of the module:

- name: Start docker compose cluster
  shell: |
    docker compose -f docker-compose.yml -p project_name up -d
  args:
    chdir: "/path/to/compose"

Suggested Fix

Update common_cli.py to check for both ApiVersion and APIVersion keys, and handle the new nested structure in Docker 29.x JSON output.

[felixfontein]

Ref: docker/cli#6647

[felixfontein]

The root cause seems to be moby/moby#51233.

[felixfontein]

There's also an issue in moby/moby: moby/moby#51476

[felixfontein]

Fix on Docker's side: docker/cli#6648

[felixfontein]

#1187 works around the issue in community.docker.

[felixfontein]

Docker's upstream 29.0.1 is out with a fix: https://github.com/moby/moby/releases/tag/docker-v29.0.1