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.
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.”
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 ansible-runner.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 ansible-runner.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 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>
PyPI or OS distro packages
ansible-runner can be installed by pip
shell> ansible-playbook pb.yml -t ar_pip -e ar_pkg_install=false ar_pip_install=true
,or from distribution’s packages, and ports
shell> ansible-playbook pb.yml -t ar_packages -e ar_pkg_install=true ar_pip_install=false
Examples
See also
Annotated Source code packages.yml
Annotated Source code pip.yml
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_debug: false
7ar_backup_conf: false
8
9ar_supported_linux_family: [RedHat, Debian]
10ar_pip_extraagrs: --user --upgrade
11
12# Sanity
13ar_sanity: true
14# Test ar_pip_install and ar_pkg_install are mutually exclusive
15ar_sanity_pip_exclusive: true
16# Test ar_owner is defined
17ar_sanity_pip_owner_defined: "{{ ar_pip_install }}"
18# Test ar_pip_executable exists
19ar_sanity_pip_exists: "{{ ar_pip_install }}"
20
21# FreeBSD
22freebsd_install_retries: 3
23freebsd_install_delay: 10
24freebsd_install_method: packages
25# freebsd_install_method: ports
26freebsd_use_packages: true
27
28# Linux
29linux_install_retries: 3
30linux_install_delay: 10
31
32# pip
33pip_install_retries: 3
34pip_install_delay: 10
35
36# Config
37ar_config: []
38
39# Links
40ar_links: []
41
42# Override OS specific variables. See tasks/vars.yml
43# ar_packages_override:
44# - ansible-runner-devel
45# ar_pip_executable_override: /usr/bin/pip4
46# ar_pip_requirements_override: ''
47
48# EOF
49...
OS variables
<TBD>
Debian
1---
2# Debian vars/defaults for ansible_runner
3
4ar_pip_executable: /usr/bin/pip3
5
6ar_packages:
7 - ansible-runner
8
9# Path to a pip requirements file local to the remote system
10ar_pip_requirements: ""
11
12# ar_links:
13# - src: "/home/{{ ar_owner }}/.local/bin/ansible-runner"
14# dest: "/home/{{ ar_owner }}/bin/ansible-runner"
15# force: true
16
17# EOF
18...
FreeBSD
1---
2# FreeBSD vars/defaults for ansible_runner
3
4ar_pip_executable: /usr/local/bin/pip-{{ ansible_python_version | splitext | first }}
5
6ar_packages_bsd:
7 - sysutils/py-ansible-runner
8
9ar_packages_pip:
10 - ansible-runner
11
12ar_packages: "{{ ar_pip_install | ternary(ar_packages_pip, ar_packages_bsd) }}"
13
14# Path to a pip requirements file local to the remote system
15ar_pip_requirements: ""
16
17# EOF
18...
RedHat
1---
2# RedHat vars/defaults for ansible_runner
3
4ar_pip_executable: /usr/bin/pip3
5
6ar_packages_rh:
7 - python-ansible-runner
8
9ar_packages_pip:
10 - ansible-runner
11
12ar_packages: "{{ ar_pip_install | ternary(ar_packages_pip, ar_packages_rh) }}"
13
14ar_pip_requirements: ""
15
16# ar_links:
17# - src: "/home/{{ ar_owner }}/.local/bin/ansible-runner"
18# dest: "/home/{{ ar_owner }}/bin/ansible-runner"
19# force: true
20
21# EOF
22...
Ubuntu
1---
2# Ubuntu vars/defaults for ansible_runner
3
4ar_pip_executable: /usr/bin/pip3
5
6ar_packages:
7 - ansible-runner
8
9# Path to a pip requirements file local to the remote system
10ar_pip_requirements: ""
11
12# ar_links:
13# - src: "/home/{{ ar_owner }}/.local/bin/ansible-runner"
14# dest: "/home/{{ ar_owner }}/bin/ansible-runner"
15# force: true
16
17# EOF
18...
Best practice
Test 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 and display changes
shell> ansible-playbook pb.yml --check --diff
Install distribution packages
shell> ansible-playbook pb.yml -t ar_packages -e ar_pkg_install=true
, or install PyPI packages
shell> ansible-playbook pb.yml -t ar_pip -e ar_pip_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.