Running Puppet jobs
Three actions are available with the puppet-job command:
- Run a job.
- Check the plan of a potential job run, described in Checking Puppet job plans.
- View the details of a running or completed job, or view a list of running and completed jobs, described in Reviewing Puppet jobs.
Note: The first time you run a command, you need to authenticate. See the orchestrator client install page for information about setting RBAC permissions and token authorization.
run action (
puppet job run) initiates the orchestration job. It creates a new Job ID, shows you all nodes included in the job, and proceeds to run Puppet on all nodes in the appropriate order.
puppet job run command
puppet job run command to trigger the Puppet orchestrator to create a new job and run Puppet on all included nodes. You can run jobs on one of three types of targets:
To run a job across an entire environment
puppet job run <OPTIONS> <ENVIRONMENT>
If you don’t specify any options or an environment, Puppet will run in order on all nodes in a Puppet environment (the default environment is
Note that if you want to run Puppet on all nodes in a given environment, Application Orchestration services must be enabled for that environment, but the nodes DO NOT need to be hosting application components. However, review the note about environment mismatches on Puppet job runs for details on what to expect if an agent detects an environment mismatch.
To run a job on all instances of an application in an environment
puppet job run <APPLICATION> <OPTIONS>
In this case, Puppet runs in order on all nodes that are found in each instance of an application.
To run a job that will configure a single application instance in an environment
puppet job run <APPLICATION INSTANCE> <OPTIONS>
In this case, Puppet runs in order on all nodes found in a specific application instance.
Note: The default environment is
production. This can be changed in the client config file (
~/.puppetlabs/client-tools/orchestrator.conf). Additionally, you can override this with the
--env or -eoption.
The following are common options you may use with the
run action. For a complete list of global options run
puppet job --help.
||flag||Overrides the URL setting for the orchestrator service.|
||flag, default false||Run a deployment job without executing the changes.|
||environment name||Overrides the environment specified in your orchestrator configuration file.|
||flag||Limits how many nodes can run concurrently. (Default is unlimited.) You can tune concurrent compile requests in the PE console.|
Review the job plan
Tip: You can use the
puppet-job plancommmand to print the plan that would be generated if you ran a Puppet job. The job plan shows application instances and the node run order that would be included in a job run with the same options.
When you execute a
puppet job run command, the orchestrator service shows the plan for the run and immediately runs the job.
The job plan shows:
- The job ID. A job ID is created when you run a Puppet job. It can be used to view jobs with the
- The environment the job will run in.
- The target for the job.
- A list of application instances included in the job.
- The total number of nodes in the job.
- The maximum concurrency setting for the job.
- A list of nodes sorted topographically, with components and application instances listed below each node. The node list is organized in levels by dependencies. Nodes shown at the top, Level 0, have no dependencies. Nodes in Level 1 have dependencies above it in Level 0. A node can run once Puppet has finished running on all its dependencies.
Note: Job run summaries that do not execute applications will not show any information about applications and components.
Example job plan
The following is an example plan summary for a job that will run on the entire
production environment (the default environment). Nodes not participating in an application are displayed at level 0 as they have no dependencies and can run immediately.
Node run status
In addition to details about the job, the command returns a list of nodes in the run. Node runs can be in progress, completed, skipped, or failed.
- For a completed node run, the orchestrator prints the following information:
- The configuration version.
- The transaction ID.
- A summary of resource events.
- A link to the full node run report in the PE console.
For an in progress node run, the orchestrator prints how many seconds ago the run started.
- For a failed node run, the orchestrator prints an error message indicating why the run failed. In this case, any additional runs will be skipped.
You can view the status of all running, completed, and failed jobs with the
puppet job show command.
To terminate a running job, use
When you terminate a job, any Puppet runs that are underway will finish. Any runs that have not started will not start.
Analyze changes and events in the PE console
The PE console helps you investigate the current state of your infrastructure by drilling down into failures and other changes. The node graph provides a graph view of a node’s catalog to help you locate and solve problems by finding which resources are causing nodes to fail or which resources have changed.
Use these tools for a closer look at successes and failures in your Orchestration runs.