Behavior of docker_container around images differs from documented

[giner]

SUMMARY

The documentation states:

When state is present or started, the module compares the configuration of an existing container to requested configuration. The evaluation includes the image version. If the image version in the registry does not match the container, the container will be recreated. You can stop this behavior by setting ignore_image to True.

Warning: This option is ignored if image: ignore or *: ignore is specified in the comparisons option.

The actual behavior of docker_container module is that neither comparison -> image: ignore nor ignore_image: true make any effect.

ISSUE TYPE

• Bug Report

COMPONENT NAME

docker_container

ANSIBLE VERSION

ansible [core 2.13.1]
  config file = None
  configured module search path = ['/home/stas/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /home/stas/.local/lib/python3.10/site-packages/ansible
  ansible collection location = /home/stas/.ansible/collections:/usr/share/ansible/collections
  executable location = /home/stas/.local/bin/ansible
  python version = 3.10.4 (main, Apr  2 2022, 09:04:19) [GCC 11.2.0]
  jinja version = 3.0.3
  libyaml = True

COLLECTION VERSION

Collection       Version
---------------- -------
community.docker 2.6.0  

CONFIGURATION

OS / ENVIRONMENT

STEPS TO REPRODUCE

- hosts: localhost
  gather_facts: false

  tasks:
    - docker_container:
        name: docker-test
        image: localhost:5000/docker-test
        #pull: true
        ignore_image: true
        comparisons:
          image: ignore
        command: sleep 600

EXPECTED RESULTS

by default (as described in the documentation) docker_container pulls remote image if changed (this may require changing the default for pull to true)

ignore_image and image: ignore are either respected or removed (according to the documentation the expected behavior of ignore matches to what pull: true/false does, therefore these parameters seem to be useless unless they allow ignoring changes to local image if anybody every needs this)

ACTUAL RESULTS

To illustrate I'll describe a few cases below.

Case 1 (default module settings)

before running

• remote image -> id1
• local image -> id2
• container image -> id3

after running

• remote image -> id1
• local image -> id2
• container image -> id2

Case 2 (pull is set to true)

before running

• remote image -> id1
• local image -> id2
• container image -> id3

after running

• remote image -> id1
• local image -> id1
• container image -> id1

Note: neither ignore_image: true nor comparison -> image: ignore change the behavior described above

[felixfontein]

Did you run the playbook/task with --diff / diff: true? It would be interesting what exactly causes the container to be recreated. I'm asking because ignore_image: true / comparsion -> image: ingnore does work (see the tests: https://github.com/ansible-collections/community.docker/blob/main/tests/integration/targets/docker_container/tasks/tests/options.yml#L2141-L2195).

What I can imagine goes wrong in your case is that the expected container configuration is computed based on the image (https://github.com/ansible-collections/community.docker/blob/main/plugins/modules/docker_container.py#L2230-L2245), and here not the image used by the container is used, but the image specified to the module. So depending on how the two images (the one used by the container, and the one mention in the module's configuration) differ, this could cause recreation of the container.

[giner]

TIL, I didn't know about --diff, very useful

TASK [docker_container] *********************************
--- before
+++ after
@@ -1,9 +1,10 @@
 {
     "expected_env": [
         "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
-        "_BASH_BASELINE=4.0",
-        "_BASH_LATEST_PATCH=44",
-        "_BASH_VERSION=4.0.44"
+        "_BASH_BASELINE=3.2.57",
+        "_BASH_BASELINE_PATCH=57",
+        "_BASH_LATEST_PATCH=57",
+        "_BASH_VERSION=3.2.57"
     ],
     "running": true
 }

changed: [localhost]

[felixfontein]

The expected environment is computed from the image's environment and the module's env parameter. So this is likely caused by the image used by the container having a different environment baked in than the image specified in the module parameters (I guess that the _BASH_* values come from the image).

I think the correct way to handle this would be to use the correct image to compute the differences: if the image is ignored, use the image currently used for the contained in this comparison. Unfortunately the old behavior has been in use for quite a few years now, and I'm not sure whether backporting a change for this is a good idea, since this might cause some breakage with existing playbooks / tasks which expect this behavior.

In any case, you can work around this by specifying comparison -> env: ignore.

[giner]

Ignoring env would make it ignore all environment variables which is usually undesirable. Either way all my use-cases are covered by pull: true / false. The issue is mostly around the current behavior and documentation being confusing and sometimes not correct. For example the docs say

If the image version in the registry does not match the container, the container will be recreated

which is not correct because the image is not checked against the registry unless pull is set to true

[felixfontein]

#428 adds an option which allows to control this behavior.