=========
 Ansible
=========
.. contents::
   :local:

Debugging Ansible
=================

Pass ``-vvv`` to Ansible utilities::

  ansible -vvv ...
  ansible-playbook -vvv ...

To debug connection use ``-vvvv``::

  ansible -vvvv ...

Print variable value with task ``debug``::

  - debug: var=ansible_host
  - debug:
      var: ansible_host
  - debug:
      msg: "host is {{ ansible_host }}"

To debug Python modules set ``ANSIBLE_KEEP_REMOTE_FILES`` to ``1`` (it causes Ansible to leave the
exact copy of the Python scripts it executed on the target machine)::

  ANSIBLE_KEEP_REMOTE_FILES=1  ansible ...

There is ``debugger`` keyword that triggers debugger, see `Ansible Debugger
<https://docs.ansible.com/ansible/latest/user_guide/playbooks_debugger.html>`_

To activate debugger on task::

  - name: Execute a command
    command: false
    debugger: on_failed

To activate debugger in ``ansible.cfg``::

  [defaults]
  enable_task_debugger = True

To activate debugger via env var::

  ANSIBLE_ENABLE_TASK_DEBUGGER=True ansible-playbook -i hosts site.yml

Use ``ansible-lint``::

  $ sudo apt install ansible-lint
  $ ansible-lint site.yml

https://docs.ansible.com/ansible/latest/network/user_guide/network_debug_troubleshooting.html
  Network Debug and Troubleshooting Guide.
https://stackoverflow.com/questions/42417079/how-to-debug-ansible-issues
  How to debug Ansible issues?

Bash completion
===============

https://github.com/ansible/ansible/issues/36397
  Provide bash-completion script for ansible commands.
https://docs.ansible.com/ansible/devel/installation_guide/intro_installation.html#shell-completion
  As of Ansible 2.9 shell completion of the ansible command line utilities is available and provided
  through an optional dependency called argcomplete.

Ansible language
================

https://docs.ansible.com/ansible/latest/user_guide/playbooks_module_defaults.html
  Module defaults.
https://docs.ansible.com/ansible/latest/reference_appendices/playbooks_keywords.html
  Reserved keywords.
https://docs.ansible.com/ansible/latest/user_guide/intro_patterns.html
  Patterns: targeting hosts and groups.
https://docs.ansible.com/ansible/latest/network/getting_started/first_inventory.html
  Using aliases & groups for hosts.
https://docs.ansible.com/ansible/latest/user_guide/playbooks_error_handling.html
  Error handling in playbooks

Variables:

https://docs.ansible.com/ansible/latest/user_guide/playbooks_variables.html
  Using Variables. Precedence.
https://docs.ansible.com/ansible/latest/reference_appendices/config.html
  Ansible Configuration Settings.
https://docs.ansible.com/ansible/latest/reference_appendices/special_variables.html
  Magic variables.
https://docs.ansible.com/ansible/latest/user_guide/playbooks_vars_facts.html
  Discovering variables: facts and magic variables.

Inventory:

https://docs.ansible.com/ansible/latest/collections/ansible/builtin/generator_inventory.html
  Uses Jinja2 to construct hosts and groups from patterns.

Inclusion:

https://docs.ansible.com/ansible/latest/collections/ansible/builtin/include_module.html
  Include a play or task list.

Filters:

https://jinja.palletsprojects.com/en/master/templates/
  Jinja template language. List of Builtin Filters.
https://docs.ansible.com/ansible/latest/user_guide/playbooks_filters.html
  Using filters to manipulate data.

Search path
===========

Files, templates, variables definitions are looked in ``files``, ``templates``, ``vars`` role / play
directories first, then in the base directory for role / play.

https://docs.ansible.com/ansible/latest/user_guide/intro_inventory.html
  You can also add ``group_vars/`` and ``host_vars/`` directories to your playbook
  directory. The ansible-playbook command looks for these directories in the current
  working directory by default. Other Ansible commands (for example, ansible,
  ansible-console, and so on) will only look for ``group_vars/`` and ``host_vars/`` in the
  inventory directory. If you want other commands to load group and host variables from a
  playbook directory, you must provide the ``--playbook-dir`` option on the command line.
  If you load inventory files from both the playbook directory and the inventory
  directory, variables in the playbook directory will override variables set in the
  inventory directory.
https://docs.ansible.com/ansible/latest/user_guide/playbook_pathing.html
  Search paths in Ansible.

Templates
=========

https://docs.ansible.com/ansible/latest/user_guide/playbooks_templating.html
  Templating (Jinja2).