Originally published on the Redpill Linpro blog by Daniel Buøy-Vehn
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 repository1 to get an easy start and some more guidance. Have fun playing with it!
Author:
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.