Ansible-runner

The command ansible-runner is part of the Ansible automation platform. If you have got installed Ansible, then you probably have already installed ansible-runner as well.

But what do you use it for? Well, if you run AWX or the Ansible Automation platform package somewhere in your environment, ansible-runner is part of the magic in the background and running your code. It is also a python library that can connect your code directly to Ansible and provides an abstraction interface with it.

For those who do not want to go into Python programming just to play with Ansible, ansible-runner also has some other useful purposes.

You can use to encapsulate a single Ansible run including all required variables and settings into a single environment.

Instead of a playbook, ansible-runner requires a project folder which then contains the required data for the Ansible run.

We create a quick setup in the /tmp/ansible-runner directory just for giving an example. Something like this is already enough:

$ tree
.
├── inventory
│   └── hosts
└── project
    └── playbook.yml

# playbook.yml
---
- name: Example playbook
  hosts: all
  tasks:
    - name: Debug output
      ansible.builtin.debug:
        msg: "The code runs."

# inventor/hosts
localhost ansible_connection=local

With these files in place, you can do this:

$ ansible-runner run /tmp/ansible-runner --playbook playbook.yml
PLAY [Example playbook] ********************************************************

TASK [Gathering Facts] *********************************************************
tirsdag 27 februar 2024  14:01:03 +0100 (0:00:00.010)       0:00:00.010 *******
tirsdag 27 februar 2024  14:01:03 +0100 (0:00:00.010)       0:00:00.010 *******
ok: [localhost]

TASK [Debug output] ************************************************************
tirsdag 27 februar 2024  14:01:04 +0100 (0:00:01.068)       0:00:01.079 *******
tirsdag 27 februar 2024  14:01:04 +0100 (0:00:01.068)       0:00:01.078 *******
ok: [localhost] => {
    "msg": "The code runs."
}

PLAY RECAP *********************************************************************
localhost                  : ok=2    changed=0    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0
Playbook run took 0 days, 0 hours, 0 minutes, 1 seconds
tirsdag 27 februar 2024  14:01:04 +0100 (0:00:00.042)       0:00:01.122 *******
===============================================================================
Gathering Facts --------------------------------------------------------- 1.07s
Debug output ------------------------------------------------------------ 0.04s
tirsdag 27 februar 2024  14:01:04 +0100 (0:00:00.043)       0:00:01.122 *******
===============================================================================
gather_facts ------------------------------------------------------------ 1.07s
ansible.builtin.debug --------------------------------------------------- 0.04s
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
total ------------------------------------------------------------------- 1.11s

ansible-runner per default assumes playbooks to be placed in the subdirectory ./project (this can be changed of course). The hosts in inventory/hosts are loaded automatically and the playbook executed against them.

All other settings required for an Ansible run, like secrets, environment variables or SSH keys for accessing hosts, can also be provided within the project directory structure.

Roles just like playbooks go into the ./project directory.

The outcome of the Ansible run creates a new directory in the project directory (not ./project, but the one above it) called ./artifacts. This directory contains all results, data and events that occured during the Ansible run in a parse-able and human-readable form.

With the proper configuration and settings, you can create encapsulated code environments, that can be deployed to a container or a remote system and the result can be parsed on for further use in e.g. a CICD pipeline.

Unfortunately there are just too many parameters for a single blog entry to go into the depth of what ansible-runner can do.

Take a look into the Ansible Runner demo repository¹ to get an easy start and some more guidance. Have fun playing with it!