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
    - name: Debug output
        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 repository1 to get an easy start and some more guidance. Have fun playing with it!


Daniel Buøy-Vehn

Senior Systems Consultant at Redpill Linpro

Daniel works with automation in the realm of Ansible, AWX, Tower, Terraform and Puppet. He rolls out mainly to our customer in Norway to assist them with the integration and automation projects.


make is a utility for automating builds. You specify the source and the build file and make will determine which file(s) have to be re-built. Using this functionality in make as an all-round tool for command running as well, is considered common practice. Yes, you could write Shell scripts for this instead and they would be probably equally good. But using make has its own charm (and gets you karma points).

Even this ... [continue reading]

Containerized Development Environment

Published on February 28, 2024

Portable Java shell scripts with Java 21

Published on February 21, 2024