When thinking about imperative infrastructure commands and Day 0 tasks for provisioning infrastructure, Ansible is an oft-mentioned tool that has been popular among practitioners for its easy YAML syntax and agentless architecture. You might have used Ansible to get your infrastructure started or for other “one-and-done” infrastructure automation scenarios. However, folks sometimes find that Ansible playbooks do not handle the scale of their infrastructure or lack built-in drift control and compliance, which leads teams to use configuration management tools like Puppet for ongoing operations. Traditionally, making a move to another automation tool has meant huge migration efforts or multiple tool sets being used by the team for different tasks with no easy path to consolidation. To overcome these obstacles, Puppet Edge now includes the Playbook Runner premium module!

Why Have a Playbook Runner?

Many infrastructure teams already rely on Ansible playbooks to automate tasks across their environments. These playbooks represent valuable institutional knowledge, whether it be scripts for provisioning, configuration, patching, or application deployment. But as organizations consolidate tooling and move toward unified automation platforms, the challenge of migrating existing assets has come to the forefront. If only you could use existing Ansible assets within Puppet workflows, right?

I think you know where this is going. 😁

Puppet Edge’s Playbook Runner module was built to solve the challenge of running existing playbooks, as the name suggests. With the Puppet Edge Playbook Runner, your team can orchestrate automation across your tooling and reuse your existing investment. The Playbook Runner supports the execution of YAML-formatted playbooks, like those used in Ansible, directly from Puppet. Using the Playbook Runner module to execute your playbooks means that you can keep your existing library of playbooks without starting a major migration project to rewrite your existing playbooks in Puppet’s desired state language. You get faster onboarding, reduced duplication, and a smoother transition between automation and orchestration strategies.

How It Works

Puppet Edge uses a combination of a Puppet Playbook Runner host, Puppet Bolt, and the Puppet Playbook Runner module to enable the execution of Ansible playbooks as part of your infrastructure automation plans.

Key Components

1. Playbook Runner control host: A designated system that acts as the execution engine for Ansible playbooks. The control host receives instructions from tasks and then runs Ansible playbook content against the target inventory. The Playbook Runner control host can be its own system or can run on an existing server, like your Puppet Enterprise server.
2. Playbook tasks: When a workflow, task, or plan includes an Ansible playbook task, Puppet sends the details of the task parameters to the Playbook Runner control host to run the requested playbook.
3. Puppet Playbook Runner module: The Playbook Runner module processes task information, loads playbooks, and runs playbooks on the Playbook Runner control host.

Example Workflow Scenario in Puppet Enterprise

• Consider a sample scenario with a three-step workflow that is defined in Puppet Enterprise:

• Step 1: The workflow begins with a step that uses a playbook task to create a load balancer.

• Step 2: The next workflow step triggers a Puppet Bolt task to enable the Network Configuration Protocol (NETCONF) on the new load balancer.

• Step 3: The final step configures the Network Time Protocol (NTP) servers on the load balancer over NETCONF with the Puppet EdgeOps module.

• When the first step is triggered, the playbook task runs using Puppet Bolt, which connects to the Playbook Runner control host.

• The Playbook Runner control host invokes the Playbook Runner module to run the playbook against the specified targets.

• Results are returned to Puppet, allowing for logging, error handling, and reporting, and the workflow continues to the next step.

The Puppet Edge Playbook Runner architecture helps to streamline automation. Teams can reuse existing playbooks, integrate the playbooks into broader Puppet workflows, and maintain consistency across automation strategies.

How to Execute an Ansible Playbook in Puppet Edge

This tutorial demonstrates how to run an existing playbook within a Puppet Enterprise task. If you use the sample playbook provided, you will create a load balancer in your Amazon Web Services (AWS) environment. The new Application Load Balancer (ALB) will be connected to a security group and two subnets. However, any playbook can be used to follow the tutorial. You will learn how to:

• Create a task to run on the Playbook Runner control host.
• Pass in command-line parameters from Puppet Enterprise to your playbook.
• Configure a task to generate additional output for debugging purposes.

ℹ️ Prerequisites:

• You have Puppet Enterprise installed and running.

You have the Playbook Runner module installed and enabled.

💡Tip: Starting with Puppet Enterprise (PE) 2025.6, the module is pre-installed and requires only a valid license for Puppet Edge. For earlier PE releases, you must install the Playbook Runner premium module. For details, see the playbook_runner module.

