docker_host_info - Allow filters which are passed as lists (#160)

* Initial Commit

* Adding integration tests

* Adding example in docs

* Adding changelog fragment

* Applying initial review suggestions

changelogs/fragments/160-docker_host_info-label-fitler-lists.yml

@@ -0,0 +1,4 @@
+---
+minor_changes:
+  - docker_host_info - allow values for keys in ``containers_filters``, ``images_filters``, ``networks_filters``, and
+    ``volumes_filters`` to be passed as YAML lists (https://github.com/ansible-collections/community.docker/pull/160).

plugins/module_utils/common.py

@@ -15,6 +15,7 @@ from distutils.version import LooseVersion
 
 
 from ansible.module_utils.basic import AnsibleModule, env_fallback, missing_required_lib
+from ansible.module_utils.common.collections import is_sequence
 from ansible.module_utils.common._collections_compat import Mapping, Sequence
 from ansible.module_utils.six import string_types
 from ansible.module_utils.six.moves.urllib.parse import urlparse
@@ -927,23 +928,27 @@ class DifferenceTracker(object):
         return result
 
 
-def clean_dict_booleans_for_docker_api(data):
+def clean_dict_booleans_for_docker_api(data, allow_sequences=False):
     '''
     Go doesn't like Python booleans 'True' or 'False', while Ansible is just
     fine with them in YAML. As such, they need to be converted in cases where
     we pass dictionaries to the Docker API (e.g. docker_network's
-    driver_options and docker_prune's filters).
+    driver_options and docker_prune's filters). When `allow_sequences=True`
+    YAML sequences (lists, tuples) are converted to [str] instead of str([...])
+    which is the expected format of filters which accept lists such as labels.
     '''
+    def sanitize(value):
+        if value is True:
+            return 'true'
+        elif value is False:
+            return 'false'
+        else:
+            return str(value)
+
     result = dict()
     if data is not None:
         for k, v in data.items():
-            if v is True:
-                v = 'true'
-            elif v is False:
-                v = 'false'
-            else:
-                v = str(v)
-            result[str(k)] = v
+            result[str(k)] = [sanitize(e) for e in v] if allow_sequences and is_sequence(v) else sanitize(v)
     return result
 
 

plugins/modules/docker_host_info.py

@@ -33,6 +33,8 @@ options:
     description:
       - A dictionary of filter values used for selecting containers to list.
       - "For example, C(until: 24h)."
+      - C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
+        C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
       - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/container_prune/#filtering)
         for more information on possible filters.
     type: dict
@@ -45,6 +47,8 @@ options:
     description:
       - A dictionary of filter values used for selecting images to list.
       - "For example, C(dangling: true)."
+      - C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
+        C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
       - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/image_prune/#filtering)
         for more information on possible filters.
     type: dict
@@ -56,6 +60,8 @@ options:
   networks_filters:
     description:
       - A dictionary of filter values used for selecting networks to list.
+      - C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
+        C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
       - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/network_prune/#filtering)
         for more information on possible filters.
     type: dict
@@ -67,6 +73,8 @@ options:
   volumes_filters:
     description:
       - A dictionary of filter values used for selecting volumes to list.
+      - C(label) is a special case of filter which can be a string C(<key>) matching when a label is present, a string
+        C(<key>=<value>) matching when a label has a particular value, or a list of strings C(<key>)/C(<key>=<value).
       - See L(the docker documentation,https://docs.docker.com/engine/reference/commandline/volume_prune/#filtering)
         for more information on possible filters.
     type: dict
@@ -126,6 +134,15 @@ EXAMPLES = '''
     disk_usage: yes
   register: result
 
+- name: Get info on docker host and list containers matching the filter
+  community.docker.docker_host_info:
+    containers: yes
+    containers_filters:
+      label:
+        - key1=value1
+        - key2=value2
+  register: result
+
 - ansible.builtin.debug:
     var: result.host_info
 
@@ -223,7 +240,7 @@ class DockerHostManager(DockerBaseClass):
             if self.client.module.params[docker_object]:
                 returned_name = docker_object
                 filter_name = docker_object + "_filters"
-                filters = clean_dict_booleans_for_docker_api(client.module.params.get(filter_name))
+                filters = clean_dict_booleans_for_docker_api(client.module.params.get(filter_name), True)
                 self.results[returned_name] = self.get_docker_items_list(docker_object, filters)
 
     def get_docker_host_info(self):

tests/integration/targets/docker_host_info/tasks/test_host_info.yml

@@ -31,6 +31,9 @@
       image: "{{ docker_test_image_alpine }}"
       command: '/bin/sh -c "sleep 10m"'
       name: "{{ cname }}"
+      labels:
+        key1: value1
+        key2: value2
       state: started
     register: container_output
 
@@ -63,6 +66,44 @@
          - 'output.containers[0].Image is string'
          - 'output.containers[0].ImageID is not defined'
 
+  - name: Get info on Docker host and list containers matching filters (single label)
+    docker_host_info:
+      containers: yes
+      containers_filters:
+        label: key1=value1
+    register: output
+
+  - name: assert container is returned when filters are matched (single label)
+    assert:
+      that: "{{ output.containers | length }} == 1"
+
+  - name: Get info on Docker host and list containers matching filters (multiple labels)
+    docker_host_info:
+      containers: yes
+      containers_filters:
+        label:
+          - key1=value1
+          - key2=value2
+    register: output
+
+  - name: assert container is returned when filters are matched (multiple labels)
+    assert:
+      that: "{{ output.containers | length }} == 1"
+
+  - name: Get info on Docker host and do not list containers which do not match filters
+    docker_host_info:
+      containers: yes
+      containers_filters:
+        label:
+          - key1=value1
+          - key2=value2
+          - key3=value3
+    register: output
+
+  - name: assert no container is returned when filters are not matched
+    assert:
+      that: "{{ output.containers | length }} == 0"
+
   - name: Get info on Docker host and list containers with verbose output
     docker_host_info:
       containers: yes