Running jobs with Puppet orchestrator
With the Puppet orchestrator, you can run three types of "jobs": on-demand Puppet jobs, task runs, and plan runs.
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 jobs 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 task operations, like running multiple tasks with one command or automatically running 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 PE, to execute on-demand Puppet runs on agent nodes in your infrastructure. The orchestrator uses PXP agents to orchestrate changes across your infrastructure.
The orchestrator (as part of pe-orchestration-services) controls the
functionality for the puppet-job and
puppet-app commands, and 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 functionality of the orchestrator is derived from the Puppet Execution Protocol (PXP) and the Puppet Communications Protocol (PCP).
-
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. This is used by the pe-orchestration services to run Puppet on agents.
-
PXP agent: A system service in the agent package that runs PXP.
-
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 master 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 (the Puppet master, PuppetDB, and the PE console) connect directly to the orchestrator, but all other PXP agents connect to compilers via load balancers.
What happens during an on-demand run from the orchestrator ?
Several PE services interact when you run Puppet on demand from the orchestrator.
- You use the
puppet-jobcommand to create a job in orchestrator. - The orchestrator validates your token with the PE RBAC service.
- The orchestrator requests environment classification from the node classifier for the nodes targeted in the job, and it queries PuppetDB for the nodes.
- The orchestrator requests the environment graph from Puppet Server.
- The orchestrator creates the job ID and starts polling nodes in the job to check their statuses.
- The orchestrator queries PuppetDB for the agent version on the nodes targeted in the job.
- The orchestrator tells the PCP broker to start runs on the nodes targeted in the job, and Puppet runs start on those agents.
- The agent sends its run results to the PCP broker.
- The orchestrator receives run results, and requests the node run reports from PuppetDB.
What happens during a task run from the orchestrator?
Several services interact for a task run as well. Because tasks are Puppet code, they must be deployed into an environment on the Puppet master. Puppet Server then exposes the task metadata to the orchestrator. When a task is run, the orchestrator sends the PXP agent a URL of where to fetch the task from the master and the checksum of the task file. The PXP agent downloads the task file from the URL and caches it for future use. The file is validated against the checksum before every execution. The following are the steps in this process.
- The PE client sends a task command.
- The orchestrator checks if a user is authorized.
- The orchestrator fetches the node target from PuppetDB if the target is a query, and returns the nodes.
- The orchestrator requests task data from Puppet Server.
- Puppet Server returns task metadata, file URIs, and file SHAs.
- The orchestrator validates the task command and then sends the job ID back to the client.
- The orchestrator sends task parameters and file information to the PXP agent.
- 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.
- Puppet Server returns the task file to the PXP agent.
- The task runs.
- The PXP agent sends the result to the orchestrator.
- The client requests events from the orchestrator.
- The orchestrator returns the result to the client.