From 756ac826fe31666116d96ece2d07f9f9b4dd26af Mon Sep 17 00:00:00 2001 From: Andrew Schultz Date: Tue, 26 Nov 2019 10:35:02 -0800 Subject: [PATCH] Improve ignore_unreachable documentation (#64938) --- docs/docsite/keyword_desc.yml | 2 +- .../user_guide/playbooks_error_handling.rst | 29 +++++++++++++++++++ 2 files changed, 30 insertions(+), 1 deletion(-) diff --git a/docs/docsite/keyword_desc.yml b/docs/docsite/keyword_desc.yml index d0e50cd3c70..361242d959a 100644 --- a/docs/docsite/keyword_desc.yml +++ b/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. diff --git a/docs/docsite/rst/user_guide/playbooks_error_handling.rst b/docs/docsite/rst/user_guide/playbooks_error_handling.rst index 6349f8cec44..c215cc5ed7f 100644 --- a/docs/docsite/rst/user_guide/playbooks_error_handling.rst +++ b/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