diff options
Diffstat (limited to 'docsite')
-rw-r--r-- | docsite/rst/playbooks_debugger.rst | 159 | ||||
-rw-r--r-- | docsite/rst/playbooks_special_topics.rst | 1 | ||||
-rw-r--r-- | docsite/rst/playbooks_strategies.rst | 2 |
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` |