Add docker_image_remove module. (#732)

tests/integration/targets/docker_container/tasks/main.yml

@@ -47,9 +47,8 @@
     with_items: "{{ cnames }}"
     diff: false
   - name: "Make sure all images are removed"
-    docker_image:
+    docker_image_remove:
       name: "{{ item }}"
-      state: absent
     with_items: "{{ inames }}"
   - name: "Make sure all networks are removed"
     docker_network:

tests/integration/targets/docker_container/tasks/tests/comparisons.yml

@@ -384,9 +384,8 @@
 
 - name: Pull {{ docker_test_image_hello_world }} image to make sure wildcard_2 test succeeds
   # If the image isn't there, it will pull it and return 'changed'.
-  docker_image:
+  docker_image_pull:
     name: "{{ docker_test_image_hello_world }}"
-    source: pull
 
 - name: wildcard
   docker_container:

tests/integration/targets/docker_container/tasks/tests/image-ids.yml

@@ -11,9 +11,8 @@
     cnames: "{{ cnames + [cname] }}"
 
 - name: Pull images
-  docker_image:
+  docker_image_pull:
     name: "{{ image }}"
-    source: pull
   loop:
     - "{{ docker_test_image_hello_world }}"
     - "{{ docker_test_image_alpine }}"
@@ -69,10 +68,9 @@
 
 - name: Untag image
   # Image will not be deleted since the container still uses it
-  docker_image:
+  docker_image_remove:
     name: "{{ docker_test_image_alpine }}"
-    force_absent: true
-    state: absent
+    force: true
 
 - name: Create container with {{ docker_test_image_alpine }} image via name (check mode, will pull, same image)
   docker_container:

tests/integration/targets/docker_container/tasks/tests/options.yml

@@ -2235,9 +2235,8 @@
 
 - name: Pull images to make sure ignore_image test succeeds
   # If the image isn't there, it will pull it and return 'changed'.
-  docker_image:
+  docker_image_pull:
     name: "{{ item }}"
-    source: pull
   loop:
     - "{{ docker_test_image_hello_world }}"
     - "{{ docker_test_image_registry_nginx }}"
@@ -2456,9 +2455,8 @@
   diff: false
 
 - name: cleanup image
-  docker_image:
+  docker_image_remove:
     name: "{{ iname_labels }}"
-    state: absent
   diff: false
 
 - assert:
@@ -2486,9 +2484,8 @@
 
 - name: Pull images to make sure ignore_image test succeeds
   # If the image isn't there, it will pull it and return 'changed'.
-  docker_image:
+  docker_image_pull:
     name: "{{ item }}"
-    source: pull
   loop:
     - "{{ docker_test_image_hello_world }}"
     - "{{ docker_test_image_registry_nginx }}"
@@ -2577,9 +2574,8 @@
     inames: "{{ inames + [iname_name_mismatch] }}"
 
 - name: Tag hello world image (pulled earlier) with new name
-  docker_image:
+  docker_image_tag:
     name: "{{ docker_test_image_registry_nginx }}"
-    source: local
     repository: "{{ iname_name_mismatch }}:latest"
 
 - name: image_name_mismatch
@@ -2617,9 +2613,8 @@
   diff: false
 
 - name: Cleanup image
-  docker_image:
+  docker_image_remove:
     name: "{{ iname_name_mismatch }}"
-    state: absent
   diff: false
 
 - assert:
@@ -3549,9 +3544,8 @@ avoid such warnings, please quote the value.' in (log_options_2.warnings | defau
 ####################################################################
 
 - name: Remove hello-world image
-  docker_image:
+  docker_image_remove:
     name: hello-world:latest
-    state: absent
 
 - name: platform
   docker_container:

tests/integration/targets/docker_image_info/tasks/main.yml

@@ -10,9 +10,8 @@
 
 - block:
   - name: Make sure image is not there
-    docker_image:
+    docker_image_remove:
       name: "{{ docker_test_image_alpine_different }}"
-      state: absent
 
   - name: Inspect a non-available image
     docker_image_info:

tests/integration/targets/docker_image_load/tasks/test.yml

@@ -21,9 +21,8 @@
 
   always:
   - name: "Make sure all images are removed"
-    docker_image:
+    docker_image_remove:
       name: "{{ item }}"
-      state: absent
     with_items: "{{ inames }}"
   - name: "Make sure all containers are removed"
     docker_container:

tests/integration/targets/docker_image_load/tasks/tests/basic.yml

@@ -42,10 +42,9 @@
 # All images by IDs
 
 - name: Remove all images
-  docker_image:
+  docker_image_remove:
     name: "{{ item }}"
-    state: absent
-    force_absent: true
+    force: true
   loop: "{{ all_images }}"
   ignore_errors: true
   register: remove_all_images
@@ -66,10 +65,9 @@
   when: remove_all_images is failed
 
 - name: Remove all images (after pruning)
-  docker_image:
+  docker_image_remove:
     name: "{{ item }}"
-    state: absent
-    force_absent: true
+    force: true
   loop: "{{ all_images }}"
   when: remove_all_images is failed
 
@@ -106,9 +104,8 @@
 # Mixed images and IDs
 
 - name: Remove all images
-  docker_image:
+  docker_image_remove:
     name: "{{ item }}"
-    state: absent
   loop: "{{ all_images }}"
 
 - name: Load all images (mixed images and IDs)
@@ -136,9 +133,8 @@
 # Same image twice
 
 - name: Remove all images
-  docker_image:
+  docker_image_remove:
     name: "{{ item }}"
-    state: absent
   loop: "{{ all_images }}"
 
 - name: Load all images (same image twice)
@@ -161,9 +157,8 @@
 # Single image by ID
 
 - name: Remove all images
-  docker_image:
+  docker_image_remove:
     name: "{{ item }}"
-    state: absent
   loop: "{{ all_images }}"
 
 - name: Load all images (single image by ID)
@@ -196,9 +191,8 @@
 # All images by names
 
 - name: Remove all images
-  docker_image:
+  docker_image_remove:
     name: "{{ item }}"
-    state: absent
   loop: "{{ all_images }}"
 
 - name: Load all images (names)

tests/integration/targets/docker_image_pull/tasks/test.yml

@@ -21,9 +21,8 @@
 
   always:
   - name: "Make sure all images are removed"
-    docker_image:
+    docker_image_remove:
       name: "{{ item }}"
-      state: absent
     with_items: "{{ inames }}"
   - name: "Make sure all containers are removed"
     docker_container:

tests/integration/targets/docker_image_pull/tasks/tests/basic.yml

@@ -8,10 +8,9 @@
     image_name: "{{ docker_test_image_hello_world_platform }}"
   block:
     - name: Make sure image is not there
-      docker_image:
+      docker_image_remove:
         name: "{{ image_name }}"
-        state: absent
-        force_absent: true
+        force: true
 
     - name: Pull image (check mode)
       docker_image_pull:
@@ -170,10 +169,9 @@
 
   always:
     - name: cleanup
-      docker_image:
+      docker_image_remove:
         name: "{{ image_name }}"
-        state: absent
-        force_absent: true
+        force: true
 
 - name: Pull image ID (must fail)
   docker_image_pull:

tests/integration/targets/docker_image_pull/tasks/tests/image-ids.yml

@@ -6,10 +6,9 @@
 - name: Image ID  pull tests
   block:
     - name: Make sure images are not there
-      docker_image:
+      docker_image_remove:
         name: "{{ item }}"
-        state: absent
-        force_absent: true
+        force: true
       loop:
         - "sha256:{{ docker_test_image_digest_v1_image_id }}"
         - "sha256:{{ docker_test_image_digest_v2_image_id }}"
@@ -82,10 +81,9 @@
 
   always:
     - name: cleanup
-      docker_image:
+      docker_image_remove:
         name: "{{ item }}"
-        state: absent
-        force_absent: true
+        force: true
       loop:
         - "sha256:{{ docker_test_image_digest_v1_image_id }}"
         - "sha256:{{ docker_test_image_digest_v2_image_id }}"

tests/integration/targets/docker_image_pull/tasks/tests/registry.yml

@@ -19,10 +19,9 @@
         inames: "{{ inames + [iname, hello_world_image_base ~ ':latest'] }}"
 
     - name: Make sure image is not there
-      docker_image:
+      docker_image_remove:
         name: "{{ hello_world_image_base }}:latest"
-        state: absent
-        force_absent: true
+        force: true
 
     - name: Make sure we have {{ docker_test_image_hello_world }}
       docker_image_pull:
@@ -45,10 +44,9 @@
       register: facts_1
 
     - name: Make sure image is not there
-      docker_image:
+      docker_image_remove:
         name: "{{ hello_world_image_base }}:latest"
-        state: absent
-        force_absent: true
+        force: true
 
     - name: Get facts of local image (not there)
       docker_image_info:

tests/integration/targets/docker_image_push/tasks/test.yml

@@ -21,9 +21,8 @@
 
   always:
   - name: "Make sure all images are removed"
-    docker_image:
+    docker_image_remove:
       name: "{{ item }}"
-      state: absent
     with_items: "{{ inames }}"
   - name: "Make sure all containers are removed"
     docker_container:

tests/integration/targets/docker_image_push/tasks/tests/basic.yml

@@ -7,9 +7,8 @@
     image_name: registry.example.com:5000/foo/bar:baz
   block:
     - name: Make sure image is not present
-      docker_image:
+      docker_image_remove:
         name: "{{ image_name }}"
-        state: absent
 
     - name: Push non-existing image (must fail)
       docker_image_push:

tests/integration/targets/docker_image_remove/aliases

@@ -0,0 +1,6 @@
+# Copyright (c) Ansible Project
+# 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
+
+azp/4
+destructive

tests/integration/targets/docker_image_remove/meta/main.yml

@@ -0,0 +1,8 @@
+---
+# Copyright (c) Ansible Project
+# 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
+
+dependencies:
+  - setup_docker
+  - setup_docker_python_deps

tests/integration/targets/docker_image_remove/tasks/main.yml

@@ -0,0 +1,296 @@
+---
+# Copyright (c) Ansible Project
+# 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
+
+####################################################################
+# WARNING: These are designed specifically for Ansible tests       #
+# and should not be used as examples of how to write Ansible roles #
+####################################################################
+
+- block:
+    - name: Pick image prefix
+      set_fact:
+        iname_prefix: "{{ 'ansible-docker-test-%0x' % ((2**32) | random) }}"
+
+    - name: Define image names
+      set_fact:
+        image: "{{ docker_test_image_hello_world }}"
+        image_id: "{{ docker_test_image_hello_world_image_id }}"
+        image_names:
+          - "{{ iname_prefix }}-tagged-1:latest"
+          - "{{ iname_prefix }}-tagged-1:foo"
+          - "{{ iname_prefix }}-tagged-1:bar"
+
+    - name: Remove image complete
+      docker_image_remove:
+        name: "{{ image_id }}"
+        force: true
+
+    - name: Remove tagged images
+      docker_image_remove:
+        name: "{{ item }}"
+      loop: "{{ image_names }}"
+
+    - name: Make sure image we work with is there
+      docker_image_pull:
+        name: "{{ image }}"
+      register: pulled_image
+      diff: true
+
+    - name: Remove tagged image (not there, check mode)
+      docker_image_remove:
+        name: "{{ iname_prefix }}-tagged-1:latest"
+      register: remove_1_check
+      check_mode: true
+      diff: true
+
+    - name: Remove tagged image (not there)
+      docker_image_remove:
+        name: "{{ iname_prefix }}-tagged-1:latest"
+      register: remove_1
+      diff: true
+
+    - name: Inspect image
+      docker_image_info:
+        name: "{{ iname_prefix }}-tagged-1:latest"
+      register: info_1
+
+    - assert:
+        that:
+          - remove_1_check is not changed
+          - remove_1_check.diff == remove_1.diff
+          - remove_1 is not changed
+          - remove_1.diff.before.exists is false
+          - remove_1.diff.after.exists is false
+          - remove_1.deleted | length == 0
+          - remove_1.untagged | length == 0
+          - remove_1_check.deleted == remove_1.deleted
+          - remove_1_check.untagged == remove_1.untagged
+          - info_1.images | length == 0
+
+    - name: Tag image 1
+      docker_image_tag:
+        name: "{{ image }}"
+        repository:
+          - "{{ iname_prefix }}-tagged-1:latest"
+          - "{{ iname_prefix }}-tagged-1:foo"
+          - "{{ iname_prefix }}-tagged-1:bar"
+
+    - name: Remove tagged image (check mode)
+      docker_image_remove:
+        name: "{{ iname_prefix }}-tagged-1:latest"
+      register: remove_2_check
+      check_mode: true
+      diff: true
+
+    - name: Remove tagged image
+      docker_image_remove:
+        name: "{{ iname_prefix }}-tagged-1:latest"
+      register: remove_2
+      diff: true
+
+    - name: Inspect image
+      docker_image_info:
+        name: "{{ iname_prefix }}-tagged-1:latest"
+      register: info_2
+
+    - assert:
+        that:
+          - remove_2_check is changed
+          - remove_2_check.diff == remove_2.diff
+          - remove_2 is changed
+          - remove_2.diff.before.id == pulled_image.image.Id
+          - remove_2.diff.before.tags | length == 4
+          - remove_2.diff.before.digests | length == 1
+          - remove_2.diff.after.id == pulled_image.image.Id
+          - remove_2.diff.after.tags | length == 3
+          - remove_2.diff.after.digests | length == 1
+          - remove_2.deleted | length == 0
+          - remove_2.untagged | length == 1
+          - remove_2.untagged[0] == iname_prefix ~ '-tagged-1:latest'
+          - remove_2_check.deleted == remove_2.deleted
+          - remove_2_check.untagged == remove_2.untagged
+          - info_2.images | length == 0
+
+    - name: Remove tagged image (idempotent, check mode)
+      docker_image_remove:
+        name: "{{ iname_prefix }}-tagged-1:latest"
+      register: remove_3_check
+      check_mode: true
+      diff: true
+
+    - name: Remove tagged image (idempotent)
+      docker_image_remove:
+        name: "{{ iname_prefix }}-tagged-1:latest"
+      register: remove_3
+      diff: true
+
+    - assert:
+        that:
+          - remove_3_check is not changed
+          - remove_3_check.diff == remove_3.diff
+          - remove_3 is not changed
+          - remove_3.diff.before.exists is false
+          - remove_3.diff.after.exists is false
+          - remove_3.deleted | length == 0
+          - remove_3.untagged | length == 0
+          - remove_3_check.deleted == remove_3.deleted
+          - remove_3_check.untagged == remove_3.untagged
+
+    - name: Inspect image with tag foo and bar
+      docker_image_info:
+        name:
+          - "{{ iname_prefix }}-tagged-1:foo"
+          - "{{ iname_prefix }}-tagged-1:bar"
+      register: info_3
+
+    - name: Remove tagged image (force, check mode)
+      docker_image_remove:
+        name: "{{ iname_prefix }}-tagged-1:foo"
+        force: true
+      register: remove_4_check
+      check_mode: true
+      diff: true
+
+    - name: Remove tagged image (force)
+      docker_image_remove:
+        name: "{{ iname_prefix }}-tagged-1:foo"
+        force: true
+      register: remove_4
+      diff: true
+
+    - name: Inspect image with tag foo and bar
+      docker_image_info:
+        name:
+          - "{{ iname_prefix }}-tagged-1:foo"
+          - "{{ iname_prefix }}-tagged-1:bar"
+      register: info_4
+
+    - assert:
+        that:
+          - remove_4_check is changed
+          - remove_4_check.diff == remove_4.diff
+          - remove_4 is changed
+          - remove_4.diff.before.id == pulled_image.image.Id
+          - remove_4.diff.before.tags | length == 3
+          - remove_4.diff.before.digests | length == 1
+          - remove_4.diff.after.id == pulled_image.image.Id
+          - remove_4.diff.after.tags | length == 2
+          - remove_4.diff.after.digests | length == 1
+          - remove_4.deleted | length == 0
+          - remove_4.untagged | length == 1
+          - remove_4.untagged[0] == iname_prefix ~ '-tagged-1:foo'
+          - remove_4_check.deleted == remove_4.deleted
+          - remove_4_check.untagged == remove_4.untagged
+          - info_3.images | length == 2
+          - info_3.images[0].Id == pulled_image.image.Id
+          - info_3.images[1].Id == pulled_image.image.Id
+          - info_4.images | length == 1
+          - info_4.images[0].Id == pulled_image.image.Id
+
+    - name: Remove image ID (force, idempotent, check mode)
+      docker_image_remove:
+        name: "{{ iname_prefix }}-tagged-1:foo"
+        force: true
+      register: remove_5_check
+      check_mode: true
+      diff: true
+
+    - name: Remove image ID (force, idempotent)
+      docker_image_remove:
+        name: "{{ iname_prefix }}-tagged-1:foo"
+        force: true
+      register: remove_5
+      diff: true
+
+    - assert:
+        that:
+          - remove_5_check is not changed
+          - remove_5_check.diff == remove_5.diff
+          - remove_5 is not changed
+          - remove_5.diff.before.exists is false
+          - remove_5.diff.after.exists is false
+          - remove_5.deleted | length == 0
+          - remove_5.untagged | length == 0
+          - remove_5_check.deleted == remove_5.deleted
+          - remove_5_check.untagged == remove_5.untagged
+
+    - name: Remove image ID (force, check mode)
+      docker_image_remove:
+        name: "{{ pulled_image.image.Id }}"
+        force: true
+      register: remove_6_check
+      check_mode: true
+      diff: true
+
+    - name: Remove image ID (force)
+      docker_image_remove:
+        name: "{{ pulled_image.image.Id }}"
+        force: true
+      register: remove_6
+      diff: true
+
+    - name: Inspect image with tag foo and bar
+      docker_image_info:
+        name:
+          - "{{ iname_prefix }}-tagged-1:foo"
+          - "{{ iname_prefix }}-tagged-1:bar"
+      register: info_5
+
+    - assert:
+        that:
+          - remove_6_check is changed
+          - remove_6_check.diff == remove_6.diff
+          - remove_6 is changed
+          - remove_6.diff.before.id == pulled_image.image.Id
+          - remove_6.diff.before.tags | length == 2
+          - remove_6.diff.before.digests | length == 1
+          - remove_6.diff.after.exists is false
+          - remove_6.deleted | length > 1
+          - pulled_image.image.Id in remove_6.deleted
+          - remove_6.untagged | length == 3
+          - (iname_prefix ~ '-tagged-1:bar') in remove_6.untagged
+          - image in remove_6.untagged
+          - remove_6_check.deleted | length == 1
+          - remove_6_check.deleted[0] == pulled_image.image.Id
+          - remove_6_check.untagged == remove_6.untagged
+          - info_5.images | length == 0
+
+    - name: Remove image ID (force, idempotent, check mode)
+      docker_image_remove:
+        name: "{{ pulled_image.image.Id }}"
+        force: true
+      register: remove_7_check
+      check_mode: true
+      diff: true
+
+    - name: Remove image ID (force, idempotent)
+      docker_image_remove:
+        name: "{{ pulled_image.image.Id }}"
+        force: true
+      register: remove_7
+      diff: true
+
+    - assert:
+        that:
+          - remove_7_check is not changed
+          - remove_7_check.diff == remove_7.diff
+          - remove_7 is not changed
+          - remove_7.diff.before.exists is false
+          - remove_7.diff.after.exists is false
+          - remove_7.deleted | length == 0
+          - remove_7.untagged | length == 0
+          - remove_7_check.deleted == remove_7.deleted
+          - remove_7_check.untagged == remove_7.untagged
+
+  always:
+    - name: Remove tagged images
+      docker_image_remove:
+        name: "{{ item }}"
+      loop: "{{ image_names }}"
+
+  when: docker_api_version is version('1.25', '>=')
+
+- fail: msg="Too old docker / docker-py version to run docker_image_info tests!"
+  when: not(docker_api_version is version('1.25', '>=')) and (ansible_distribution != 'CentOS' or ansible_distribution_major_version|int > 6)

tests/integration/targets/docker_image_tag/tasks/main.yml

@@ -35,10 +35,8 @@
       diff: true
 
     - name: Remove tagged images
-      docker_image:
+      docker_image_remove:
         name: "{{ item }}"
-        source: local
-        state: absent
       loop: "{{ image_names }}"
 
     - name: Tag image 1 (check mode)
@@ -394,10 +392,8 @@
 
   always:
     - name: Remove tagged images
-      docker_image:
+      docker_image_remove:
         name: "{{ item }}"
-        source: local
-        state: absent
       loop: "{{ image_names }}"
 
   when: docker_api_version is version('1.25', '>=')

tests/integration/targets/setup_docker/vars/main.yml

@@ -9,6 +9,7 @@ docker_test_image_digest_v2: ee44b399df993016003bf5466bd3eeb221305e9d0fa831606bc
 docker_test_image_digest_v2_image_id: dc3bacd8b5ea796cea5d6070c8f145df9076f26a6bc1c8981fd5b176d37de843
 docker_test_image_digest_base: quay.io/ansible/docker-test-containers
 docker_test_image_hello_world: quay.io/ansible/docker-test-containers:hello-world
+docker_test_image_hello_world_image_id: sha256:bf756fb1ae65adf866bd8c456593cd24beb6a0a061dedf42b26a993176745f6b
 docker_test_image_hello_world_base: quay.io/ansible/docker-test-containers
 docker_test_image_hello_world_platform: docker.io/library/hello-world:latest
 docker_test_image_busybox: quay.io/ansible/docker-test-containers:busybox

tests/integration/targets/setup_docker_registry/handlers/cleanup.yml

@@ -4,9 +4,8 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 - name: "Make sure all images are removed"
-  docker_image:
+  docker_image_remove:
     name: "{{ item }}"
-    state: absent
   with_items: "{{ docker_registry_setup_inames }}"
 
 - name: "Get registry logs"