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" }'

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" }'`

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.