Make sure that 'container' is returned in more circumstances, and improve documentation when it is actually returned

changelogs/fragments/178-docker_container-container.yml

@@ -0,0 +1,2 @@
+bugfixes:
+- "docker_container - make sure to also return ``container`` on ``detached=false`` when status code is non-zero (https://github.com/ansible-collections/community.docker/pull/178)."

plugins/modules/docker_container.py

@@ -1139,11 +1139,9 @@
 container:
     description:
       - Facts representing the current state of the container. Matches the docker inspection output.
-      - Before 2.3 this was C(ansible_docker_container) but was renamed in 2.3 to C(docker_container) due to
-        conflicts with the connection plugin.
-      - Empty if I(state) is C(absent)
-      - If I(detached) is C(false), will include C(Output) attribute containing any output from container run.
-    returned: always
+      - Empty if I(state) is C(absent).
+      - If I(detach=false), will include C(Output) attribute containing any output from container run.
+    returned: success; or when I(state=started) and I(detach=false), and when waiting for the container result did not fail
     type: dict
     sample: '{
         "AppArmorProfile": "",
@@ -1181,7 +1179,7 @@
     description:
       - In case a container is started without detaching, this contains the exit code of the process in the container.
       - Before community.docker 1.1.0, this was only returned when non-zero.
-    returned: when I(state) is C(started) and I(detached) is C(false), and when waiting for the container result did not fail
+    returned: when I(state=started) and I(detach=false), and when waiting for the container result did not fail
     type: int
     sample: 0
 '''
@@ -3104,15 +3102,17 @@ def container_start(self, container_id):
                     else:
                         output = "Result logged using `%s` driver" % logging_driver
 
-                if status != 0:
-                    self.fail(output)
                 if self.parameters.cleanup:
                     self.container_remove(container_id, force=True)
                 insp = self._get_container(container_id)
                 if insp.raw:
                     insp.raw['Output'] = output
                 else:
                     insp.raw = dict(Output=output)
+                if status != 0:
+                    # Set `failed` to True and return output as msg
+                    self.results['failed'] = True
+                    self.results['msg'] = output
                 return insp
         return self._get_container(container_id)
 

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

@@ -615,6 +615,16 @@
   register: detach_auto_remove_cleanup
   diff: no
 
+- name: detach with cleanup and non-zero status
+  docker_container:
+    name: "{{ cname }}"
+    image: "{{ docker_test_image_alpine }}"
+    command: '/bin/sh -c "exit 42"'
+    detach: no
+    cleanup: yes
+  register: detach_cleanup_nonzero
+  ignore_errors: true
+
 - assert:
     that:
     # NOTE that 'Output' sometimes fails to contain the correct output
@@ -629,6 +639,10 @@
     - detach_cleanup.status == 0
     # - "'Hello from Docker!' in detach_cleanup.container.Output"
     - detach_cleanup_cleanup is not changed
+    - detach_cleanup_nonzero is failed
+    - detach_cleanup_nonzero.status == 42
+    - "'Output' in detach_cleanup_nonzero.container"
+    - "detach_cleanup_nonzero.container.Output == ''"
 - assert:
     that:
     - "'Cannot retrieve result as auto_remove is enabled' == detach_auto_remove.container.Output"