You have deployed your playbook YAML file to the host running your Playbook Runner. You can use any playbook, or this sample provided on GitHub, which creates an application load balancer in AWS.

(Optional) If you are using the sample playbook from GitHub:

• On the host running the Playbook Runner, install the required packages: python3, python3-pip, python3-boto3, and python3-botocore.
• On the host running the Playbook Runner, configure the AWS environment variables required to authenticate to your AWS environment.

Step-by-Step Instructions

1. Authenticate: Log in to Puppet Enterprise using your credentials.
2. View inventory: In the navigation pane, click Nodes to view all nodes in your inventory. The Playbook Runner control host is one of the nodes in your inventory.

Select the Playbook Runner control host: In the Node name column, click on the name of the node where your Playbook Runner control host is running. In this tutorial, the Playbook Runner control host is named puppet.domain.

💡 Tip: You can also select the nodes when you run the task creation wizard at a later step, but by targeting the host in these early steps, you streamline the task creation process later. 1.

Run a task: To run a one-time task on the Playbook Runner control host node, click Run>Task. 1.

Configure the task options:

1. Code environment: Specify where to run the task. Choose the environment that works for your solution. In this tutorial example, the production value is selected.
2. Task: Select playbook_runner::playbook. This option configures the task engine to run the Playbook Runner module.
3. Task description: Describe what the task will accomplish. For this tutorial scenario, you can enter “Create AWS Application Load Balancer.”
4. Concurrency limit: Leave the Concurrency limit (optional) field blank because it is not necessary to limit the number of affected nodes.

Timeout: Select No for the timeout setting, indicating that Puppet will not stop the execution after a timeout. 1.

Configure the playbook path: In the Task Parameters section, locate the playbook task parameter and enter the path to your playbook. For example /root/aws-create-application-lb.yaml

💡 Tip: When running a playbook task, the playbook task parameter is required. The parameter value specifies the path where the playbook YAML file is stored on the Playbook Runner host. 1.

Configure the additional arguments: If your playbook requires parameters, pass these with the additional_arguments task parameter. In the Task Parameters section, take the following actions:

1. Create a parameter by clicking the field in the Parameter column.
2. Select the additional_arguments task parameter.

In the Value column field, enter your arguments to pass to the playbook. For example, if you are using the sample application load balancer playbook, enter the following values for creating the application load balancer in AWS with a name of puppet-demo-alb in the us-east1 region, along with a few subnets and a security group:

--extra-vars '{'alb_name': 'puppet-demo-alb', 'aws_region': 'us-east-1', 'vpc_subnets': ['prod-main-vpc-us-east-1a-public-alb', 'prod-main-vpc-us-east-1b-public-alb'], 'security_group': 'prod-main-vpc-alb-ingress-v1-sg'}'

💡 Tip: If you are using the sample playbook, remember to specify real values for the subnets and security groups in your AWS environment to avoid errors. 1.

Save the parameter by clicking Add to task.

⚠️ You must click Add to task or the value will not be added to the task parameters when you proceed to the next stage of the wizard! 1.

(Optional) Add debugging output: For learning purposes, change the standard output of results to YAML format by updating the stdout_callback parameter. The additional logging detail can help with debugging your task, if necessary. If you do not specify the stdout_callback parameter value, the default output will be recorded.

Restriction: Use of the YAML format can affect system performance. For this reason, the default output is more appropriate in production scenarios at scale where auditing is not needed.

Take the following actions to enhance your logging for development and learning purposes:

1. Create a parameter by clicking the empty field in the Parameter column.
2. Select the stdout_callback task parameter.
3. Enter yaml in the Value column field.

Save your parameter by clicking Add to task. 1.

Select nodes: To advance to the next step in the task creation wizard, click Next: Select Nodes. During this step you can select the nodes to target with the Playbook Runner task. In this tutorial, you previously selected the node and then chose to run a task, so the Select nodes page is pre-populated with the Playbook Runner control host selected earlier. In our tutorial, the Playbook Runner host is named puppet.domain. You do not have to select additional nodes.

However, if you created the task without selecting the node first, select the Playbook Runner control host now. 1.

Review the task configuration: To review the configurations for the Playbook Runner task, click Next: Review and schedule. For this tutorial, you will run the task immediately, so you can leave the schedule on the default setting of Now. 1.

