pull as true + check mode + existing local image means no changes for the module

[woprandi]

SUMMARY

When this module is used with pull parameter as true, check mode and with an existing local image, the module always considers there is no changes. You will have the surprise during the real execution that your container has been recreated with a new image.
The source code is pretty straightforward :

community.docker/plugins/module_utils/module_container/module.py

Lines 447 to 461 in 7b55408

	if not image or self.param_pull:
	if not self.check_mode:
	self.log("Pull the image.")
	image, alreadyToLatest = self.engine_driver.pull_image(
	self.client, repository, tag, platform=self.module.params['platform'])
	if alreadyToLatest:
	self.results['changed'] = False
	else:
	self.results['changed'] = True
	self.results['actions'].append(dict(pulled_image="%s:%s" % (repository, tag)))
	elif not image:
	# If the image isn't there, claim we'll pull.
	# (Implicitly: if the image is there, claim it already was latest.)
	self.results['changed'] = True
	self.results['actions'].append(dict(pulled_image="%s:%s" % (repository, tag)))

ISSUE TYPE

• Bug Report

COMPONENT NAME

docker_container module

ANSIBLE VERSION

ansible2 :: ~ » ansible --version                                                                
ansible [core 2.16.3]
  config file = /home/otera/.ansible.cfg
  configured module search path = ['/home/otera/.ansible/plugins/modules', '/usr/share/ansible/plugins/modules']
  ansible python module location = /home/otera/.local/pipx/venvs/ansible/lib/python3.11/site-packages/ansible
  ansible collection location = /home/otera/.ansible/collections:/usr/share/ansible/collections
  executable location = /home/otera/.local/bin/ansible
  python version = 3.11.2 (main, Mar 13 2023, 12:18:29) [GCC 12.2.0] (/home/otera/.local/pipx/venvs/ansible/bin/python)
  jinja version = 3.1.3
  libyaml = True

COLLECTION VERSION

# /home/otera/.local/pipx/venvs/ansible/lib/python3.11/site-packages/ansible_collections
Collection        Version
----------------- -------
community.general 8.3.0  

CONFIGURATION

CONFIG_FILE() = /home/otera/.ansible.cfg
DEFAULT_HOST_LIST(/home/otera/.ansible.cfg) = ['/home/otera/provisioning/production']
DEFAULT_ROLES_PATH(/home/otera/.ansible.cfg) = ['/home/otera/provisioning/roles']
DEFAULT_STDOUT_CALLBACK(/home/otera/.ansible.cfg) = yaml
HOST_KEY_CHECKING(/home/otera/.ansible.cfg) = False
PAGER(env: PAGER) = less

OS / ENVIRONMENT

STEPS TO REPRODUCE

With these kind of playbook configuration

docker_container:
  name: <name>
  image: <image>:<tag>
  pull: true

1. Pull the image first
2. Update with the same tag in the registry
3. Run the playbook with check mode enabled
4. Check mode will print "ok"
5. Run without check mode
6. The image will be downloaded and your container recreated

EXPECTED RESULTS

With pull as true, the module should check with the remote registry if the local image is up-to-date or not

ACTUAL RESULTS

If a local image exists, the module say no changes on check mode.

[felixfontein]

With pull as true, the module should check with the remote registry if the local image is up-to-date or not

Docker does not support this, so it's impossible to implement.

[woprandi]

But how a docker pull can avoid to download if the local image is up-to-date ?

[felixfontein]

The Docker daemon does know this, but it does not provide any endpoint to clients that allow them to ask for this information. Since the docker_container module is not part of the Docker daemon, it has no way to get hold of that information until it starts an actual pull (which it must not do in check mode to avoid changing data).

[woprandi]

I see. That is a big lack. And generates a dangerous behavior. Thanks for your fast answer. I let you close if you want

[felixfontein]

I fully agree. I'll definitely update the docs so this is explicitly mentioned.

[felixfontein]

Hmm, I just checked, there's already a comment for the check mode attribute: When trying to pull an image, the module assumes this is always changed in check mode.. This is obviously not true, and I also checked the rewrite of the module from July 2022, the behavior didn't change then. (So that comment was always wrong.)

I'm wondering whether we should make this behavior configurable, since I can see good arguments for both behaviors. On the other hand, this is quite a special case and making the module interface even more complex for it feels like not a good idea.

[woprandi]

Yes that would be better to at least be able to configure the behavior.

[felixfontein]

I've implemented this in #797.