User’s guide 

Introduction 

Run this role to install and configure Ansible. Optionally, install Ansible plugins, checkout repo with the source code, and download the Ansible release notes.

Ansible role: ansible
Supported systems:
- FreeBSD Supported Production Releases
- Ubuntu Supported Releases
Requirements:
- ansible_lib
- community.general

See also

The most convenient way how to install an Ansible role is to use Ansible Galaxy CLI ansible-galaxy. The utility comes with the standard Ansible package and provides the user with a simple interface to the Ansible Galaxy’s services. For example, take a look at the current status of the role

shell> ansible-galaxy role info vbotka.ansible

and install it

shell> ansible-galaxy role install vbotka.ansible

Install the library

shell> ansible-galaxy role install vbotka.ansible_lib

and install the collection if necessary

shell> ansible-galaxy collection install community.general

See also

To install specific versions from various sources see Installing content
Take a look at other roles shell> ansible-galaxy search --author=vbotka

Playbook 

Below is a simple playbook that calls this role (10) at a single host srv.example.com (2)

shell> cat ansible.yml
- hosts: srv.example.com
  gather_facts: true
  connection: ssh
  remote_user: admin
  become: true
  become_user: root
  become_method: sudo
  roles:
    - vbotka.ansible

Note

gather_facts: true (3) must be set to gather facts needed to evaluate OS-specific options of the role. For example, to install packages, the variable ansible_os_family is needed to select the appropriate Ansible module.

See also

For details see Connection Plugins (4-5)
See also Understanding Privilege Escalation (6-8)

Debug 

To see additional debug information enable debug output in the configuration

ma_debug: true

, or set the extra variable in the command

shell> ansible-playbook ansible.yml -e ma_debug=true

Note

The debug output of this role is optimized for the yaml callback plugin. Set this plugin for example in the environment shell> export ANSIBLE_STDOUT_CALLBACK=yaml.
See details about the yaml callback plugin shell> ansible-doc -t callback yaml
See list of other callback plugins shell> ansible-doc -t callback -l

See also

Playbook Debugger

Tags 

The tags provide the user with a very useful tool to run selected tasks of the role. To see what tags are available list the tags of the role:

shell> ansible-playbook ansible.yml --list-tags

playbook: ansible.yml

play #1 (srv.example.com): srv.example.com   TAGS: []

   TASK TAGS: [always, ma_ara, ma_config, ma_debug, ma_devel,
   ma_devel_repo, ma_devel_rnotes, ma_pip, ma_pkg, ma_plugins,
   ma_plugins_download, ma_plugins_extract, ma_plugins_link,
   ma_plugins_lists, ma_plugins_path, ma_plugins_test_inikeys,
   ma_repo_path, ma_rnotes_path, ma_sanity, ma_src_path, ma_vars,
   ma_venv]

For example, display the list of the variables and their values with the tag ma_debug (when the debug is enabled ma_debug=true)

 shell> ansible-playbook ansible.yml -t ma_debug -e ma_debug=true

Create directories

 shell> ansible-playbook ansible.yml -t ma_plugins_path,ma_src_path,ma_repo_path,ma_rnotes_path

See what packages will be installed

 shell> ansible-playbook ansible.yml -t ma_packages --check

Install packages and exit the play

 shell> ansible-playbook ansible.yml -t ma_packages

Tasks 

Test single tasks at single remote host test_01. Create a playbook

shell> cat ansible.yml
- hosts: test_01
  become: true
  roles:
    - vbotka.ansible

Customize configuration in host_vars/test_01/ma-*.yml and check the syntax

shell> ansible-playbook ansible.yml --syntax-check

Then dry-run the selected task and see what will be changed. Replace <tag> with valid tag.

shell> ansible-playbook ansible.yml -t <tag> --check --diff

When all seems to be ready run the command. Run the command twice and make sure the playbook and the configuration is idempotent

shell> ansible-playbook ansible.yml -t <tag>

Install Ansible package 

There are three options:

Install OS-specific packages
Install PyPI package
Install PyPI package in Python virtual environment

By default, nothing will be installed:

ma_pkg_install: false
ma_pip_install: false
ma_venv_install: false

By default, the options are mutually exclusive

ma_sanity_pip_exclusive: true

Install OS-specific packages

Dry run the installation and see what will be installed

shell> ansible-playbook ansible.yml -t ma_pkg -e ma_debug=true -e ma_pkg_install=true -CD

If all is right install the package

shell> ansible-playbook ansible.yml -t ma_pkg -e ma_debug=true -e ma_pkg_install=true

See also

Annotated Source code pkg.yml

Install PyPI package

Dry run the installation and see what will be installed

shell> ansible-playbook ansible.yml -t ma_pip -e ma_debug=true -e ma_pip_install=true -CD

If all is right install the package

shell> ansible-playbook ansible.yml -t ma_pip -e ma_debug=true -e ma_pip_install=true

