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.
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:
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
.
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
.
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>
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
.
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>
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
.
Ensure you have the correct permissions to use PQL queries.
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" }'
The following table shows common options for the puppet job plan
command. For a complete list of options, run puppet job --help
.
Option | Value | Description |
---|---|---|
--environment , -e |
Environment name |
Overrides the environment specified in the orchestrator configuration file. The orchestrator uses this option to:
|
--concurrency |
Integer |
Limits how many nodes can run concurrently. (Default is unlimited.) You can tune concurrent compile requests in the PE console. |
The puppet job plan
command returns the following:
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 usepuppet job run
.Use the job ID to view jobs with the
puppet job show
command.
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.
The following is an example plan summary for a job that will run on a list of nodes that contain a partial application instance.
After you view the plan:
puppet job run <SAME TARGET AND OPTIONS>
to create and run a job like this.