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.

To schedule a recurring Puppet run or schedule a single run for a later time or date, refer to Schedule a Puppet run.

1. In the console, in the Jobs page, click Run Puppet.
2. Optional: In the Job description field, provide a description. The text you enter here appears on the job list and job details pages.
3. Under Environment, select one of the following options to specify the environment you want the nodes to run in:
   • Run nodes in their own assigned environment: Nodes run in the environment specified by the Node Manager or their puppet.conf file.
   • Select an environment for nodes to run in: Nodes run in the environment you select from the dropdown list. Nodes can run in an environment if their environment is agent-specified or if they're classified in that environment by the node manager.
4. Under Run options, select the run mode for the job. The default run mode for a job always attempts to enforce new catalogs on nodes. To change the run mode, use the following selections:
   • No-op: Simulate a Puppet run on all nodes in the job without enforcing a new catalog.
   • Debug: Print all debugging messages.
   • Trace: Print stack traces on some errors.
   • Eval-trace: Display how long it took for each step to run.
   • Override noop = true configuration: If any nodes in the job have noop = true set in their puppet.conf files, Puppet ignores that setting and enforce a new catalog on those nodes. This setting corresponds to the --no-noop flag available on the orchestrator CLI.
5. Click Next: Select nodes.
6. Under Node selection method, from the dropdown, select PQL query.
7. Specify the target nodes by doing one of the following:
   • Enter a PQL query that captures the nodes you want to target. See the Puppet Query Language (PQL) reference for more information.
   • From the Common queries dropdown, select one of the queries, and replace the defaults inside the braces ({ }) with values specific to nodes you want to target.

     These queries include [certname] as [<projection>] to restrict the output.

     Target	PQL query
     All nodes	nodes[certname] { }
     Nodes with a Puppet agent	inventory[certname] {facts.aio_agent_version ~ "\\d+" }
     Nodes with a specific resource (example: httpd)	resources[certname] { type = "Service" and title = "httpd" }
     Nodes with a specific fact and value (example: OS name is CentOS)	inventory[certname] { facts.os.name = "<OS>" }
     Nodes with a specific report status (example: last run failed)	reports[certname] { latest_report_status = "failed" }
     Nodes with a specific class (example: Apache)	resources[certname] { type = "Class" and title = "Apache" }
     Nodes assigned to a specific environment (example: production)	nodes[certname] { catalog_environment = "production" }
     Nodes with a specific version of a resource type (example: OpenSSL v1.1.0e)	resources[certname] {type = "Package" and title="openssl" and parameters.ensure = "1.0.1e-51.el7_2.7" }
     Nodes with a specific resource and operating system (example: httpd and CentOS)	inventory[certname] { facts.os.name = "CentOS" and resources { type = "Service" and title = "httpd" } }

8. Click Submit query and click Refresh node list to update the node results.
9. If you change or edit the query after it runs, click Submit query again.
10. Optional: To convert the list of nodes captured by the PQL query to a static list of nodes, click Convert query to static node list.
    If you select this option, the job target becomes a node list. You can add or remove nodes from the node list before running the job, but you cannot edit the query.
11. When you have submitted a query that captures the nodes you want to target or have created a static list of targeted nodes, click Next: Review and schedule.
12. Schedule the job or, to start the Puppet run immediately, click Run job.

    You can view the job status and a list of previous and scheduled jobs on the Jobs page.

    To rerun a job, click on the relevant job ID and click Run again, choosing whether to rerun it on all nodes or only the nodes that failed during the initial run.