=========
 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.
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/set_fact_module.html
  ``ansible.builtin.set_fact`` – Set host facts from a task.

Inventory:

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

Collections:

https://docs.ansible.com/ansible/latest/user_guide/collections_using.html
  Using collections.
https://docs.ansible.com/ansible/2.10/collections/index.html
  Collection Index.

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.

Execution:

https://docs.ansible.com/ansible/latest/user_guide/playbooks_strategies.html
  Controlling playbook execution: strategies and more.
https://docs.ansible.com/ansible/latest/plugins/strategy.html
  Strategy Plugins.
https://docs.ansible.com/ansible/latest/user_guide/playbooks_delegation.html
  Controlling where tasks run: delegation and local actions.
https://docs.ansible.com/ansible/latest/reference_appendices/general_precedence.html
  Controlling how Ansible behaves: precedence rules.
https://docs.ansible.com/ansible/latest/user_guide/playbooks_handlers.html
  Handlers: running operations on change.
https://docs.ansible.com/ansible/latest/collections/ansible/builtin/setup_module.html
  ansible.builtin.setup – Gathers facts about remote hosts.

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).

Execution
=========

``-f`` option controls forking: how many executors are started to perform tasks.

The way tasks are processed depends on ``strategy`` and ``serial``.

``strategy`` * ``serial`` can be defined on each ``hosts`` in a play::

  - hosts: web
    strategy: free
    serial: 50%
  - hosts: db
    strategy: linear
    serial: 1

* With ``linear`` strategy all workers execute the same tasks, idling until every is finished the
  task. Then next task is executed. ``serial`` sets how many hosts at a time to run at a time to the
  end of subplay.
* With ``free`` strategy tasks are executed without waiting for completion of the same task on every
  host.

Special variables
=================

You can dump any variable by ``debug`` task in a playbook or using mudule::

  ansible $host -m debug -a var=groups

* ``vars`` holds everything!
* ``hosts`` holds all inventory definitions
* ``groups`` holds info about grouping of hosts
* ``ansible_facts`` all collected facts about current host

Blocks
======

To avoid repetitive checks or to handle failures use ``block``::

  block:
  - shell: echo do 1
  - shell: echo do 2
  when: not db_started
  become: true
  become_user: dba
  rescue:
  - shell: echo rollback
  always:
  - shell: echo notify

Collections
===========

https://docs.ansible.com/ansible/latest/user_guide/collections_using.html
  Using collections.

To install specific version use a colon and conditions with operators: ``==``, ``!=``, ``>``,
``>=``, ``<``, ``<=`` separated by comma::

  ansible-galaxy collection install 'my_namespace.my_collection:>=1.0.0,<2.0.0'

Only one version of collection can be installed, if you want to update with different version use
``--force``::

  ansible-galaxy collection install google.cloud:=0.0.1
  ansible-galaxy collection install --force google.cloud:=1.0.1