Improve ignore_unreachable documentation (#64938)

docs/docsite/keyword_desc.yml

@@ -37,7 +37,7 @@ gather_timeout: Allows you to set the timeout for the fact gathering plugin cont
 handlers: "A section with tasks that are treated as handlers, these won't get executed normally, only when notified after each section of tasks is complete. A handler's `listen` field is not templatable."
 hosts: "A list of groups, hosts or host pattern that translates into a list of hosts that are the play's target."
 ignore_errors: Boolean that allows you to ignore task failures and continue with play. It does not affect connection errors.
-ignore_unreachable: Boolean that allows you to ignore unreachable hosts and continue with play. This does not affect other task errors (see :term:`ignore_errors`) but is useful for groups of volatile/ephemeral hosts.
+ignore_unreachable: Boolean that allows you to ignore task failures due to an unreachable host and continue with the play. This does not affect other task errors (see :term:`ignore_errors`) but is useful for groups of volatile/ephemeral hosts.
 loop: "Takes a list for the task to iterate over, saving each list element into the ``item`` variable (configurable via loop_control)"
 loop_control: |
     Several keys here allow you to modify/set loop behaviour in a task.

docs/docsite/rst/user_guide/playbooks_error_handling.rst

@@ -28,6 +28,35 @@ so if you have an undefined variable used or a syntax error, it will still raise
 Note that this will not prevent failures on connection or execution issues.
 This feature only works when the task must be able to run and return a value of 'failed'.
 
+Ignoring Unreachable Host Errors
+````````````````````````````````````````
+
+.. versionadded:: 2.7
+
+You may ignore task failure due to the host instance being 'UNREACHABLE' with the ``ignore_unreachable`` keyword.
+Note that task errors are what's being ignored, not the unreachable host.
+
+Here's an example explaining the behavior for an unreachable host at the task level::
+
+    - name: this executes, fails, and the failure is ignored
+      command: /bin/true
+      ignore_unreachable: yes
+
+    - name: this executes, fails, and ends the play for this host
+      command: /bin/true
+
+And at the playbook level::
+
+    - hosts: all
+      ignore_unreachable: yes
+      tasks:
+      - name: this executes, fails, and the failure is ignored
+        command: /bin/true
+
+      - name: this executes, fails, and ends the play for this host
+        command: /bin/true
+        ignore_unreachable: no
+
 .. _resetting_unreachable:
 
 Resetting Unreachable Hosts