docker_container: allow pull=never, and make check mode behavior configurable (#797)

* Allow to configure behavior of pull=true in check mode.

* Change pull to option that accepts some strings as well, such as pull=never.

* Adjust values.

plugins/module_utils/module_container/module.py

@@ -78,6 +78,11 @@ class ContainerManager(DockerBaseClass):
         self.param_output_logs = self.module.params['output_logs']
         self.param_paused = self.module.params['paused']
         self.param_pull = self.module.params['pull']
+        if self.param_pull is True:
+            self.param_pull = 'always'
+        if self.param_pull is False:
+            self.param_pull = 'missing'
+        self.param_pull_check_mode_behavior = self.module.params['pull_check_mode_behavior']
         self.param_recreate = self.module.params['recreate']
         self.param_removal_wait_timeout = self.module.params['removal_wait_timeout']
         self.param_restart = self.module.params['restart']
@@ -444,21 +449,28 @@ class ContainerManager(DockerBaseClass):
             if not tag:
                 tag = "latest"
             image = self.engine_driver.inspect_image_by_name(self.client, repository, tag)
-            if not image or self.param_pull:
+            if not image and self.param_pull == "never":
+                self.client.fail("Cannot find image with name %s:%s, and pull=never" % (repository, tag))
+            if not image or self.param_pull == "always":
                 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
+                        self.results['actions'].append(dict(pulled_image="%s:%s" % (repository, tag), 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['actions'].append(dict(pulled_image="%s:%s" % (repository, tag), changed=True))
+                elif not image or self.param_pull_check_mode_behavior == 'always':
+                    # If the image isn't there, or pull_check_mode_behavior == 'always', claim we'll
+                    # pull. (Implicitly: if the image is there, claim it already was latest unless
+                    # pull_check_mode_behavior == 'always'.)
                     self.results['changed'] = True
-                    self.results['actions'].append(dict(pulled_image="%s:%s" % (repository, tag)))
+                    action = dict(pulled_image="%s:%s" % (repository, tag))
+                    if not image:
+                        action['changed'] = True
+                    self.results['actions'].append(action)
 
         self.log("image")
         self.log(image, pretty_print=True)
@@ -860,7 +872,8 @@ def run_module(engine_driver):
             networks_cli_compatible=dict(type='bool', default=True),
             output_logs=dict(type='bool', default=False),
             paused=dict(type='bool'),
-            pull=dict(type='bool', default=False),
+            pull=dict(type='raw', choices=['never', 'missing', 'always', True, False], default='missing'),
+            pull_check_mode_behavior=dict(type='str', choices=['image_not_present', 'always'], default='image_not_present'),
             purge_networks=dict(type='bool', default=False, removed_in_version='4.0.0', removed_from_collection='community.docker'),
             recreate=dict(type='bool', default=False),
             removal_wait_timeout=dict(type='float'),

plugins/modules/docker_container.py

@@ -35,7 +35,8 @@ attributes:
   check_mode:
     support: partial
     details:
-      - When trying to pull an image, the module assumes this is always changed in check mode.
+      - When trying to pull an image, the module assumes this is never changed in check mode except when the image is not present on the Docker daemon.
+      - This behavior can be configured with O(pull_check_mode_behavior).
   diff_mode:
     support: full
 
@@ -788,12 +789,37 @@ options:
       - ports
   pull:
     description:
-      - If true, always pull the latest version of an image. Otherwise, will only pull an image
-        when missing.
+      - If set to V(never), will never try to pull an image. Will fail if the image is not available
+        on the Docker daemon.
+      - If set to V(missing) or V(false), only pull the image if it is not available on the Docker
+        daemon. This is the default behavior.
+      - If set to V(always) or V(true), always try to pull the latest version of the image.
       - "B(Note:) images are only pulled when specified by name. If the image is specified
-        as a image ID (hash), it cannot be pulled."
-    type: bool
-    default: false
+        as a image ID (hash), it cannot be pulled, and this option is ignored."
+      - "B(Note:) the values V(never), V(missing), and V(always) are only available since
+        community.docker 3.8.0. Earlier versions only support V(true) and V(false)."
+    type: raw
+    choices:
+      - never
+      - missing
+      - always
+      - true
+      - false
+    default: missing
+  pull_check_mode_behavior:
+    description:
+      - Allows to adjust the behavior when O(pull=always) or O(pull=true) in check mode.
+      - Since the Docker daemon does not expose any functionality to test whether a pull will result
+        in a changed image, the module by default acts like O(pull=always) only results in a change when
+        the image is not present.
+      - If set to V(image_not_present) (default), only report changes in check mode when the image is not present.
+      - If set to V(always), always report changes in check mode.
+    type: str
+    default: image_not_present
+    choices:
+      - image_not_present
+      - always
+    version_added: 3.8.0
   purge_networks:
     description:
       - Remove the container from ALL networks not included in O(networks) parameter.