Running Ansible Playbooks from Puppet Edge

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 

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 

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. 

3. 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.

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

   

5. 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. 

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

      

6. 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. 

   

7. 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.

   3. 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. 

   4. 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!

      

8. (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. 

   4. Save your parameter by clicking Add to task. 

      

9. 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. 

   

10. 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. 

11. 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. 

    

12. 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: 

    

13. 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. 

14. 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.

2. 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'}'

3. 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)