docker: provide alternatives to ansible_facts results (#51192)

* Try to stop using ansible_facts for docker modules.

* Stop using facts returned from regular modules.

changelogs/fragments/docker-facts.yaml

@@ -0,0 +1,6 @@
+minor_changes:
+- "docker_container, docker_network, docker_volume - return facts as regular variable additionally to
+   facts. This is now the preferred way to obtain results."
+- "docker_service - return facts as regular variable ``service_facts``; this is a dictionary mapping
+   service names to container dictionaries. The facts are still returned, but it is recommended to
+   use ``register`` and ``service_facts`` in the future."

lib/ansible/modules/cloud/docker/docker_compose.py

@@ -293,8 +293,12 @@ EXAMPLES = '''
 '''
 
 RETURN = '''
-service:
+service_facts:
-  description: Name of the service.
+  description:
+  - A dictionary mapping the service's name to a dictionary of containers.
+  - Note that facts are part of the registered vars since Ansible 2.8. For compatibility reasons, the facts
+    are also accessible directly. The service's name is the variable with which the container dictionary
+    can be accessed.
   returned: success
   type: complex
   contains:
@@ -673,7 +677,7 @@ class ContainerManager(DockerBaseClass):
         start_deps = self.dependencies
         service_names = self.services
         detached = True
-        result = dict(changed=False, actions=[], ansible_facts=dict())
+        result = dict(changed=False, actions=[], ansible_facts=dict(), service_facts=dict())
 
         up_options = {
             u'--no-recreate': False,
@@ -757,7 +761,9 @@ class ContainerManager(DockerBaseClass):
             result['actions'] += scale_output['actions']
 
         for service in self.project.services:
-            result['ansible_facts'][service.name] = dict()
+            service_facts = dict()
+            result['ansible_facts'][service.name] = service_facts
+            result['service_facts'][service.name] = service_facts
             for container in service.containers(stopped=True):
                 inspection = container.inspect()
                 # pare down the inspection data to the most useful bits
@@ -809,7 +815,7 @@ class ContainerManager(DockerBaseClass):
                         if networks[key].get('MacAddress', None) is not None:
                             facts['networks'][key]['macAddress'] = networks[key]['MacAddress']
 
-                result['ansible_facts'][service.name][container.name] = facts
+                service_facts[container.name] = facts
 
         return result
 

lib/ansible/modules/cloud/docker/docker_container.py

@@ -821,7 +821,8 @@ docker_container:
     description:
       - Before 2.3 this was 'ansible_docker_container' but was renamed due to conflicts with the connection plugin.
       - Facts representing the current state of the container. Matches the docker inspection output.
-      - Note that facts are not part of registered vars but accessible directly.
+      - Note that facts are part of the registered vars since Ansible 2.8. For compatibility reasons, the facts
+        are also accessible directly.
       - Empty if C(state) is I(absent)
       - If detached is I(False), will include Output attribute containing any output from container run.
     returned: always
@@ -2196,6 +2197,7 @@ class ContainerManager(DockerBaseClass):
 
         if self.facts:
             self.results['ansible_facts'] = {'docker_container': self.facts}
+            self.results['docker_container'] = self.facts
 
     def present(self, state):
         container = self._get_container(self.parameters.name)

lib/ansible/modules/cloud/docker/docker_network.py

@@ -246,8 +246,11 @@ EXAMPLES = '''
 '''
 
 RETURN = '''
-facts:
+docker_network:
-    description: Network inspection results for the affected network.
+    description:
+    - Network inspection results for the affected network.
+    - Note that facts are part of the registered vars since Ansible 2.8. For compatibility reasons, the facts
+      are also accessible directly.
     returned: success
     type: dict
     sample: {}
@@ -575,7 +578,9 @@ class DockerNetworkManager(object):
         if not self.check_mode and not self.parameters.debug:
             self.results.pop('actions')
 
-        self.results['ansible_facts'] = {u'docker_network': self.get_existing_network()}
+        network_facts = self.get_existing_network()
+        self.results['ansible_facts'] = {u'docker_network': network_facts}
+        self.results['docker_network'] = network_facts
 
     def absent(self):
         self.diff_tracker.add('exists', parameter=False, active=self.existing_network is not None)

lib/ansible/modules/cloud/docker/docker_volume.py

@@ -113,8 +113,11 @@ EXAMPLES = '''
 '''
 
 RETURN = '''
-facts:
+docker_volume:
-    description: Volume inspection results for the affected volume.
+    description:
+    - Volume inspection results for the affected volume.
+    - Note that facts are part of the registered vars since Ansible 2.8. For compatibility reasons, the facts
+      are also accessible directly.
     returned: success
     type: dict
     sample: {}
@@ -284,7 +287,9 @@ class DockerVolumeManager(object):
         if not self.check_mode and not self.parameters.debug:
             self.results.pop('actions')
 
-        self.results['ansible_facts'] = {u'docker_volume': self.get_existing_volume()}
+        volume_facts = self.get_existing_volume()
+        self.results['ansible_facts'] = {u'docker_volume': volume_facts}
+        self.results['docker_volume'] = volume_facts
 
     def absent(self):
         self.diff_tracker.add('exists', parameter=False, active=self.existing_volume is not None)

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

@@ -543,15 +543,15 @@
     #      of hello-world. We don't know why this happens, but it happens
     #      often enough to be annoying. That's why we disable this for now,
     #      and simply test that 'Output' is contained in the result.
-    - "'Output' in detach_no_cleanup.ansible_facts.docker_container"
+    - "'Output' in detach_no_cleanup.docker_container"
-    # - "'Hello from Docker!' in detach_no_cleanup.ansible_facts.docker_container.Output"
+    # - "'Hello from Docker!' in detach_no_cleanup.docker_container.Output"
     - detach_no_cleanup_cleanup is changed
-    - "'Output' in detach_cleanup.ansible_facts.docker_container"
+    - "'Output' in detach_cleanup.docker_container"
-    # - "'Hello from Docker!' in detach_cleanup.ansible_facts.docker_container.Output"
+    # - "'Hello from Docker!' in detach_cleanup.docker_container.Output"
     - detach_cleanup_cleanup is not changed
 - assert:
     that:
-    - "'Cannot retrieve result as auto_remove is enabled' == detach_auto_remove.ansible_facts.docker_container.Output"
+    - "'Cannot retrieve result as auto_remove is enabled' == detach_auto_remove.docker_container.Output"
     - detach_auto_remove_cleanup is not changed
   when: docker_py_version is version('2.1.0', '>=')
 
@@ -2373,7 +2373,7 @@
     - memory_swap_1 is changed
     # Sometimes (in particular during integration tests, maybe when not running
     # on a proper VM), memory_swap cannot be set and will be -1 afterwards.
-    - memory_swap_2 is not changed or memory_swap_2.ansible_facts.docker_container.HostConfig.MemorySwap == -1
+    - memory_swap_2 is not changed or memory_swap_2.docker_container.HostConfig.MemorySwap == -1
     - memory_swap_3 is changed
 
 - debug: var=memory_swap_1
@@ -2775,7 +2775,7 @@
     command: '/bin/sh -c "sleep 10m"'
     name: "{{ cname }}"
     state: started
-    pid_mode: "container:{{ pid_mode_helper.ansible_facts.docker_container.Id }}"
+    pid_mode: "container:{{ pid_mode_helper.docker_container.Id }}"
   register: pid_mode_1
   ignore_errors: yes
   # docker-py < 2.0 does not support "arbitrary" pid_mode values
@@ -3098,9 +3098,9 @@
     - recreate_2 is changed
     - recreate_3 is changed
     - recreate_4 is changed
-    - recreate_1.ansible_facts.docker_container.Id != recreate_2.ansible_facts.docker_container.Id
+    - recreate_1.docker_container.Id != recreate_2.docker_container.Id
-    - recreate_2.ansible_facts.docker_container.Id == recreate_3.ansible_facts.docker_container.Id
+    - recreate_2.docker_container.Id == recreate_3.docker_container.Id
-    - recreate_3.ansible_facts.docker_container.Id != recreate_4.ansible_facts.docker_container.Id
+    - recreate_3.docker_container.Id != recreate_4.docker_container.Id
 
 ####################################################################
 ## restart #########################################################
@@ -3139,7 +3139,7 @@
     that:
     - restart_1 is changed
     - restart_2 is changed
-    - restart_1.ansible_facts.docker_container.Id == restart_2.ansible_facts.docker_container.Id
+    - restart_1.docker_container.Id == restart_2.docker_container.Id
 
 ####################################################################
 ## restart_policy ##################################################

test/integration/targets/docker_prune/tasks/main.yml

@@ -35,14 +35,14 @@
   - assert:
       that:
       # containers
-      - container.ansible_facts.docker_container.Id in result.containers
+      - container.docker_container.Id in result.containers
       - "'containers_space_reclaimed' in result"
       # images
       - "'images_space_reclaimed' in result"
       # networks
-      - network.ansible_facts.docker_network.Name in result.networks
+      - network.docker_network.Name in result.networks
       # volumes
-      - volume.ansible_facts.docker_volume.Name in result.volumes
+      - volume.docker_volume.Name in result.volumes
       - "'volumes_space_reclaimed' in result"
       # builder_cache
       - "'builder_cache_space_reclaimed' in result"