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:
Requirements:
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
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
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
Annotated Source code configure.yml
Ansible plugins
Synopsis
Install Ansible plugins.
See also
Annotated Source code plugins.yml
Examples
Ansible devel
Synopsis
Ansible development <WIP>.
See also
Annotated Source code devel.yml
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
<TBD>
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