User’s guide
Introduction
This role to installs and configures Ansible Runner. Optionally, configure cron to periodically run Ansible playbooks.
Ansible role: ansible_runner
Supported systems:
Requirements:
Note
The utility ansible-runner is not part of standard Ansible installation.
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_runner
and install it
shell> ansible-galaxy role install vbotka.ansible_runner
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 a specific version of a role.
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 pb.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_runner
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
ar_debug: true
, or set the extra variable in the command
shell> ansible-playbook pb.yml -e ar_debug=true
Note
The debug output of this role is optimized for the yaml callback plugin. For example, set this plugin 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 pb.yml
- hosts: test_01
become: true
roles:
- vbotka.ansible_runner
Customize configuration, for example, in host_vars/test_01/ar-*.yml
and check the syntax
shell> ansible-playbook pb.yml --syntax-check
Then dry-run the selected task and see what will be changed. Replace <tag> with valid tag.
shell> ansible-playbook pb.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 pb.yml -t <tag>
Install ansible-runner 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:
ar_pkg_install: false
ar_pip_install: false
ar_venv_install: false
Warning
By default, ar_pkg_install, ar_pip_install, and ar_venv_install are mutually exclusive. Disable ar_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 pb.yml -t ar_pkg -e ar_debug=true -e ar_pkg_install=true -CD
If all is right install the package
shell> ansible-playbook pb.yml -t ar_pkg -e ar_debug=true -e ar_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 pb.yml -t ar_pip -e ar_debug=true -e ar_pip_install=true -CD
If all is right install the package
shell> ansible-playbook pb.yml -t ar_pip -e ar_debug=true -e ar_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 pb.yml -t ar_venv -e ar_debug=true -e ar_venv_install=true -CD
If all is right install the package
shell> ansible-playbook pb.yml -t ar_venv -e ar_debug=true -e ar_venv_install=true
See also
Annotated Source code venv.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# defaults ansible_runner
3
4ar_pkg_install: false
5ar_pip_install: false
6ar_venv_install: false
7
8ar_packages_state: present
9# ar_packages see vars/defaults
10ar_pip_packages_state: present
11ar_pip_packages:
12 - name: ansible-runner
13 state: "{{ ar_pip_packages_state }}"
14
15ar_debug: false
16ar_backup_conf: false
17
18ar_supported_linux_family: [RedHat, Debian]
19ar_pip_extraagrs: --user --upgrade
20
21# Sanity
22ar_sanity: true
23# Test ar_pip_install, ar_venv_install, and ar_pkg_install are mutually exclusive
24ar_sanity_pip_exclusive: true
25# Test ar_owner is defined
26ar_sanity_pip_owner_defined: "{{ ar_pip_install }}"
27# Test ar_pip_executable exists
28ar_sanity_pip_exists: "{{ ar_pip_install }}"
29
30# FreeBSD
31freebsd_install_retries: 3
32freebsd_install_delay: 10
33freebsd_install_method: packages
34# freebsd_install_method: ports
35freebsd_use_packages: true
36
37# Linux
38linux_install_retries: 3
39linux_install_delay: 10
40
41# pip
42pip_install_retries: 3
43pip_install_delay: 10
44
45# venv
46ar_virtualenv: $HOME/env
47
48# Config
49ar_config: []
50
51# Links
52ar_links: []
53
54# Override OS specific variables. See tasks/vars.yml
55# ar_packages_override:
56# - ansible-runner-devel
57# ar_pip_executable_override: /usr/bin/pip4
58# ar_pip_requirements_override: ''
59
60# EOF
61...
OS variables
<TBD>
Debian
1---
2# Debian vars/defaults for ansible_runner
3
4ar_packages:
5 - name: ansible-runner
6 state: "{{ ar_packages_state }}"
7
8ar_virtualenv_command: python3 -m venv
9ar_virtualenv_packages:
10 - name: python3-venv
11 state: "{{ ar_packages_state }}"
12 - name: python{{ ansible_python_version | splitext | first }}-venv
13 state: "{{ ar_packages_state }}"
14
15ar_pip_executable: /usr/bin/pip3
16
17# Path to a pip requirements file local to the remote system
18ar_pip_requirements: ""
19
20# ar_links:
21# - src: "/home/{{ ar_owner }}/.local/bin/ansible-runner"
22# dest: "/home/{{ ar_owner }}/bin/ansible-runner"
23# force: true
24
25# EOF
26...
FreeBSD
1---
2# FreeBSD vars/defaults for ansible_runner
3
4ar_packages:
5 - name: sysutils/py-ansible-runner
6 state: "{{ ar_packages_state }}"
7
8ar_virtualenv_command: python3 -m venv
9ar_virtualenv_packages: []
10
11ar_pip_executable: /usr/local/bin/pip-{{ ansible_python_version | splitext | first }}
12
13# Path to a pip requirements file local to the remote system
14ar_pip_requirements: ""
15
16# EOF
17...
RedHat
1---
2# RedHat vars/defaults for ansible_runner
3
4ar_packages:
5 - name: python-ansible-runner
6 state: "{{ ar_packages_state }}"
7
8ar_virtualenv_command: python3 -m venv
9ar_virtualenv_packages:
10 - name: python3-venv
11 state: "{{ ar_packages_state }}"
12
13ar_pip_executable: /usr/bin/pip3
14
15ar_pip_requirements: ""
16
17# ar_links:
18# - src: "/home/{{ ar_owner }}/.local/bin/ansible-runner"
19# dest: "/home/{{ ar_owner }}/bin/ansible-runner"
20# force: true
21
22# EOF
23...
Ubuntu
1---
2# Ubuntu vars/defaults for ansible_runner
3
4ar_packages:
5 - name: ansible-runner
6 state: "{{ ar_packages_state }}"
7
8ar_virtualenv_command: python3 -m venv
9ar_virtualenv_packages:
10 - name: python3-venv
11 state: "{{ ar_packages_state }}"
12 - name: python{{ ansible_python_version | splitext | first }}-venv
13 state: "{{ ar_packages_state }}"
14
15ar_pip_executable: /usr/bin/pip3
16
17# Path to a pip requirements file local to the remote system
18ar_pip_requirements: ""
19
20# ar_links:
21# - src: "/home/{{ ar_owner }}/.local/bin/ansible-runner"
22# dest: "/home/{{ ar_owner }}/bin/ansible-runner"
23# force: true
24
25# EOF
26...
Best practice
Test the syntax
shell> ansible-playbook pb.yml --syntax-check
Display and review the variables. Then disable debug
ar_debug=false
to speedup the playbook
shell> ansible-playbook pb.yml -t ar_debug -e ar_debug=true
Dry-run the playbook in the check mode and display changes
shell> ansible-playbook pb.yml --check --diff
Install OS packages ar_pkg_install=true
or PyPI packages
ar_pip_install=true
. Optionally, install the packages in Python
virtual environment ar_venv_install=true
. Then disable the
installation to speedup the playbook
shell> ansible-playbook pb.yml -t ar_pkg -e ar_pkg_install=true
The role and the configuration data in the examples are idempotent. Once the installation and configuration have passed there should be no changes reported by ansible-playbook when running the playbook repeatedly
shell> ansible-playbook pb.yml
Ansible Runner Usage Examples
Troubleshooting
Commented issues
There are reported issues at GitHub. Some of them influence ansible-runner in an unexpected and undocumented ways. See the commented issues to avoid unnecessary confusion and investigation looking for the difference between a bug and a feature. Check with the below links to see the issues’ current status.