Run Puppet on demand from the CLI

Use the puppet job run command to start an on-demand Puppet run to enforce changes on your agent nodes.

Use the puppet job run command to immediately enforce change across nodes, rather than waiting for the next scheduled Puppet run. For example, if you add a new class parameter to a set of nodes, or if you deploy code to a new Puppet environment, you might want to use this command to run Puppet across all the nodes in the impacted environment.

Each time you use the puppet job run command, you can select one, and only one, of these targets:
  • A list of one or more specific nodes, identified by certname.
  • A node group, identified by node group ID.
  • A Puppet Query Language (PQL) query defining a set of nodes.

The first time you run a command, you need to authenticate. For details, refer to Setting PE RBAC permissions and token authentication for orchestrator.

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-task run

Run Puppet on one or more specific nodes

An orchestrator job can target one or more specific nodes, identified by certname. This is useful if you want to run Puppet on a single node, a few specific nodes, nodes that are not in the same node group, or nodes that can't easily be identified by a PQL query.

Before you begin
You need to know the certnames of the node or nodes you want to target. Optionally, you can store the node names in a text file with each node name on a separate line.

Make sure you have the permissions necessary to run jobs.

Make sure you have access to the nodes you want to target.

  1. Log into your primary server or the client tools workstation.
  2. Run one of the following commands:
    • To run a job on a single node run: 
      puppet job run --nodes <NODE NAME>
    • To run a job on multiple nodes, supply a comma-separated list of node names. Do not put spaces between the node names.
      puppet job run --nodes <COMMA-SEPARATED_LIST_OF_NODE_NAMES>
    • To run a job on a list of nodes in a text file, supply the path to the text file:
      puppet job run --nodes @<PATH_TO_.txt_FILE>
    Tip: You can append additional options, such as --noop, after the node names or filepath. To learn about options you can supply to this command, refer to puppet job run command options.
Results

When you execute the puppet job run command, the orchestrator generates a job ID for the job, shows you a list of nodes targeted by the job, and proceeds to run Puppet on the targeted nodes in the appropriate order. Puppet compiles a new catalog for all nodes targeted by the job.

To view the job status, run: puppet job show <JOB_ID>

To view a list of the 50 most-recent running and completed jobs, run: puppet job show

Run Puppet on a PQL query

An orchestrator job can target a set of nodes based on a PQL query. This is useful when you want to target a variable set of nodes that meet specific conditions, such as a particular operating system. When you supply a PQL query, the orchestrator runs the job on a list of nodes generated by the PQL query.

Before you begin

Make sure you have access to the nodes you want to target.

Make sure you have the permissions necessary to run jobs and PQL queries.

  1. Log into your primary server or the client tools workstation.
  2. Run one of the following commands:
    • To supply the PQL query in the command:
      puppet job run --query '<QUERY>'
      For example:
      puppet job run --query 'nodes[certname] { facts {name = "operatingsystem" and value = "Debian" }}'
    • To supply the query in a text file:
      puppet job run --query @<PATH_TO_.txt_FILE>
    Tip: You can append additional options, such as --noop, after the query or filepath. To learn about options you can supply to this command, refer to puppet job run command options.
    The following table shows some examples of PQL queries you might use for particular node targets.
    Target PQL query
    A single node by certname 'nodes { certname = "mynode" }'
    All nodes with web in their certname 'nodes { certname ~ "web" }'
    All CentOS nodes 'inventory { facts.os.name = "CentOS" }'
    All CentOS nodes with httpd managed 'inventory { facts.operatingsystem = "CentOS" and resources { type = "Service" and title = "httpd" } }'
    All nodes with failed reports 'reports { latest_report? = true and status = "failed" }'
    All nodes matching the environment of the last received catalog 'nodes { catalog_environment = "production" }'
    Tip:

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

    To shorten the command, you can use -q in place of --query.

Results

