The puppet job plan command allows you to preview a plan for a Puppet job without actually enforcing any change. Use this command to ensure your job will run as expected.

View a job plan

Use the puppet job plan command to print the plan that would be generated if you ran a Puppet job.

You can preview plans for three types of targets, but these targets cannot be combined:

• View a plan to enforce change on a an application or an application instance in an environment
• View a plan to enforce change on a list of nodes or a single node
• View a plan to enforce change based on a PQL nodes query

Note: The first time you run a command, you need to authenticate. See the orchestrator installation instructions for information about setting RBAC permissions and token authorization.

Note: If you’re running this command from a managed or non-managed Windows workstation, you must specify the full path to the command. For example, c:\Program Files\Puppet Labs\Client\bin\puppet-job plan.

View a job plan for applications or application instances

You can view a plan for enforcing change on all instances of an application or for a specific instance of an application.

Tip: You can use -a in place of --application.

1. Log into your Puppet master or client tools workstation and run one of the following commands:

   • To view a job plan for all instances of an application:

     puppet job plan --application <APPLICATION> <OPTIONS>
     

   • To view a job plan for an application instance in an environment:

     puppet job plan --application <APPLICATION INSTANCE> <OPTIONS>
     

View a job plan for a list of nodes or a single node

You can view a plan for enforcing change on a single node or a comma-separated list of nodes.

Tip: You can use -n in place of --nodes.

1. Log into your Puppet master or client tools workstation and run one of the following commands:

   • To view a plan for a single node:

     puppet job plan --nodes <NODE NAME> <OPTIONS>
     

   • To view a plan for a list of nodes, use a comma-separated list of node names.

     puppet job plan --nodes <NODE NAME>, <NODE NAME>, <NODE NAME>, <NODE NAME> <OPTIONS>
     

View a job plan for a PQL nodes query

Use a PQL nodes query as a Puppet job target. In this case, the orchestrator presents a plan for a job that could run on a list of nodes returned from a PQL nodes query.

Tip: You can use -q in place of --query.

1. Ensure you have the correct permissions to use PQL queries.

2. Log into your Puppet master or client tools workstation and run the following command:

   puppet job plan --query '<QUERY>' <OPTIONS>
   

Note: The following table shows some example targets and the associated PQL queries you could run with the orchestrator.

Be sure to wrap the entire query in single quotes and use double quotes inside the query.

Target	PQL query
Single node by certname	--query 'nodes { certname = "mynode" }'
All nodes with “web” in certname	--query 'nodes { certname ~ "web" }'
All CentOS nodes	--query 'inventory { facts.os.name = "CentOS" }'
All CentOS nodes with httpd managed	--query 'inventory { facts.operatingsystem = "CentOS" and resources { type = "Service" and title = "httpd" } }'
All nodes with failed reports	--query 'reports { latest_report? = true and status = "failed" }'
All nodes matching the environment for the last received catalog	--query 'nodes { catalog_environment = "production" }'

Command options

The following table shows common options for the puppet job plan command. For a complete list of options, run puppet job --help.

Reviewing the job plan

The puppet job plan command returns the following:

• The environment the job will run in.
• The target for the job.
• The maximum concurrency setting for the job.
• The total number of nodes in the job run.
• A list of application instances included in the job, if applicable.
• 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 in level 0. A node can run once Puppet has finished running on all its dependencies.

Important: The puppet job plan does not generate a job ID. A job ID is only created, and shown in the job plan, when you use puppet job run.

Use the job ID to view jobs with the puppet job show command.

Example job plans

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 because they have no dependencies and can run immediately.

(Click to enlarge)

The following is an example plan summary for a job that will run on a list of nodes that contain a partial application instance.

(Click to enlarge)

After you view the plan:

• Use puppet job run <SAME TARGET AND OPTIONS> to create and run a job like this.
• Remember that node catalogs may have changed since this plan was generated.
• Review and address any errors that the service reports it will encounter when running the job. For example, it will detect any dependency cycles or components that not properly mapped to nodes.