See also

Annotated Source code pip.yml

Install PyPI package in Python virtual environment

Dry run the installation and see what will be installed

shell> ansible-playbook ansible.yml -t ma_venv -e ma_debug=true -e ma_venv_install=true -CD

If all is right install the package

shell> ansible-playbook ansible.yml -t ma_venv -e ma_debug=true -e ma_venv_install=true

See also

Annotated Source code venv.yml

Configure Ansible 

Synopsis

Configure Ansible <WIP>.

See also

Annotated Source code config.yml
Configuring Ansible

Install Ansible plugins 

Synopsis

Install Ansible plugins.

See also

Examples

Ansible devel 

Synopsis

Ansible development <WIP>.

See also

Annotated Source code devel.yml
Ansible Developer Guide

Examples

Variables 

The default variables are stored in the directory defaults. OS specific variables are stored in the directory vars/defaults.

See also

Annotated Source code vars.yml
Ansible variable precedence: Where should I put a variable?

<TBD>

[defaults/main.yml]

---
# default vars for ansible

ma_pkg_install: false
ma_pip_install: false
ma_venv_install: false

ma_packages_state: present
# ma_packages see vars/defaults
ma_pip_packages_state: present
ma_pip_packages:
  - name: ansible
    state: "{{ ma_pip_packages_state }}"

ma_debug: false
ma_backup_conf: false

ma_supported_linux_family: [RedHat, Debian]
ma_pip_extraagrs: --user --upgrade

# Sanity
ma_sanity: true
# Test ma_pip_install, ma_venv_install, and ma_pkg_install are mutually exclusive
ma_sanity_pip_exclusive: true
# Test ma_owner is defined
ma_sanity_pip_owner_defined: "{{ ma_pip_install }}"
# Test ma_pip_executable exists
ma_sanity_pip_exists: "{{ ma_pip_install }}"

# FreeBSD
freebsd_install_retries: 3
freebsd_install_delay: 10
freebsd_install_method: packages
# freebsd_install_method: ports
freebsd_use_packages: true

# Linux
linux_install_retries: 3
linux_install_delay: 10

# pip
pip_install_retries: 3
pip_install_delay: 10

# venv
ma_virtualenv: $HOME/env

# Config
ma_config: []
# ma_config_type options: template, lineinfile, ini_file
# See tasks/configure.yml
ma_config_type: template
ma_config_template_default: ansible-auto.cfg.j2
ma_src_path: /usr/local/ansible/src

# ARA
ma_ara: false

# Plugins
ma_plugins_paths_list: []
ma_plugins_path: /usr/local/ansible/plugins
ma_plugins: []
ma_plugins_sections:
  action_plugins: defaults
  cache_plugins: defaults
  callback_plugins: defaults
  connection_plugins: defaults
  filter_plugins: defaults
  httpapi_plugins: defaults
  inventory_plugins: defaults
  lookup_plugins: defaults
  netconf_plugins: defaults
  strategy_plugins: defaults
  terminal_plugins: defaults
  test_plugins: defaults
  vars_plugins: defaults

# Devel
ma_devel: false
ma_devel_owner: root
ma_repo: false
ma_repo_version: devel
ma_repo_url: https://github.com/ansible/ansible
ma_repo_dir: /scratch/ansible-git
ma_rnotes: false
ma_rnotes_core_url: https://raw.githubusercontent.com/ansible/ansible/stable-
ma_rnotes_core_dir: /scratch/ansible-release-notes/core
ma_rnotes_core_list: ["2.14", "2.15", "2.16"]
ma_rnotes_build_url: https://raw.githubusercontent.com/ansible-community/ansible-build-data/main/
ma_rnotes_build_dir: /scratch/ansible-release-notes/build
ma_rnotes_build_list: ["7", "8", "9"]

# EOF
...

Best practice 

Test syntax

shell> ansible-playbook ansible.yml --syntax-check

Display and review the variables. Then disable debug ma_debug=false to speedup the playbook

shell> ansible-playbook ansible.yml -t ma_debug -e ma_debug=true

Install OS-packages ma_pkg_install=true or PyPI packages ma_pip_install=true. Optionally, install the packages in Python virtual environment ma_venv_install=true. Then disable the installation to speedup the playbook

shell> ansible-playbook ansible.yml -t ma_pkg -e ma_pkg_install=true

Create directories. The following check would fail without the directories

shell> ansible-playbook ansible.yml -t ma_plugins_dirs,ma_src_path

If you want to download the repository and the release notes create also these directories

shell> ansible-playbook ansible.yml -t ma_repo_path,ma_rnotes_path

Run the playbook in the check mode and review the changes

shell> ansible-playbook ansible.yml --check --diff

If all seems to be right run the playbook. The role and the configuration data in the examples are idempotent. After the installation and configuration completed there should be no changes reported by ansible-playbook when running the playbook repeatedly

shell> ansible-playbook ansible.yml