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 Inventory drop-down list, 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. Select an environment:
    • 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: Select an environment from the 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. 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. In the Inventory list, select Node list.
  6. To create a node list, in the search field, start typing in the names of nodes to search for, and click Search.
    The search does not handle regular expressions.
  7. Select the nodes you want to add to the job. You can select nodes from multiple searches to create a complete target node list.
  8. Click Run job.
    View the job status and a list of previous Puppet jobs on the Jobs page. To rerun the job, click Run again and choose 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. Select an environment:
    • 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: Select an environment from the 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. 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. From the list of target types, select PQL query.
  6. Specify a target by doing one of the following:
    • Enter a query that selects the target you want. See the Puppet Query Language (PQL) reference for more information.
    • Click Common queries, select one of the queries, and replace the defaults in the braces ({ }) with values that specify the target you want.
      Note: These queries include [certname] as [<projection>] to restrict the output.
      Target PQL query
      All nodes nodes[certname] { }
      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" } }
  7. Click Submit query and click Refresh to update the node results.
  8. If you change or edit the query after it runs, click Submit query again.
  9. Optional: To convert the PQL query target results to a node list, for use as a node list target, 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.
  10. Click Run job.
    View the job status and a list of previous Puppet jobs on the Jobs page. To rerun the job, click Run again and choose 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. Select an environment:
    • 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: Select an environment from the 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. 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. From the list of target types, select Node group.
  6. In the Choose a node group box, type or select a node group, and click Select.
  7. Click Run job.
    View the job status and a list of previous Puppet jobs on the Jobs page. To rerun the job, click Run again and choose 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 Overview, 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:
    • Overview: 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 new Puppet run job list target.
  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. Select an environment:
    • 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: Select an environment from the 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. 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 Inventory from Node list to PQL query. This clears the node list target.
  7. Click Run job.
    View the job status and a list of previous Puppet jobs on the Jobs page. To rerun the job, click Run again and choose 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. Select an environment:
    • 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: Select an environment from the 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 Schedule, select Later and choose a start date, time, time zone, and frequency for the job to run.
  5. 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.
  6. 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.
  7. From the list of target types, select the category of nodes you want to target.
    • 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.
  8. Click Schedule job.
Results
Your job appears on the Scheduled Puppet run tab of the Jobs page.

Delete a scheduled job

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.
  2. Switch to the Scheduled Puppet Run tab.
  3. Locate the scheduled job you want to delete and click Remove.

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.