Install the Playbook Runner module

With Puppet Core Edge, you can execute Playbook Runner content on Ansible inventory via the Bolt CLI.

These installation steps are for users with a Puppet Core Edge license. If you are a Puppet Enterprise (PE) or Puppet Enterprise Advanced (PEA) user, see the Puppet Enterprise documentation for Playbook Runner.

Before you begin

  • To enable Playbook Runner, you must acquire an Edge entitlement. Contact your Puppet administrator or  Contact our sales team to acquire a license.

  • Have an Ansible control node  (newly installed or previously existing).

    • Ensure the Ansible inventory file on the control node includes SSH connectivity details.  For Playbook Runner version 1 to work as designed, you must have SSH connectivity details in the Ansible inventory file on your control node. SSH connectivity details are not set by default. 

    • Puppet agent or Ruby must be installed on the Ansible control node.

  • You must have Bolt 5.0 or later installed. Playbook Runner uses Bolt tasks to execute Ansible content. See Installing Bolt.

Install the Playbook Runner module

Install the Playbook Runner module by creating a Bolt project and adding the playbook_runner module. See the Playbook Runner module README on Puppet Forge.

Run ad-hoc commands and playbooks using Playbook Runner

You can use tasks in the Playbook Runner module to:

  • Run an Ansible ad-hoc command.

  • Run an Ansible playbook.

Before you begin

See Install the Playbook Runner module

Playbook Runner examples and sample tasks

Run a playbook named create-users on the Ansible host

To use a Bolt task to run a playbook on the Ansible host, where the playbook and inventory files are located on the Ansible host at /etc/ansible/playbooks/create-users.yaml and /etc/ansible/inventory/hosts, run:

Copy 
bolt task run playbook_runner::playbook --targets ansible-control-node playbook=/etc/ansible/playbooks/create-users.yaml inventory=/etc/ansible/inventory/hosts

Run a playbook from a Python virtual environment where Ansible is local to the user

Copy 
bolt task run playbook_runner::playbook --targets ansible-control-node playbook_executor_path=/home/johndoe/python-venv/ansible2.16/bin/ansible-playbook playbook=/home/johndoe/ansible/playbooks/create-users.yaml inventory=/home/johndoe/ansible/inventory/hosts.yaml user=johndoe

Run a playbook or adhoc Ansible content on the remote host and output results in Ansible YAML stdout format

By default, Playbook Runner data is returned in a Puppet customized format. This provides short, readable, consistent output that can be parsed by Puppet workflows and plans.

However, an alternative format can be specified using the parameter stdout_callback. Using the YAML format can be helpful for debugging playbook failures.

For example, to run a playbook on the remote host and output results in Ansible YAML stdout format:

Copy 
bolt task run playbook_runner::playbook --targets ansible-control-node playbook=playbooks/create-users.yaml inventory=inventory/hosts project=/etc/ansible/ stdout_callback=yaml

For example, to run adhoc Ansible content on the remote host and output results in Ansible YAML stdout format:

Copy 
bolt task run playbook_runner::command --targets ansible-control-node module_name=ping inventory=inventory/hosts project=/etc/ansible/ stdout_callback=yaml

Related information