[docker] support the lookup of images by digest (#56649)

* [docker] images: add support for lookup by sha256 digest

Signed-off-by: Jakob Ackermann <das7pad@outlook.com>

* [tests] docker image by digest: work on a minimal test case

Signed-off-by: Jakob Ackermann <das7pad@outlook.com>

* [docker] group branch conditions per lookup

Co-Authored-By: Felix Fontein <felix@fontein.de>

* [misc] add a news fragment for the added digest lookup for docker images

Signed-off-by: Jakob Ackermann <das7pad@outlook.com>

changelogs/fragments/56649-docker-image-lookup-by-digest.yml

@@ -0,0 +1,4 @@
+bugfixes:
+  - docker_container - Add support for image lookups by digest. Fixes the detection of digest changes.
+  - docker_image - Add support for image lookups by digest. Fixes the detection of digest changes.
+  - docker_image_info - Add support for image lookups by digest. Fixes the detection of digest changes.

lib/ansible/module_utils/docker/common.py

@@ -639,10 +639,12 @@ class AnsibleDockerClient(Client):
         images = response
         if tag:
             lookup = "%s:%s" % (name, tag)
+            lookup_digest = "%s@%s" % (name, tag)
             images = []
             for image in response:
                 tags = image.get('RepoTags')
-                if tags and lookup in tags:
+                digests = image.get('RepoDigests')
+                if (tags and lookup in tags) or (digests and lookup_digest in digests):
                     images = [image]
                     break
         return images

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

@@ -76,3 +76,45 @@
       - create_2 is not changed
       - create_3 is changed
       - create_4 is not changed
+
+- name: set Digests
+  set_fact:
+    digest_hello_world_2016: 0256e8a36e2070f7bf2d0b0763dbabdd67798512411de4cdcf9431a1feb60fd9
+    digest_hello_world_2019: 2557e3c07ed1e38f26e389462d03ed943586f744621577a99efb77324b0fe535
+
+- name: Create container with hello-world image via old digest
+  docker_container:
+    image: "hello-world@sha256:{{ digest_hello_world_2016 }}"
+    name: "{{ cname }}"
+    state: present
+    force_kill: yes
+  register: digest_1
+
+- name: Create container with hello-world image via old digest (idempotent)
+  docker_container:
+    image: "hello-world@sha256:{{ digest_hello_world_2016 }}"
+    name: "{{ cname }}"
+    state: present
+    force_kill: yes
+  register: digest_2
+
+- name: Update container with hello-world image via new digest
+  docker_container:
+    image: "hello-world@sha256:{{ digest_hello_world_2019 }}"
+    name: "{{ cname }}"
+    state: present
+    force_kill: yes
+  register: digest_3
+
+- name: Cleanup
+  docker_container:
+    name: "{{ cname }}"
+    state: absent
+    force_kill: yes
+  diff: no
+
+- assert:
+    that:
+      - digest_1 is changed
+      - digest_2 is not changed
+      - digest_3 is changed