Run the playbook task: To start running the playbook, click Run task. Your arguments are sent to the Puppet Playbook Runner module, which runs the specified playbook. The Task details page displays information about the task run.

💡 Tip: Provisioning a new device can take a few minutes, so the task remains in the In progress state for some time. 1.

Confirm provisioning: In your browser, switch from the Puppet Enterprise to the host environment where your device is being provisioned. If you are using the sample tutorial playbook and steps, the load balancer is created in the AWS load balancers list in us-east-1. In the State column, you can verify that ALB provisioning is in progress: 1.

Wait for the completion: Wait for provisioning to be completed. If you are using AWS, the state of the device switches to Active when provisioning is complete. 1.

Confirm successful completion: In your browser, switch back to the tab with your Puppet Enterprise task details. You now see a successful task run displayed with the result message.

💡 Tip: With the yaml setting for the stdout_callback, you can see the output from the playbook run in detail.

✅ Success!

You now know how to create a task to run the Playbook Runner module. By running your existing playbooks through Puppet, you can keep any existing libraries of playbooks you may already have and still enjoy the benefits of using Puppet for your consolidated automation platform.

In these tutorial steps, you learned how to create a task using the Puppet Enterprise console user interface, but you can also invoke the Puppet Playbook Runner with Puppet Core, or Puppet Enterprise, at the command line. To learn more about working with the Playbook Runner at the command line, check out the documentation for running the Playbook Runner module on Puppet Core.

What If the Task Run Fails?

When building out automation, you might make mistakes. When an error occurs, the task will not be completed with a Success message. Instead, you will see messages such as Error: Running playbook failed in the task run details output.

Your first step is to check the run details for debugging information. If you have correctly set your output to yaml, you will see additional mesages that can help with troubleshooting.

If the task details output provides no additional details for debugging, you can run the playbook at a command prompt directly on your Playbook Runner control host to see the full details of your error in the console. Follow these steps to run the Puppet Playbook module at a command prompt:

1. Access the command-line interface of you Playbook Runner host.

Run a command with the following format:

ANSIBLE_STDOUT_CALLBACK=yaml ansible-playbook /root/aws-create-application-lb.yaml --extra-vars '{'alb_name': 'puppet-demo-alb', 'aws_region': 'us-east-1', 'vpc_subnets': ['prod-main-vpc-us-east-1a-public-alb', 'prod-main-vpc-us-east-1b-public-alb'], 'security_group': 'prod-main-vpc-alb-ingress-v1-sg'}' 1.

To debug your playbook, review the full output, including warnings and errors.

The ansible-playbook command includes the following elements:

ANSIBLE_STDOUT_CALLBACK=yaml: Explicitly sets the callback output for the module. Ensure that the value matches the value that you entered for the Puppet Enterprise stdout_callback task parameter to properly mimic your Puppet Enterprise task run. For example, if you put YAML here instead of yaml, an error message is generated:

ERROR! Invalid callback for stdout specified: YAML.

ansible-playbook: The command that starts the Playbook Runner module.

/root/aws-create-application-lb.yaml: The playbook path, which matches the playbook task parameter value that you specified in the Puppet Enterprise task.

–extra-vars: The values to pass into your playbook. The extra-vars value matches the additional_arguments value that you specified in the Puppet Enterprise task.

What’s Next?

This tutorial represents only one example of using playbooks as part of your overall Puppet automation strategy. Stay tuned for Puppet Edge updates and other new features that can help you and your team put Puppet orchestration at the center of your infrastructure automation, regardless of which tools you use or the types of nodes you manage.

Want to learn more right now? Check out these official docs and other resources to help you get started:

• Playbook Runner premium module (forge.puppet.com)
• Install the Playbook Runner module (help.puppet.com)
• Run a task using Playbook Runner in Puppet Enterprise (help.puppet.com)
• Running the Playbook Runner module on Puppet Core (help.puppet.com)
• Playbook example code: Create Application Load Balancer in AWS (github.com)
• Puppet Edge official product page (puppet.com)
• Expanding Your Infrastructure Automation Across the Lifecycle Using Puppet Edge (puppet.com)
• Automating Network Devices with NETCONF and YANG in Puppet Edge (puppet.com)
• Build Tasks for Network Devices Faster with Code Assistance and Puppet Edge (puppet.com)