Make image archive/save idempotent, using image id and repo tags as keys (#500)

plugins/modules/docker_image.py

@@ -343,6 +343,13 @@ from ansible_collections.community.docker.plugins.module_utils.common_api import
     AnsibleDockerClient,
     RequestException,
 )
+
+from ansible_collections.community.docker.plugins.module_utils.image_archive import (
+    archived_image_manifest,
+    api_image_id,
+    ImageArchiveInvalidException,
+)
+
 from ansible_collections.community.docker.plugins.module_utils.util import (
     clean_dict_booleans_for_docker_api,
     DockerBaseClass,
@@ -535,6 +542,42 @@ class ImageManager(DockerBaseClass):
             self.results['actions'].append("Removed image %s" % (name))
             self.results['image']['state'] = 'Deleted'
 
+    @staticmethod
+    def archived_image_action(failure_logger, archive_path, current_image_name, current_image_id):
+        '''
+        If the archive is missing or requires replacement, return an action message.
+
+        :param failure_logger: a logging function that accepts one parameter of type str
+        :type failure_logger: Callable
+        :param archive_path: Filename to write archive to
+        :type archive_path: str
+        :param current_image_name: repo:tag
+        :type current_image_name: str
+        :param current_image_id: Hash, including hash type prefix such as "sha256:"
+        :type current_image_id: str
+
+        :returns: Either None, or an Ansible action message.
+        :rtype: str
+        '''
+
+        def build_msg(reason):
+            return 'Archived image %s to %s, %s' % (current_image_name, archive_path, reason)
+
+        try:
+            archived = archived_image_manifest(archive_path)
+        except ImageArchiveInvalidException as exc:
+            failure_logger('Unable to extract manifest summary from archive: %s' % to_native(exc))
+            return build_msg('overwriting an unreadable archive file')
+
+        if archived is None:
+            return build_msg('since none present')
+        elif current_image_id == api_image_id(archived.image_id) and [current_image_name] == archived.repo_tags:
+            return None
+        else:
+            name = ', '.join(archived.repo_tags)
+
+            return build_msg('overwriting archive with image %s named %s' % (archived.image_id, name))
+
     def archive_image(self, name, tag):
         '''
         Archive an image to a .tar file. Called when archive_path is passed.
@@ -559,9 +602,17 @@ class ImageManager(DockerBaseClass):
             self.log("archive image: image %s not found" % image_name)
             return
 
-        self.results['actions'].append('Archived image %s to %s' % (image_name, self.archive_path))
-        self.results['changed'] = True
-        if not self.check_mode:
+        # Will have a 'sha256:' prefix
+        image_id = image['Id']
+
+        action = self.archived_image_action(self.client.module.debug, self.archive_path, image_name, image_id)
+
+        if action:
+            self.results['actions'].append(action)
+
+        self.results['changed'] = action is not None
+
+        if (not self.check_mode) and self.results['changed']:
             self.log("Getting archive of image %s" % image_name)
             try:
                 saved_image = self.client._stream_raw_result(
@@ -579,8 +630,7 @@ class ImageManager(DockerBaseClass):
             except Exception as exc:
                 self.fail("Error writing image archive %s - %s" % (self.archive_path, to_native(exc)))
 
-        if image:
-            self.results['image'] = image
+        self.results['image'] = image
 
     def push_image(self, name, tag=None):
         '''