How Puppet orchestrator works

With the Puppet orchestrator, you can run Puppet, tasks, or plans on-demand.

When you run Puppet on-demand with the orchestrator, you control the rollout of configuration changes when and how you want them. You control when Puppet runs and where node catalogs are applied (from the environment level to an individual node). You no longer need to wait on arbitrary run times to update your nodes.

Puppet tasks allow you to execute actions on target machines. A "task" is a single action that you execute on the target via an executable file. For example, do you want to upgrade a package or restart a particular service? Set up a Puppet task run to enforce to make those changes at will.

Puppet plans are bundles of tasks that can be combined with other logic. They allow you to do complex operations, like run multiple tasks with one command or automatically run certain tasks based on the output of another task.

Tasks and plans are packaged and distributed as Puppet modules.

Puppet orchestrator technical overview

The orchestrator uses pe-orchestration-services, a JVM-based service in Puppet Enterprise (PE), to execute on-demand Puppet runs on agent nodes in your infrastructure. The orchestrator uses Puppet Execution Protocol (PXP) agents to orchestrate changes across your infrastructure.

The orchestrator (part of pe-orchestration-services) controls the functionality for the puppet job, puppet task, and puppet plan commands, and it also controls the functionality for jobs and single-node runs in the PE console.

The orchestrator is comprised of several components, each with their own configuration and log locations.

Puppet orchestrator architecture

The orchestrator's functionality derives from the Puppet Execution Protocol (PXP), the Puppet Communications Protocol (PCP), and the Agentless Catalog Executor (ACE) Server.
Puppet Execution Protocol (PXP)
A message format used to request that a task be executed on a remote host and receive responses on the status of that task.
Used by pe-orchestration-services to run Puppet on agents.
PXP agent
A system service in the agent package that runs PXP.
Puppet Communications Protocol (PCP)
The underlying communication protocol that describes how PXP messages get routed to an agent and back to the orchestrator.
PCP broker
A JVM-based service that runs in pe-orchestration-services on the primary server and in the pe-puppetserver service on compilers.
PCP brokers route PCP messages, which declare the content of the message (via message type) and identify the sender and intended recipient.
PCP brokers on compilers connect to the orchestrator, and the orchestrator uses the brokers to direct messages to PXP agents connected to the compilers. When using compilers, PXP agents running on PE components (which includes the primary server, PuppetDB, and the PE console) connect directly to the orchestrator, but all other PXP agents connect to compilers via load balancers.
Agentless Catalog Executor (ACE) service
A Ruby service that enables you to execute tasks, plans, and Puppet runs on remotely on agentless targets. Refer to PE ACE server configuration for more information.
Bolt vs ACE: Orchestrator uses both ACE and Bolt to run tasks and plans. While both can act on agentless targets, the primary difference is that Bolt server works with agentless nodes over WinRM or SSH, whereas ACE works with agentless devices, like network switches and firewalls, over other transports. Go to PE Bolt server configuration to learn about how Bolt works in PE and configuring the Bolt server.

What happens during an on-demand run from the orchestrator ?

Several PE services interact when you Run Puppet on demand from the orchestrator.

  1. You use the puppet job command to create a job in orchestrator.
  2. The orchestrator validates your token with the PE RBAC service.
  3. The orchestrator requests environment classification from the node classifier for the nodes targeted in the job. It also queries PuppetDB for the nodes.
  4. The orchestrator creates the job ID and starts polling nodes in the job to check their statuses.
  5. The orchestrator queries PuppetDB for the agent version on the nodes in the job.
  6. The orchestrator tells the PCP broker to start runs on the nodes in the job, and Puppet runs start on those agents.
  7. Agents send run results to the PCP broker.
  8. The orchestrator receives run results and requests node run reports (also called agent run reports) from PuppetDB.

What happens during a task run from the orchestrator?

Several services interact during task runs. Because tasks are Puppet code, they must be deployed into an environment on the primary server. Puppet Server then exposes the task metadata to the orchestrator. When a task runs, the orchestrator sends the PXP agent a URL indicating where to fetch the task from (on the primary server) and the task file's checksum. The PXP agent downloads the task file from the supplied URL and caches it for future use. The file is validated against the checksum before every execution. This process is comprised of the following steps:

  1. The PE client sends a task command.
  2. The orchestrator checks if the user is authorized.
  3. The orchestrator fetches the node target from PuppetDB (if the target is a query) and returns the list of targeted nodes.
  4. The orchestrator requests task data from Puppet Server.
  5. Puppet Server returns task metadata, file URIs, and file SHAs.
  6. The orchestrator validates the task command and then sends the job ID back to the client.
  7. The orchestrator sends task parameters and file information to the PXP agent.
  8. The PXP agent sends a provisional response to the orchestrator, checks the SHA against the local cache, and requests the task file from Puppet Server.
  9. Puppet Server returns the task file to the PXP agent.
  10. The task runs.
  11. The PXP agent sends the result to the orchestrator.
  12. The client requests events from the orchestrator.
  13. The orchestrator returns the result to the client.