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.

Installation

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)

 1shell> cat ansible.yml
 2- hosts: srv.example.com
 3  gather_facts: true
 4  connection: ssh
 5  remote_user: admin
 6  become: true
 7  become_user: root
 8  become_method: sudo
 9  roles:
10    - 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

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

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_packages, 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_src_path, ma_vars]

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>

Configure Ansible

Synopsis

Configure Ansible <WIP>.

See also

Ansible plugins

Synopsis

Install Ansible plugins.

See also

Examples

Ansible devel

Synopsis

Ansible development <WIP>.

See also

Examples

Variables

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

<TBD>

[defaults/main.yml]

 1---
 2# default vars for ansible
 3
 4ma_install: true
 5ma_debug: false
 6ma_backup_conf: false
 7
 8ma_supported_linux_family: [RedHat, Debian]
 9# Packages
10freebsd_install_method: packages
11# freebsd_install_method: ports
12freebsd_use_packages: true
13freebsd_install_retries: 10
14freebsd_install_delay: 5
15linux_install_retries: 10
16linux_install_delay: 5
17
18# ma_config_type options: template, lineinfile, ini_file
19# See tasks/configure.yml
20ma_config_type: template
21ma_config_template_default: ansible-auto.cfg.j2
22ma_config: []
23ma_src_path: /usr/local/ansible/src
24
25# ARA
26ma_ara: false
27
28# Plugins
29ma_plugins_paths_list: []
30ma_plugins_path: /usr/local/ansible/plugins
31ma_plugins: []
32ma_plugins_sections:
33  action_plugins: defaults
34  cache_plugins: defaults
35  callback_plugins: defaults
36  connection_plugins: defaults
37  filter_plugins: defaults
38  httpapi_plugins: defaults
39  inventory_plugins: defaults
40  lookup_plugins: defaults
41  netconf_plugins: defaults
42  strategy_plugins: defaults
43  terminal_plugins: defaults
44  test_plugins: defaults
45  vars_plugins: defaults
46
47# Devel
48ma_devel: false
49ma_devel_owner: root
50ma_repo: false
51ma_repo_version: devel
52ma_repo_url: https://github.com/ansible/ansible
53ma_repo_dir: /scratch/ansible-git
54ma_rnotes: false
55ma_rnotes_core_url: https://raw.githubusercontent.com/ansible/ansible/stable-
56ma_rnotes_core_dir: /scratch/ansible-release-notes/core
57ma_rnotes_core_list: ["2.14", "2.15"]
58ma_rnotes_build_url: https://raw.githubusercontent.com/ansible-community/ansible-build-data/main/
59ma_rnotes_build_dir: /scratch/ansible-release-notes/build
60ma_rnotes_build_list: ["7", "8"]
61
62# EOF
63...

Best practice

Test syntax

shell> ansible-playbook pb.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 packages. Then disable the installation ma_install=false to speedup the playbook

shell> ansible-playbook ansible.yml -t ma_packages -e ma_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

Run the playbook if all seems to be right. 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