Running Puppet on nodes

Puppet automatically attempts to run on each of your nodes every 30 minutes. To trigger a Puppet run outside of the default 30-minute interval, you can manually trigger a Puppet run.

In a Puppet run, the primary server and agent nodes perform these actions:
  1. Each agent node sends facts to the primary server and requests a catalog.
  2. The primary server compiles and returns each agent's catalog.
  3. Each agent applies the catalog by checking each resource the catalog describes. If the agent finds any resources that are not in the desired state, the agent makes the necessary changes to bring the resource into the desired state.
Note: Puppet run behavior differs slightly if static catalogs are enabled.

Running Puppet with the orchestrator

The Puppet orchestrator is a set of interactive tools you can use to deploy configuration changes when and how you desire.

You can use the orchestrator to enforce change on a selection of nodes identified by their certnames, a PQL query, or a node group.

You can use the orchestrator from the console, command line, or through the orchestrator API endpoints. The orchestrator API is useful if you're putting together your own tools for running Puppet or if you want to enable CI workflows across your infrastructure.

Running Puppet with SSH

To use trigger a Puppet run with SSH from an agent node, SSH into the target node and run puppet agent --test or puppet agent -t.

Running Puppet from the console

In the console, you can run Puppet from an agent node's Node details page.

Restriction: The Run Puppet button is not available if an agent does not have an active websocket session with the PCP broker, or if the node's connection method is SSH or WinRM (an agentless node), or if it is a device.
  1. In the console, go to Nodes and click the name of the node you want to run Puppet on.
  2. On the Node details page, click Run Puppet. You can configure these run options, if desired:
    • No-op: The Puppet run simulates changes without actually enforcing the new catalog. Nodes with noop = true in their puppet.conf files always run in no-op mode.
    • Debug: Prints all messages generated during the run that are available for use in debugging.
    • Trace: Prints stack traces on some errors.
    • Evaltrace: Shows a breakdown of the time taken for each step in the run.

When the Puppet run completes, the console displays the node’s run status.

Activity logging when running Puppet from the console

When you initiate a Puppet run from the console, the Activity service logs the run activity.

You can view activity for a single node by opening the node's Node details page and switching to the Activity tab.

Alternatively, you can use the Activity Service API to retrieve activity information.

Troubleshooting Puppet run failures

Puppet Enterprise (PE) creates a View Report link for most failed runs, which you can use to access the run's events and logs. You might encounter these errors when a Puppet run fails.

Changes could not be applied
Usually caused by conflicting classes. Check the run log to get information.
This error can also occur when running in no-op mode.
Run already in progress
Occurs when you try to trigger a Puppet run on a node, but there is already a Puppet run in progress. This could be a scheduled run or a run started by another user.
Run request times out
Occurs if you attempt to start a Puppet run but the agent isn’t available.
Report request times out
Occurs when the run report is not successfully stored in PuppetDB after the run completes.
Invalid response, such as a 500 error
Some part of the request is invalid. If you used the command line or the orchestrator API to start the Puppet run, check the formatting of your command or request. If you're using the console, or your command or request is well-formed, your Puppet code might be have incorrect formatting.
In the console, the Run button is disabled and a run is not allowed.
You have permission to run Puppet on the node, but the agent is not responding.