Run Puppet on demand from the console

When you set up a job to run Puppet from the console, the orchestrator creates a job ID to track the job, shows you all nodes included in the job, and runs Puppet on the targeted nodes in the appropriate order. Puppet compiles a new catalog for each node included in the job.

You can specify one, and only one, of these targets for a job:
  • A list of one or more specific nodes.
  • A node group.
  • A Puppet Query Language (PQL) query defining a set of nodes.
Tip: When configuring the job in the console, if you switch the target method in the Select a target type dropdown, then the target list clears and you must re-select the target nodes. However, you can perform a one-time conversion of a PQL query to a static node list if you want to add or remove specific nodes from the query results.

Run Puppet on one or more specific nodes

An orchestrator job can target one or more specific nodes. 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 single 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.

Tip: You can add network devices to a node list when you have installed modules for device transports in your production environment. You can find such modules in Puppet Forge.
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, on 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 Node list.
  7. In the search field, search for and select the nodes you want to add to the job.
    You can select nodes from multiple searches to create a complete list of the nodes you want to target.
    The search does not handle regular expressions.
    Nodes you select are added to the list under Nodes selected for this job. To remove nodes from the list, you can click Edit selection.
  8. When you have selected all the nodes you want to target, click Next: Review and schedule.
  9. Review the details of your job configuration and the selected nodes. To make changes, you can click Edit in the Configure job and Select nodes summaries, or click Back to return to previous steps.
  10. 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.

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.

To run PQL queries, you need the View node data from PuppetDB permission.

Tip: You can Add custom PQL queries to the console to quickly select them when running jobs.
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, on 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.
      Note: 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.operatingsystem = "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.
    Tip: 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.
What to do next
Important: Unless you converted your PQL query to a node list, each time you run this job the PQL query runs again. Therefore, the job might run on a different set of nodes each time, depending on how your inventory has changed between runs. If you want the job to run on the same set of nodes queried when you originally created the query, you must convert the query to a node list before you run the job again.

Add custom PQL queries to the console

Add your own Puppet Query Language (PQL) queries to the console to quickly access them when running jobs.

For help forming queries, go to the PQL Reference guide in the Puppet documentation.
  1. On the primary server, copy the custom_pql_queries.json.example file, and remove the .example suffix. For example, you can use this command: 
    sudo cp
/etc/puppetlabs/console-services/custom_pql_queries.json.example 
/etc/puppetlabs/console-services/custom_pql_queries.json
  2. Edit the file contents to include your own PQL queries or remove any existing queries.
  3. Refresh the console UI in your browser.
Results
You can now see your custom queries in the PQL drop-down options when running jobs.

Run Puppet on a node group

An orchestrator job can target all nodes in a specific node group.

Before you begin

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

Note: If you don't have permission to view a node group, or the node group doesn't have any matching nodes, that node group isn't listed as an option. In addition, node groups don't appear if they have no rules specified.
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, on 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 Node group.
  7. From the Choose a node group dropdown, type or select a node group, and click Select.
  8. Optional: To convert the list of nodes captured by the selected node group into a static list of nodes, click Convert query to static node list.
    Tip: 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.
  9. When you have selected the node group containing the nodes you want to target or have created a static list of targeted nodes, click Next: Review and schedule.
  10. 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.

Run jobs from other node lists

In addition to the Jobs page, you can run Puppet jobs on lists of nodes shown on the Status, Events, and some Node groups pages.

Before you begin

Make sure you have the permissions necessary to run jobs.

For information about creating jobs on the Jobs page, refer to Run Puppet on one or more specific nodes, Run Puppet on a PQL query, and Run Puppet on a node group.

  1. In the console, go to one of these pages and, depending on the page, go to the specific section or tab containing the node list you want to target:
    • Status: This page shows a list of all your managed nodes, and gathers essential information about your infrastructure at a glance.
    • Events page, Nodes with events section: This page shows a summary of activity in your infrastructure and helps you analyze the details of important changes or investigate common causes behind related events. For example, if your Puppet runs are failing due to outdated code, after you update the code, you can create a job targeting the nodes listed as failed on the Events page. The ensures you're targeting the particular failed nodes you want to target.
    • Node groups pages for classification node groups: Node groups automate classification of nodes with similar functions in your infrastructure. If you make a classification change to a node group, you can quickly create a job to run Puppet on all the nodes in that group, pushing the change to all those nodes at once.
  2. Click Run > Puppet.
    The list of nodes from the page, or page section, you were viewing is converted to a list of target nodes for the new Puppet run.
  3. Optional: In the Job description field, provide a description. The text you enter here appears on the job list and job details pages.
  4. 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.
  5. 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.
  6. Important: Do not change the Node selection method from Node list to PQL query in the dropdown. Changing the node selection method clears the targeted nodes list.
  7. Click Next: Review and schedule.
  8. 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.

Schedule a Puppet run

Schedule a job to deploy configuration changes at a particular date and time or on a recurring schedule.

Before you begin

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

If a reboot occurs or you restore a backup, scheduled Puppet jobs are rescheduled based on the last execution time. If a reboot is caused by a scheduled Puppet job running in the orchestrator, that job returns a failed status.
  1. In the console, on 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 a target type.
    • Node list: Add individual nodes by name.
    • PQL Query: Use the Puppet query language to retrieve a list of nodes.
    • Node group: Select an existing node group.
    For details about the target options, refer to Run Puppet on one or more specific nodes, Run Puppet on a PQL query, and Run Puppet on a node group.
  7. When you have used one of the node selection methods to select the nodes you want to target click Next: Review and schedule.
  8. Under Schedule, select Later and choose a start date, time, time zone, and frequency for the job to run.
  9. Optional: To repeat the job on a regular schedule, change the run frequency from Once to Hourly, Daily, or Weekly.
    Note: If a recurring job's run overlaps with the next scheduled run, the job skips the overlapped time and doesn't run again until the next scheduled start time.
  10. Click Schedule job.
Results
Your job appears on the Scheduled Puppet run tab of the Jobs page.

Edit a scheduled job

You can view and edit a scheduled job if, for example, you want to change the selected run options or add nodes to the job.

If you want to edit a scheduled job created by another user, you must have the appropriate role-based permissions to do so.
  1. In the console, go to Jobs and switch to the Scheduled Puppet run tab.
  2. In the list of scheduled jobs, locate the job you want to edit and click the view icon.
  3. On the View scheduled job page, click Actions > Edit in the upper right corner.
  4. Make your required changes and click Save changes.

Delete a scheduled job

You can delete a job that you've scheduled to run at a later time or at recurring intervals.

If you want to delete a scheduled job created by another user, you must have the appropriate role-based permissions to do so.
  1. In the console, go to Jobs and switch to the Scheduled Puppet Run tab.
  2. Locate the scheduled job you want to delete and click the trashcan icon.
  3. Confirm that you want to remove the scheduled job.

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.