=========

 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