Add debug strategy plugin (#15125)

* Add debug strategy plugin

* Fix Python 2-3 compatiblity issue

* Add document for debug strategy

3 files changed, 162 insertions, 0 deletions

diff --git a/docsite/rst/playbooks_debugger.rst b/docsite/rst/playbooks_debugger.rst
new file mode 100644
index 0000000000..dc22d7b9a4
--- /dev/null
+++ b/docsite/rst/playbooks_debugger.rst
@@ -0,0 +1,159 @@
+Playbook Debugger
+=================
+
+.. contents:: Topics
+
+In 2.1 we added a ``debug`` strategy. This strategy enables you to invoke a debugger when a task is
+failed, and check several info, such as the value of a variable. Also, it is possible to update module
+arguments in the debugger, and run the failed task again with new arguments to consider how you
+can fix an issue.
+
+To use ``debug`` strategy, change ``strategy`` attribute like this::
+
+    - hosts: test
+      strategy: debug
+      tasks:
+      ...
+
+For example, run the playbook below::
+
+    - hosts: test
+      strategy: debug
+      gather_facts: no
+      vars:
+        var1: value1
+      tasks:
+        - name: wrong variable
+          ping: data={{ wrong_var }}
+
+The debugger is invoked since *wrong_var* variable is undefined. Let's change the module's args,
+and run the task again::
+
+    PLAY ***************************************************************************
+
+    TASK [wrong variable] **********************************************************
+    fatal: [192.168.1.1]: FAILED! => {"failed": true, "msg": "ERROR! 'wrong_var' is undefined"}
+    Debugger invoked
+    (debug) p result
+    {'msg': u"ERROR! 'wrong_var' is undefined", 'failed': True}
+    (debug) p task.args
+    {u'data': u'{{ wrong_var }}'}
+    (debug) task.args['data'] = '{{ var1 }}'
+    (debug) p task.args
+    {u'data': '{{ var1 }}'}
+    (debug) redo
+    ok: [192.168.1.1]
+
+    PLAY RECAP *********************************************************************
+    192.168.1.1               : ok=1    changed=0    unreachable=0    failed=0
+
+This time, the task runs successfully!
+
+.. _available_commands:
+
+Available Commands
+++++++++++++++++++
+
+.. _p_command:
+
+p *task/vars/host/result*
+`````````````````````````
+
+Print values used to execute a module::
+
+    (debug) p task
+    TASK: install package
+    (debug) p task.args
+    {u'name': u'{{ pkg_name }}'}
+    (debug) p vars
+    {u'ansible_all_ipv4_addresses': [u'192.168.1.1'],
+     u'ansible_architecture': u'x86_64',
+     ...
+    }
+    (debug) p vars['pkg_name']
+    u'bash'
+    (debug) p host
+    192.168.1.1
+    (debug) p result
+    {'_ansible_no_log': False,
+     'changed': False,
+     u'failed': True,
+     ...
+     u'msg': u"No package matching 'not_exist' is available"}
+
+.. _update_args_command:
+
+task.args[*key*] = *value*
+``````````````````````````
+
+Update module's argument.
+
+If you run a playbook like this::
+
+    - hosts: test
+      strategy: debug
+      gather_facts: yes
+      vars:
+        pkg_name: not_exist
+      tasks:
+        - name: install package
+          apt: name={{ pkg_name }}
+
+Debugger is invoked due to wrong package name, so let's fix the module's args::
+
+    (debug) p task.args
+    {u'name': u'{{ pkg_name }}'}
+    (debug) task.args['name'] = 'bash'
+    (debug) p task.args
+    {u'name': 'bash'}
+    (debug) redo
+
+Then the task runs again with new args.
+
+.. _update_vars_command:
+
+vars[*key*] = *value*
+`````````````````````
+
+Update vars.
+
+Let's use the same playbook above, but fix vars instead of args::
+
+    (debug) p vars['pkg_name']
+    u'not_exist'
+    (debug) vars['pkg_name'] = 'bash'
+    (debug) p vars['pkg_name']
+    'bash'
+    (debug) redo
+
+Then the task runs again with new vars.
+
+.. _redo_command:
+
+r(edo)
+``````
+
+Run the task again.
+
+.. _continue_command:
+
+c(ontinue)
+``````````
+
+Just continue.
+
+.. _quit_command:
+
+q(uit)
+``````
+
+Quit from the debugger. The playbook execution is aborted.
+
+.. seealso::
+
+   :doc:`playbooks`
+       An introduction to playbooks
+   `User Mailing List <http://groups.google.com/group/ansible-devel>`_
+       Have a question?  Stop by the google group!
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible IRC chat channel
diff --git a/docsite/rst/playbooks_special_topics.rst b/docsite/rst/playbooks_special_topics.rst
index 6593d20a54..3e31d38e22 100644
--- a/docsite/rst/playbooks_special_topics.rst
+++ b/docsite/rst/playbooks_special_topics.rst
@@ -11,6 +11,7 @@ and adopt these only if they seem relevant or useful to your environment.
    playbooks_acceleration
    playbooks_async
    playbooks_checkmode
+   playbooks_debugger
    playbooks_delegation
    playbooks_environment
    playbooks_error_handling
diff --git a/docsite/rst/playbooks_strategies.rst b/docsite/rst/playbooks_strategies.rst
index a9095bc083..a34daa1c1f 100644
--- a/docsite/rst/playbooks_strategies.rst
+++ b/docsite/rst/playbooks_strategies.rst
@@ -26,6 +26,8 @@ The strategies are implemented via a new type of plugin, this means that in the
 execution types can be added, either locally by users or to Ansible itself by
 a code contribution.
 
+One example is ``debug`` strategy. See :doc:`playbooks_debugger` for details.
+
 .. seealso::
 
    :doc:`playbooks`