When you execute the puppet job run command, the orchestrator generates a job ID for the job, shows you a list of nodes targeted by the job, and proceeds to run Puppet on the targeted nodes in the appropriate order. Puppet compiles a new catalog for all nodes targeted by the job.

To view the job status, run: puppet job show <JOB_ID>

To view a list of the 50 most-recent running and completed jobs, run: puppet job show

Run Puppet on a node group

An orchestrator job can target all nodes in a specific node group, identified by node group ID.

Before you begin
You need to know the node group ID of the node group you want to target. You can use the node classifier API GET /v1/groups endpoint to retrieve a list of node groups and their IDs.

Make sure you have the permissions necessary to run jobs.

Make sure you have access to the nodes you want to target.

  1. Log into your primary server or the client tools workstation.
  2. Run the following command: 
    puppet job run --node-group <NODE_GROUP_ID>
    Tip: You can append additional options, such as --noop, after the node group ID. To learn about options you can supply to this command, refer to puppet job run command options.
Results

When you execute the puppet job run command, the orchestrator generates a job ID for the job, shows you a list of nodes targeted by the job, and proceeds to run Puppet on the targeted nodes in the appropriate order. Puppet compiles a new catalog for all nodes targeted by the job.

To view the job status, run: puppet job show <JOB_ID>

To view a list of the 50 most-recent running and completed jobs, run: puppet job show

puppet job run command options

You might want to use these options with the puppet job run command. Alternately, use puppet job --help to get a complete list of options you can use with puppet job commands.

Option Description
--noop A flag indicating whether to run the job in no-op mode. No-op mode simulates changes from a new catalog without actually enforcing the changes. Excluding this option assumes noop = false, unless noop is specified elsewhere, such as the agent's puppet.conf file.

Cannot be used in conjunction with --no-noop.
--no-noop A flag indicating whether to run the job in enforcement mode and enforce a new catalog on all targeted nodes. This flag overrides noop = true if set in the agent's puppet.conf file. Cannot be used in conjunction with --noop.
--environment or -e Supply an environment name, as a string, to override the environment specified in the orchestrator configuration file. The orchestrator uses this option to tell nodes which environment to run the job in. If any nodes can’t run in the specified environment, those node runs fail. A node can run in an environment as long as it is classified into that environment in the PE node classifier.
--no-enforce-environment A flag indicating whether you want the job to ignore the environment set by the --environment flag. When you use this flag, agents run in the environment specified by the PE Node Manager or their puppet.conf files.
--description Supply a description of the job, as a string. The description appears on the job list and job details pages, and it is returned when you use the puppet job show command.
--concurrency Supply an integer specifying the maximum number of nodes to run at one time. The default is an unlimited number of nodes. You can also configure concurrent compile requests in the console.

Post-run node status

After a Puppet run, the orchestrator returns a list of targeted nodes and their run statuses.

Node runs can be in progress, completed, skipped, or failed.
  • For completed runs, the orchestrator prints the configuration version, the transaction ID, a summary of resource events, and a link to the full node run report in the console.
  • For in progress runs, the orchestrator prints the elapsed time, in seconds, since the run started.
  • When there is afailed run, subsequent or related runs might be skipped. For failed runs, the orchestrator prints an error message indicating why the run failed, a list of applications that were affected by the failure, and any applications that were affected by skipped node runs.

Use puppet job show to see a list of the 50 most-recent in progress, completed, and failed jobs.

In the console, on the Jobs page, you can review a list of jobs and to view job details for previous or in-progress jobs.

Stop an in-progress job

You can stop a job if, for example, you need to reconfigure a class or push a configuration change that the job needs. When you stop a Puppet job, in-progress jobs finish, and jobs that aren't started are canceled.

To stop a job:
  • In the console, go to Jobs, switch to the Puppet run tab, locate the job you want to stop, and click Stop.
  • If you started the job on the command line, press CTRL + C.