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:

  • FreeBSD Supported Production Releases

  • Ubuntu Supported Releases

• Requirements:

  • ansible_lib

  • community.general

Note

• The utility ansible-runner is not part of standard Ansible installation.

• See Installing Ansible Runner

See also

• Ansible Runner documentation

• Ansible Runner source code

• REST API ansible-runner-service

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 pb.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_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

Hint

The debug output of this role is optimized for result_format=yaml. See result_format. Set it in the configuration

[defaults]
callback_result_format = yaml

, or in the environment

ANSIBLE_CALLBACK_RESULT_FORMAT=yaml

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 pb.yml --list-tags

playbook: pb.yml

play #1 (srv.example.com): srv.example.com TAGS: [] TASK TAGS:
   [always, ar_config, ar_debug, ar_links, ar_pip, ar_pkg,
   ar_sanity, ar_vars, ar_venv]

For example, display the list of the variables and their values with the tag ar_debug (when the debug is enabled ar_debug=true)

shell> ansible-playbook pb.yml -t ar_debug -e ar_debug=true

See what OS packages will be installed

shell> ansible-playbook pb.yml -t ar_pkg --check

Install OS packages and exit the play

shell> ansible-playbook pb.yml -t ar_pkg

Tasks

Test single tasks at single remote host test_01. Create the playbook 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

• Example 1: Install ansible-runner in Ubuntu by pip for admin
• Example 2: Install ansible-runner in FreeBSD from port

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?

<TBD>

[defaults/main.yml]

---
# defaults ansible_runner
ar_role_version: 2.8.0

ar_pkg_install: false
ar_pip_install: false
ar_venv_install: false

ar_packages_state: present
# ar_packages see vars/defaults
ar_pip_packages_state: present
ar_pip_packages:
  - name: ansible-runner
    state: "{{ ar_pip_packages_state }}"

ar_debug: false
ar_backup_conf: false

ar_supported_linux_family: [RedHat, Debian]
ar_pip_extraagrs: --user --upgrade

# Sanity
ar_sanity: true
# Test ar_pip_install, ar_venv_install, and ar_pkg_install are mutually exclusive
ar_sanity_pip_exclusive: true
# Test ar_owner is defined
ar_sanity_pip_owner_defined: "{{ ar_pip_install }}"
# Test ar_pip_executable exists
ar_sanity_pip_exists: "{{ ar_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
ar_virtualenv: $HOME/env

# Config
ar_config: []

# Links
ar_links: []

# Override OS specific variables. See tasks/vars.yml
# ar_packages_override:
#   - ansible-runner-devel
# ar_pip_executable_override: /usr/bin/pip4
# ar_pip_requirements_override: ''

# EOF
...

OS variables

<TBD>

Debian

[vars/defaults/Debian.yml]

---
# Debian vars/defaults for ansible_runner

ar_packages:
  - name: ansible-runner
    state: "{{ ar_packages_state }}"

ar_virtualenv_command: python3 -m venv
ar_virtualenv_packages:
  - name: python3-venv
    state: "{{ ar_packages_state }}"
  - name: python{{ ansible_python_version | splitext | first }}-venv
    state: "{{ ar_packages_state }}"

ar_pip_executable: /usr/bin/pip3

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

# ar_links:
#   - src: "/home/{{ ar_owner }}/.local/bin/ansible-runner"
#     dest: "/home/{{ ar_owner }}/bin/ansible-runner"
#     force: true

# EOF
...

FreeBSD

[vars/defaults/FreeBSD.yml]

---
# FreeBSD vars/defaults for ansible_runner

ar_packages:
  - name: sysutils/py-ansible-runner
    state: "{{ ar_packages_state }}"

ar_virtualenv_command: python3 -m venv
ar_virtualenv_packages: []

ar_pip_executable: /usr/local/bin/pip-{{ ansible_python_version | splitext | first }}

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

# EOF
...

RedHat

[vars/defaults/RedHat.yml]

---
# RedHat vars/defaults for ansible_runner

ar_packages:
  - name: python-ansible-runner
    state: "{{ ar_packages_state }}"

ar_virtualenv_command: python3 -m venv
ar_virtualenv_packages:
  - name: python3-venv
    state: "{{ ar_packages_state }}"

ar_pip_executable: /usr/bin/pip3

ar_pip_requirements: ""

# ar_links:
#   - src: "/home/{{ ar_owner }}/.local/bin/ansible-runner"
#     dest: "/home/{{ ar_owner }}/bin/ansible-runner"
#     force: true

# EOF
...

Ubuntu

[vars/defaults/Ubuntu.yml]

---
# Ubuntu vars/defaults for ansible_runner

ar_packages:
  - name: ansible-runner
    state: "{{ ar_packages_state }}"

ar_virtualenv_command: python3 -m venv
ar_virtualenv_packages:
  - name: python3-venv
    state: "{{ ar_packages_state }}"
  - name: python{{ ansible_facts['python_version'] | splitext | first }}-venv
    state: "{{ ar_packages_state }}"

ar_pip_executable: /usr/bin/pip3

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

# ar_links:
#   - src: "/home/{{ ar_owner }}/.local/bin/ansible-runner"
#     dest: "/home/{{ ar_owner }}/bin/ansible-runner"
#     force: true

# EOF
...

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

• Example 1: Run Ansible playbooks in cron
  • Run ssh-agent
  • Run gpg-agent
  • Wrapper ansible-runner
  • Command for cron
  • Crontab
  • Email sent by cron
  • Project
  • Playbook
  • Artifacts
• Example 2: List artifacts’ job events
  • Test negative result
  • Cron email on failure
  • Artifacts
  • Playbook
  • Events
  • Failed event(s)
• Example 3: Handle custom status of playbook
  • Playbook
  • Enable custom status
  • Wrapper ansible-runner
  • Run the playbook and display the artifacts’ directory
  • Display the custom status from the artifacts
  • Select results of the first script

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.

• ANSIBLE_CALLBACK_PLUGINS in envvars is not working. #219