Add docker_image_remove module. (#732)

plugins/modules/docker_image.py

@@ -254,6 +254,8 @@ seealso:
   - module: community.docker.docker_image_info
   - module: community.docker.docker_image_load
   - module: community.docker.docker_image_pull
+  - module: community.docker.docker_image_push
+  - module: community.docker.docker_image_remove
   - module: community.docker.docker_image_tag
 '''
 

plugins/modules/docker_image_load.py

@@ -47,6 +47,11 @@ requirements:
 
 author:
   - Felix Fontein (@felixfontein)
+
+seealso:
+  - module: community.docker.docker_image_push
+  - module: community.docker.docker_image_remove
+  - module: community.docker.docker_image_tag
 '''
 
 EXAMPLES = '''

plugins/modules/docker_image_pull.py

@@ -64,6 +64,11 @@ requirements:
 
 author:
   - Felix Fontein (@felixfontein)
+
+seealso:
+  - module: community.docker.docker_image_pull
+  - module: community.docker.docker_image_remove
+  - module: community.docker.docker_image_tag
 '''
 
 EXAMPLES = '''

plugins/modules/docker_image_push.py

@@ -36,7 +36,7 @@ options:
     required: true
   tag:
     description:
-      - Used to select an image when pulling. Defaults to V(latest).
+      - Select which image to push. Defaults to V(latest).
       - If O(name) parameter format is C(name:tag) or C(image@hash:digest), then O(tag) will be ignored.
     type: str
     default: latest
@@ -48,6 +48,8 @@ author:
   - Felix Fontein (@felixfontein)
 
 seealso:
+  - module: community.docker.docker_image_pull
+  - module: community.docker.docker_image_remove
   - module: community.docker.docker_image_tag
 '''
 

plugins/modules/docker_image_remove.py

@@ -0,0 +1,267 @@
+#!/usr/bin/python
+#
+# Copyright 2016 Red Hat | Ansible
+# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from __future__ import absolute_import, division, print_function
+__metaclass__ = type
+
+
+DOCUMENTATION = '''
+---
+module: docker_image_remove
+
+short_description: Remove Docker images
+
+description:
+  - Remove Docker images from the Docker daemon.
+
+extends_documentation_fragment:
+  - community.docker.docker.api_documentation
+  - community.docker.attributes
+  - community.docker.attributes.actiongroup_docker
+
+attributes:
+  check_mode:
+    support: full
+  diff_mode:
+    support: full
+
+options:
+  name:
+    description:
+      - "Image name. Name format will be one of: C(name), C(repository/name), C(registry_server:port/name).
+        When pushing or pulling an image the name can optionally include the tag by appending C(:tag_name)."
+      - Note that image IDs (hashes) can also be used.
+    type: str
+    required: true
+  tag:
+    description:
+      - Tag for the image name O(name) that is to be tagged.
+      - If O(name)'s format is C(name:tag), then the tag value from O(name) will take precedence.
+    type: str
+    default: latest
+  force:
+    description:
+      - Un-tag and remove all images matching the specified name.
+    type: bool
+    default: false
+  prune:
+    description:
+      - Delete untagged parent images.
+    type: bool
+    default: true
+
+requirements:
+  - "Docker API >= 1.25"
+
+author:
+  - Felix Fontein (@felixfontein)
+
+seealso:
+  - module: community.docker.docker_image_load
+  - module: community.docker.docker_image_pull
+  - module: community.docker.docker_image_tag
+'''
+
+EXAMPLES = '''
+
+- name: Remove an image
+  community.docker.docker_image_remove:
+    name: pacur/centos-7
+'''
+
+RETURN = '''
+image:
+    description:
+      - Image inspection results for the affected image before removal.
+      - Empty if the image was not found.
+    returned: success
+    type: dict
+    sample: {}
+deleted:
+    description:
+      - The digests of the images that were deleted.
+    returned: success
+    type: list
+    elements: str
+    sample: []
+untagged:
+    description:
+      - The digests of the images that were untagged.
+    returned: success
+    type: list
+    elements: str
+    sample: []
+'''
+
+import traceback
+
+from ansible.module_utils.common.text.converters import to_native
+
+from ansible_collections.community.docker.plugins.module_utils.common_api import (
+    AnsibleDockerClient,
+    RequestException,
+)
+
+from ansible_collections.community.docker.plugins.module_utils.util import (
+    DockerBaseClass,
+    is_image_name_id,
+    is_valid_tag,
+)
+
+from ansible_collections.community.docker.plugins.module_utils._api.errors import DockerException, NotFound
+from ansible_collections.community.docker.plugins.module_utils._api.utils.utils import (
+    parse_repository_tag,
+)
+
+
+class ImageRemover(DockerBaseClass):
+
+    def __init__(self, client):
+        super(ImageRemover, self).__init__()
+
+        self.client = client
+        self.check_mode = self.client.check_mode
+        self.diff = self.client.module._diff
+
+        parameters = self.client.module.params
+        self.name = parameters['name']
+        self.tag = parameters['tag']
+        self.force = parameters['force']
+        self.prune = parameters['prune']
+
+        if not is_valid_tag(self.tag, allow_empty=True):
+            self.fail('"{0}" is not a valid docker tag'.format(self.tag))
+
+        # If name contains a tag, it takes precedence over tag parameter.
+        if not is_image_name_id(self.name):
+            repo, repo_tag = parse_repository_tag(self.name)
+            if repo_tag:
+                self.name = repo
+                self.tag = repo_tag
+
+    def fail(self, msg):
+        self.client.fail(msg)
+
+    def get_diff_state(self, image):
+        if not image:
+            return dict(exists=False)
+        return dict(
+            exists=True,
+            id=image['Id'],
+            tags=sorted(image.get('RepoTags') or []),
+            digests=sorted(image.get('RepoDigests') or []),
+        )
+
+    def absent(self):
+        results = dict(
+            changed=False,
+            actions=[],
+            image={},
+            deleted=[],
+            untagged=[],
+        )
+
+        name = self.name
+        if is_image_name_id(name):
+            image = self.client.find_image_by_id(name, accept_missing_image=True)
+        else:
+            image = self.client.find_image(name, self.tag)
+            if self.tag:
+                name = "%s:%s" % (self.name, self.tag)
+
+        if self.diff:
+            results['diff'] = dict(before=self.get_diff_state(image))
+
+        if not image:
+            if self.diff:
+                results['diff']['after'] = self.get_diff_state(image)
+            return results
+
+        results['changed'] = True
+        results['actions'].append("Removed image %s" % (name))
+        results['image'] = image
+
+        if not self.check_mode:
+            try:
+                res = self.client.delete_json('/images/{0}', name, params={'force': self.force, 'noprune': not self.prune})
+            except NotFound:
+                # If the image vanished while we were trying to remove it, don't fail
+                res = []
+            except Exception as exc:
+                self.fail("Error removing image %s - %s" % (name, to_native(exc)))
+
+            for entry in res:
+                if entry.get('Untagged'):
+                    results['untagged'].append(entry['Untagged'])
+                if entry.get('Deleted'):
+                    results['deleted'].append(entry['Deleted'])
+
+            results['untagged'] = sorted(results['untagged'])
+            results['deleted'] = sorted(results['deleted'])
+
+            if self.diff:
+                image_after = self.client.find_image_by_id(image['Id'], accept_missing_image=True)
+                results['diff']['after'] = self.get_diff_state(image_after)
+
+        elif is_image_name_id(name):
+            results['deleted'].append(image['Id'])
+            results['untagged'] = sorted((image.get('RepoTags') or []) + (image.get('RepoDigests') or []))
+            if not self.force and results['untagged']:
+                self.fail('Cannot delete image by ID that is still in use - use force=true')
+            if self.diff:
+                results['diff']['after'] = self.get_diff_state({})
+
+        elif is_image_name_id(self.tag):
+            results['untagged'].append(name)
+            if len(image.get('RepoTags') or []) < 1 and len(image.get('RepoDigests') or []) < 2:
+                results['deleted'].append(image['Id'])
+            if self.diff:
+                results['diff']['after'] = self.get_diff_state(image)
+                try:
+                    results['diff']['after']['digests'].remove(name)
+                except ValueError:
+                    pass
+
+        else:
+            results['untagged'].append(name)
+            if len(image.get('RepoTags') or []) < 2 and len(image.get('RepoDigests') or []) < 1:
+                results['deleted'].append(image['Id'])
+            if self.diff:
+                results['diff']['after'] = self.get_diff_state(image)
+                try:
+                    results['diff']['after']['tags'].remove(name)
+                except ValueError:
+                    pass
+
+        return results
+
+
+def main():
+    argument_spec = dict(
+        name=dict(type='str', required=True),
+        tag=dict(type='str', default='latest'),
+        force=dict(type='bool', default=False),
+        prune=dict(type='bool', default=True),
+    )
+
+    client = AnsibleDockerClient(
+        argument_spec=argument_spec,
+        supports_check_mode=True,
+    )
+
+    try:
+        results = ImageRemover(client).absent()
+        client.module.exit_json(**results)
+    except DockerException as e:
+        client.fail('An unexpected Docker error occurred: {0}'.format(to_native(e)), exception=traceback.format_exc())
+    except RequestException as e:
+        client.fail(
+            'An unexpected requests error occurred when trying to talk to the Docker daemon: {0}'.format(to_native(e)),
+            exception=traceback.format_exc())
+
+
+if __name__ == '__main__':
+    main()

plugins/modules/docker_image_tag.py

@@ -70,6 +70,7 @@ author:
 
 seealso:
   - module: community.docker.docker_image_push
+  - module: community.docker.docker_image_remove
 '''
 
 EXAMPLES = '''