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 ansible.yml that calls this role (10) at a single host srv.example.com (2)

---
- 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 OS packages will be installed

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

Install OS packages and exit the play

shell> ansible-playbook ansible.yml -t ma_pkg

Tasks 

Test single tasks at single remote host test_01. Create the playbook ansible.yml

---
- hosts: test_01
  become: true
  roles:
    - vbotka.ansible

Customize configuration, for example, 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

Warning

By default, ma_pkg_install, ma_pip_install, and ma_venv_install are mutually exclusive. Disable ma_sanity_pip_exclusive if you want to install more options in the same play.

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

Warning

Conclusions. The pip module isn’t always idempotent #28952 Quoting: “Managing system site-packages with Pip is not a good idea and will probably break your OS. Those should be solely managed by the OS package manager (apt/yum/dnf/etc.). If you want to manage env for some software in Python, better use a virtualenv technology.”

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?

Default variables 

<TBD>

[defaults/main.yml]

---
# default vars for ansible
ma_role_version: 2.6.23

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.15", "2.16", "2.17"]
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"]

OS variables 

<TBD>

Debian 

[vars/defaults/Debian.yml]

---
# Debian vars/defaults for ansible

ma_packages:
  - name: ansible
    state: "{{ ma_packages_state }}"

ma_virtualenv_command: python3 -m venv
ma_virtualenv_packages:
  - name: python3-venv
    state: "{{ ma_packages_state }}"
  - name: python{{ ansible_python_version | splitext | first }}-venv
    state: "{{ ma_packages_state }}"

ma_pip_executable: /usr/bin/pip3

# Path to a pip requirements file local to the remote system
ma_pip_requirements: ""

# EOF

FreeBSD 

[vars/defaults/FreeBSD.yml]

---
# FreeBSD vars/defaults for ansible

ma_packages:
  - name: sysutils/ansible
    state: "{{ ma_packages_state }}"
  - name: sysutils/py-ansible-lint
    state: "{{ ma_packages_state }}"
# - name: devel/py-epdb
#   state: "{{ ma_packages_state }}"

ma_virtualenv_command: python3 -m venv
ma_virtualenv_packages: []
ma_pip_executable: /usr/local/bin/pip-{{ ansible_python_version | splitext | first }}

# Path to a pip requirements file local to the remote system
ma_pip_requirements: ""

# EOF

RedHat 

[vars/defaults/RedHat.yml]

---
# RedHat vars for ansible

ma_packages:
  - name: python-ansible
    state: "{{ ma_packages_state }}"

ma_virtualenv_command: python3 -m venv
ma_virtualenv_packages:
  - name: python3-venv
    state: "{{ ma_packages_state }}"

ma_pip_executable: /usr/bin/pip3

# Path to a pip requirements file local to the remote system
ma_pip_requirements: ""

# EOF

Ubuntu 

[vars/defaults/Ubuntu.yml]

---
# Ubuntu vars/defaults for ansible

ma_packages:
  - name: ansible
    state: "{{ ma_packages_state }}"

ma_virtualenv_command: python3 -m venv
ma_virtualenv_packages:
  - name: python3-venv
    state: "{{ ma_packages_state }}"
  - name: python{{ ansible_python_version | splitext | first }}-venv
    state: "{{ ma_packages_state }}"

ma_pip_executable: /usr/bin/pip3

# Path to a pip requirements file local to the remote system
ma_pip_requirements: ""

# EOF

Best practice 

Test the 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

Dry-run the playbook in the check mode and display changes

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

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

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