Debugging modules

    • Set a breakpoint in the module: import pdb; pdb.set_trace()
    • Run the module on the local machine: $ python -m pdb ./my_new_test_module.py ./args.json

    To debug a module running on a remote target (i.e. not localhost):

    • Run your playbook targeting the remote machine and specify -vvvv (verbose) to display the remote location Ansible is using for the modules (among many other things).
    • Take note of the directory Ansible used to store modules on the remote host. This directory is usually under the home directory of your ansible_ssh_user, in the form ~/.ansible/tmp/ansible-tmp-….
    • SSH into the remote target after the playbook runs.
    • Navigate to the directory you noted in step 3.
    • Extract the module you want to debug from the zipped file that Ansible sent to the remote host: $ python my_test_module.py explode. Ansible will expand the module into ./debug-dir. You can optionally run the zipped file by specifying python my_test_module.py.
    • Modify or set a breakpoint in .
    • Ensure that the unzipped module is executable: $ chmod 755 ansible_module_my_test_module.py.
    • Run the unzipped module directly, passing the args file that contains the params that were originally passed: $ ./ansible_module_my_test_module.py args. This approach is good for reproducing behavior as well as modifying the parameters for debugging.

    Tip

    If you’re using the hacking/test-module script then most of thisis taken care of for you. If you need to do some debugging of the moduleon the remote machine that the module will actually run on or when themodule is used in a playbook then you may need to use this informationinstead of relying on test-module.

    If you are using Ansible with the environment variables to keep the remote module file, here’s a sample of howyour debugging session will start:

    Setting ANSIBLE_KEEP_REMOTE_FILES to 1 tells Ansible to keep theremote module files instead of deleting them after the module finishesexecuting. Giving Ansible the -vvv option makes Ansible more verbose.That way it prints the file name of the temporary module file for you to see.

    If you want to examine the wrapper file you can. It will show a small pythonscript with a large, base64 encoded string. The string contains the modulethat is going to be executed. Run the wrapper’s explode command to turn thestring into some python files that you can work with:

    • ansible_module_ping.py is the code for the module itself. The nameis based on the name of the module with a prefix so that we don’t clash withany other python module names. You can modify this code to see what effectit would have on your module.
    • The args file contains a JSON string. The string is a dictionarycontaining the module arguments and other variables that Ansible passes intothe module to change its behaviour. If you want to modify the parametersthat are passed to the module, this is the file to do it in.

    Once you edit the code or arguments in the exploded tree you need some way torun it. There’s a separate wrapper subcommand for this:

    This subcommand takes care of setting the PYTHONPATH to use the explodeddebug_dir/ansible/module_utils directory and invoking the script usingthe arguments in the args file. You can continue to run it like thisuntil you understand the problem. Then you can copy it back into your realmodule file and test that the real module works via ansible oransible-playbook.

    Note