community.docker.docker_container command idempotency handling seems off or ill documented

[sandrinr]

SUMMARY

Running a Docker container with:

community.docker.docker_container:
  command: []
  command_handling: correct
  # ...

The module recreates the container with every Ansible run if the container image defines a CMD. For container images without CMD the container is not recreated.

Setting command_handling: compatibility, the container is not recreated.

This seems to be either a bug in the module or in the documentation. Reading the documentation, it seems to me that with command_handling: correct the module should ignore empty lists for command setting and and idemptency checks.

The default behavior for command (when provided as a list) and entrypoint is to convert them to strings without considering shell quoting rules. (For comparing idempotency, the resulting string is split considering shell quoting rules).
Also, setting command to an empty list of string, and setting entrypoint to an empty list will be handled as if these options are not specified. This is different from idempotency handling for other container-config related options.
When this is set to compatibility, which was the default until community.docker 3.0.0, the current behavior will be kept.
When this is set to correct, these options are kept as lists, and an empty value or empty list will be handled correctly for idempotency checks. This has been the default since community.docker 3.0.0.

ISSUE TYPE

• Bug Report

COMPONENT NAME

community.docker.docker_container

ANSIBLE VERSION

ansible [core 2.18.4]
  config file = /Users/****/Projects/infra/ansible/ansible.cfg
  configured module search path = ['/Users/****/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /opt/homebrew/Cellar/ansible/11.4.0/libexec/lib/python3.13/site-packages/ansible
  ansible collection location = /Users/****/.ansible/collections:/usr/share/ansible/collections
  executable location = /opt/homebrew/bin/ansible
  python version = 3.13.3 (main, Apr  8 2025, 13:54:08) [Clang 16.0.0 (clang-1600.0.26.6)] (/opt/homebrew/Cellar/ansible/11.4.0/libexec/bin/python)
  jinja version = 3.1.6
  libyaml = True

COLLECTION VERSION

# /Users/****/.ansible/collections/ansible_collections
Collection       Version
---------------- -------
community.docker 4.5.2  

# /opt/homebrew/Cellar/ansible/11.4.0/libexec/lib/python3.13/site-packages/ansible_collections
Collection       Version
---------------- -------
community.docker 4.5.2  

CONFIGURATION

CONFIG_FILE() = /Users/****/Projects/infra/ansible/ansible.cfg
DEFAULT_STDOUT_CALLBACK(/Users/****/Projects/infra/ansible/ansible.cfg) = protect_data
EDITOR(env: EDITOR) = vim
INTERPRETER_PYTHON(/Users/****/Projects/infra/ansible/ansible.cfg) = auto_silent

OS / ENVIRONMENT

macOS 15

STEPS TO REPRODUCE

Use the following action in a playbook or in a role to trigger the described behavior.

- name: testing...
  community.docker.docker_container:
    name: testing
    image: "nginx:latest"
    command: []
    command_handling: correct

EXPECTED RESULTS

Running this action multiple times, I expect Ansible to report no changes, except maybe on the first run to setup the container.

ACTUAL RESULTS

Ansible reports changes on every run of the action and also recreates the container every time.

Again, running the same action with command_handling: compatibility shows the expected behavior.

[felixfontein]

Thanks for reporting this (and providing a simple reproducer!). This is definitely a bug in the idempotency handling.

[felixfontein]

It looks like Docker Daemon does not allow to distinguish between an empty command being used to configure the container and the exact same command as in the image being specified. Which is not exactly great, but should allow to fix this.