Running tasks from the command line

Use the puppet task run command to run tasks on agent nodes.

Use the puppet task tool and the relevant module to make changes arbitrarily, rather than through a Puppet configuration change. For example, to inspect a package or quickly stop a particular service.

You can run tasks on a single node, on nodes identified in a static list, on nodes retrieved by a PQL query, or on nodes in a node group.

Use the orchestrator command puppet task to trigger task runs.

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

Run a task on a list of nodes or a single node

Use a node list target when you need to run a job on a set of nodes that doesn't easily resolve to a PQL query. Use a single node or a comma-separated list of nodes.

Before you begin

Install the tasks you want to use.

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

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

Log into your primary server or client tools workstation and run one of the following commands:
  • To run a task job on a single node: puppet task run <TASK NAME> <PARAMETER>=<VALUE> <PARAMETER>=<VALUE> --nodes <NODE NAME> <OPTIONS>
  • To run a task job on a list of nodes, use a comma-separated list of node names: puppet task run <TASK NAME> <PARAMETER>=<VALUE> <PARAMETER>=<VALUE> --nodes <NODE NAME>,<NODE NAME>,<NODE NAME>,<NODE NAME> <OPTIONS>
    Note: Do not add spaces in the list of nodes.
  • To run a task job on a node list from a text file: puppet task run <TASK NAME> <PARAMETER>=<VALUE> <PARAMETER>=<VALUE> --nodes @/path/to/file.txt
    Note: In the text file, put each node on a separate line.
For example, to run the service task with two required parameters, on three specific hosts: 
puppet task run service action=status name=nginx --nodes host1,host2,host3
Tip: Use puppet task show <TASK NAME> to see a list of available parameters for a task. Not all tasks require parameters.

Refer to the puppet task command options to see how to pass parameters with the --params flag.

Run a task on a PQL query

Create a PQL query to run tasks on nodes that meet specific conditions.

Before you begin

Install the tasks you want to use.

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

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

Log into your primary server or client tools workstation and run one of the following commands:
  • To specify the query on the command line: puppet task run <TASK NAME> <PARAMETER>=<VALUE> <PARAMETER>=<VALUE> --query '<QUERY>' <OPTIONS>
  • To pass the query in a text file: puppet task run <TASK NAME> <PARAMETER>=<VALUE> <PARAMETER>=<VALUE> --query @/path/to/file.txt
For example, to run the service task with two required parameters, on nodes with "web" in their certname: 
puppet task run service action=status name=nginx --query 'nodes { certname ~ "web" }'
Tip: Use puppet task show <TASK NAME> to see a list of available parameters for a task. Not all tasks require parameters.

Refer to the puppet task command options to see how to pass parameters with the --params flag.

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.

Run a task on a node group

Similar to running a task on a list of nodes, you can run a task on a node group.

Before you begin

Install the tasks you want to use.

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

  1. Log into your primary server or client tools workstation.
  2. Run the command: puppet task run <TASK NAME> --node-group <node-group-id>
    Tip: Use the /v1/groups endpoint to retrieve a list node groups and their IDs.

puppet task run command options

The following are common options you can use with the task action. For a complete list of global options run puppet task --help.

Option Value Description
--noop Flag, default false Run a task to simulate changes without actually enforcing the changes.
--params String Specify a JSON object that includes the parameters, or specify the path to a JSON file containing the parameters, prefaced with @, for example, @/path/to/file.json. Do not use this flag if specifying parameter-value pairs inline; see more information below.
--environment, -e Environment name Use tasks installed in the specified environment.
--description Flag, defaults to empty Provide a description for the job, to be shown on the job list and job details pages, and returned with the puppet job show command.
You can pass parameters into the task one of two ways:
  • Inline, using the <PARAMETER>=<VALUE> syntax: 
    puppet task run <TASK NAME> <PARAMETER>=<VALUE> <PARAMETER>=<VALUE> --nodes <LIST OF NODES>
puppet task run my_task action=status service=my_service timeout=8 --nodes host1,host2,host3
  • With the --params option, as a JSON object or reference to a JSON file: 
    puppet task run <TASK NAME> --params '<JSON OBJECT>' --nodes <LIST OF NODES>
puppet task run my_task --params '{ "action":"status", "service":"my_service", "timeout":8 }' --nodes host1,host2,host3
puppet task run my_task --params @/path/to/file.json  --nodes host1,host2,host3

You can't combine these two ways of passing in parameters; choose either inline or --params. If you use the inline way, parameter types other than string, integer, double, and Boolean will be interpreted as strings. Use the --params method if you want them read as their original type.

Reviewing task job output

The output the orchestrator returns depends on the type of task you run. Output is either standard output (STDOUT) or structured output. At minimum, the orchestrator prints a new job ID and the number of nodes in the task.

The following example shows a task to check the status of the Puppet service running on a list of nodes derived from a PQL query. 

[example@orch-master ~]$ puppet task run service name=puppet action=status -q 'nodes {certname ~ "br"}' --environment=production
Starting job ...
New job ID: 2029
Nodes: 8

Started on bronze-11 ...
Started on bronze-8 ...
Started on bronze-3 ...
Started on bronze-6 ...
Started on bronze-2 ...
Started on bronze-5 ...
Started on bronze-7 ...
Started on bronze-10 ...
Finished on node bronze-11
  status : running
  enabled : true
Finished on node bronze-3
  status : running
  enabled : true
Finished on node bronze-8
  status : running
  enabled : true
Finished on node bronze-7
  status : running
  enabled : true
Finished on node bronze-2
  status : running
  enabled : true
Finished on node bronze-6
  status : running
  enabled : true
Finished on node bronze-5
  status : running
  enabled : true
Finished on node bronze-10
  status : running
  enabled : true

Job completed. 8/8 nodes succeeded.
Duration: 1 sec
Tip: To view the status of all running, completed, and failed jobs run the puppet job show command, or view them from the Job details page in the console.