Ansible

Debugging Ansible
Bash completion
Ansible language
Search path
Templates
Execution
Special variables
Blocks
Collections

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

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