Running tasks from the console

Run ad-hoc tasks on targeted nodes to upgrade packages, restart services, or perform any other type of single-action executions on nodes in your inventory.

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

You can use one of the following methods to target nodes for a task: :

  • Specify a list of one or more nodes.

  • Specify a node group.

  • Use a Puppet Query Language (PQL) query to define a set of nodes.

Tip: When configuring the task 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 a task on one or more specific nodes

An orchestrator job can target one or more specific nodes. This is useful if you want to run a task on a single node, a few specific nodes, nodes that are not ins the same node group, or nodes that can't be easily identified by a single PQL query.

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 permissions necessary to run tasks.

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.
  1. In the console, in the Orchestration section, click Tasks.
  2. Click Run a task in the upper right corner of the Tasks page.
  3. In the Code environment field, select the environment where you installed the module containing the task you want to run. The default is production.
  4. In the Task field, select a task to run. For example, service.
    Note: If the tasks you expect are not available, you either have no tasks installed, or you don't have the correct permissions to run them.
  5. Optional: In the Concurrency limit field, specify the number of nodes on which the task can be executed simultaneously.
  6. Optional: In the Task description field, provide a description. The text you enter here appears on the task list and task details pages.
  7. Optional: If you want to limit how long the task can run before being automatically cancelled, under Timeout, select Yes and specify a time interval (such as 5 minutes).
  8. Under Task parameters, add optional parameters and enter values for the optional and required parameters on the list.
    Important: You must click Add to task for each optional parameter-value pair you add to the task.

    To view information about required and optional parameters for the task, select View task metadata below the Concurrency limit field.

    Express values as strings, arrays, objects, integers, or Booleans. You must express empty strings by entering a pair of double quotation marks with no space between (""). Structured values, like arrays, must be valid JSON.

    Tasks that have default values use the default values when running unless you specify other values.

    Note: The parameters you supply the first time you run a task are used for subsequent task runs when you use Run again on the Task details page.
  9. Click Next: Select nodes.
  10. Under Node selection method, from the dropdown, select Node list.
  11. On the Inventory nodes tab, in the Find in inventory search field, search for and select the nodes you want to add to the task.
    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 task. To remove nodes from the list, click Edit selection.
  12. When you have selected all the nodes you want to target, click Next: Review and schedule.
  13. 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.
  14. Schedule the task or, to run the task immediately, click Run task.
    You can view the task job status and a list of previous and scheduled tasks on the Tasks page.
    To rerun a task, click on the relevant ID and click Run again, choosing whether to rerun it on all nodes or only the nodes that failed during the initial run.

Run a task over SSH

Use the SSH protocol to run tasks on target nodes that do not have the Puppet agent installed.

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 permissions necessary to run tasks.

  1. In the console, in the Orchestration section, click Tasks.
  2. Click Run a task in the upper right corner of the Tasks page.
  3. In the Code environment field, select the environment where you installed the module containing the task you want to run. The default is production.
  4. In the Task field, select a task to run. For example, service.
    Note: If the tasks you expect are not available, you either have no tasks installed, or you don't have the correct permissions to run them.
  5. Optional: In the Concurrency limit field, specify the number of nodes on which the task can be executed simultaneously.
  6. Optional: In the Task description field, provide a description. The text you enter here appears on the task list and task details pages.
  7. Optional: If you want to limit how long the task can run before being automatically cancelled, under Timeout, select Yes and specify a time interval (such as 5 minutes).
  8. Under Task parameters, add optional parameters and enter values for the optional and required parameters on the list.
    Important: You must click Add to task for each optional parameter-value pair you add to the task.

    To view information about required and optional parameters for the task, select View task metadata below the Concurrency limit field.

    Express values as strings, arrays, objects, integers, or Booleans. You must express empty strings by entering a pair of double quotation marks with no space between (""). Structured values, like arrays, must be valid JSON.

    Tasks that have default values use the default values when running unless you specify other values.

    Note: The parameters you supply the first time you run a task are used for subsequent task runs when you use Run again on the Task details page.
  9. Click Next: Select nodes.
  10. Under Node selection method, from the dropdown, select Node list.
  11. Create the node list.
    1. Click the SSH nodes tab.
      Restriction: This target is available only for tasks permitted to run on all nodes.
    2. In the SSH node hostnames field, enter an SSH node hostname, or specify multiple SSH nodes by entering a list of hostnames separated by commas.
    3. Under Credentials, enter the SSH username and the authentication method required to access the nodes you specified. You can use one of the following authentication methods:
      • The SSH key. Make sure to include beginning and end tags.
      • The SSH password.
    4. Click Add nodes.
      Nodes you specified are listed under Nodes selected for this task.
    5. Optional: Select additional target options.
      For example, to add a target port number, select Target Port from the drop-down list, enter the number, and click Add.
    6. Repeat these steps to add other nodes. You can add SSH nodes with different credentials to create the node list.
      Tip: To remove a node from the table, select the check box next to it and click Remove selected.
  12. When you have selected all the nodes you want to target, click Next: Review and schedule.
  13. 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.
  14. Schedule the task or, to run the task immediately, click Run task.
    You can view the task job status and a list of previous and scheduled tasks on the Tasks page.
    To rerun a task, click on the relevant ID and click Run again, choosing whether to rerun it on all nodes or only the nodes that failed during the initial run.

Run a task over WinRM

Use the Windows Remote Management (WinRM) to run tasks on target nodes that do not have the Puppet agent installed.

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 permissions necessary to run tasks.

  1. In the console, in the Orchestration section, click Tasks.
  2. Click Run a task in the upper right corner of the Tasks page.
  3. In the Code environment field, select the environment where you installed the module containing the task you want to run. The default is production.
  4. In the Task field, select a task to run. For example, service.
    Note: If the tasks you expect are not available, you either have no tasks installed, or you don't have the correct permissions to run them.
  5. Optional: In the Concurrency limit field, specify the number of nodes on which the task can be executed simultaneously.
  6. Optional: In the Task description field, provide a description. The text you enter here appears on the task list and task details pages.
  7. Optional: If you want to limit how long the task can run before being automatically cancelled, under Timeout, select Yes and specify a time interval (such as 5 minutes).
  8. Under Task parameters, add optional parameters and enter values for the optional and required parameters on the list.
    Important: You must click Add to task for each optional parameter-value pair you add to the task.

    To view information about required and optional parameters for the task, select View task metadata below the Concurrency limit field.

    Express values as strings, arrays, objects, integers, or Booleans. You must express empty strings by entering a pair of double quotation marks with no space between (""). Structured values, like arrays, must be valid JSON.

    Tasks that have default values use the default values when running unless you specify other values.

    Note: The parameters you supply the first time you run a task are used for subsequent task runs when you use Run again on the Task details page.
  9. Click Next: Select nodes.
  10. Under Node selection method, from the dropdown, select Node list.
  11. Create the node list.
    1. Click the WinRM nodes tab.
      Restriction: This target is available only for tasks permitted to run on all nodes.
    2. In the WinRM node hostnames field, enter a WinRM node hostname, or specify multiple WinRM nodes by entering a list of hostnames separated by commas.
    3. Under Credentials, enter the WinRM username and password required to access the nodes you specified.
    4. Click Add nodes.
      Nodes you specified are listed under Nodes selected for this task.
    5. Optional: Select additional target options.
      For example, to add a target port number, select Target Port from the drop-down list, enter the number, and click Add.
    6. Repeat these steps to add other nodes. You can add nodes with different credentials to create the node list.
      Tip: To remove a node from the table, select the check box next to it and click Remove selected.
  12. When you have selected all the nodes you want to target, click Next: Review and schedule.
  13. 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.
  14. Schedule the task or, to run the task immediately, click Run task.
    You can view the task job status and a list of previous and scheduled tasks on the Tasks page.
    To rerun a task, click on the relevant ID and click Run again, choosing whether to rerun it on all nodes or only the nodes that failed during the initial run.

Run a task on a node group

Similar to running a task on a list of nodes that you create in the console, 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.

Make sure you have permissions necessary to run tasks.

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.
  1. In the console, in the Orchestration section, click Tasks.
  2. Click Run a task in the upper right corner of the Tasks page.
  3. In the Code environment field, select the environment where you installed the module containing the task you want to run. The default is production.
  4. In the Task field, select a task to run. For example, service.
    Note: If the tasks you expect are not available, you either have no tasks installed, or you don't have the correct permissions to run them.
  5. Optional: In the Concurrency limit field, specify the number of nodes on which the task can be executed simultaneously.
  6. Optional: In the Task description field, provide a description. The text you enter here appears on the task list and task details pages.
  7. Optional: If you want to limit how long the task can run before being automatically cancelled, under Timeout, select Yes and specify a time interval (such as 5 minutes).
  8. Under Task parameters, add optional parameters and enter values for the optional and required parameters on the list.
    Important: You must click Add to task for each optional parameter-value pair you add to the task.

    To view information about required and optional parameters for the task, select View task metadata below the Concurrency limit field.

    Express values as strings, arrays, objects, integers, or Booleans. You must express empty strings by entering a pair of double quotation marks with no space between (""). Structured values, like arrays, must be valid JSON.

    Tasks that have default values use the default values when running unless you specify other values.

    Note: The parameters you supply the first time you run a task are used for subsequent task runs when you use Run again on the Task details page.
  9. Click Next: Select nodes.
  10. Under Node selection method, from the dropdown select Node group.
  11. From the Choose a node group dropdown, type or select a node group, and click Select.
  12. 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.
  13. 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.
  14. Schedule the task or, to run the task immediately, click Run task.
    You can view the task job status and a list of previous and scheduled tasks on the Tasks page.
    To rerun a task, click on the relevant ID and click Run again, choosing whether to rerun it on all nodes or only the nodes that failed during the initial run.

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.

  1. In the console, in the Orchestration section, click Tasks.
  2. Click Run a task in the upper right corner of the Tasks page.
  3. In the Code environment field, select the environment where you installed the module containing the task you want to run. The default is production.
  4. In the Task field, select a task to run. For example, service.
    Note: If the tasks you expect are not available, you either have no tasks installed, or you don't have the correct permissions to run them.
  5. Optional: In the Concurrency limit field, specify the number of nodes on which the task can be executed simultaneously.
  6. Optional: In the Task description field, provide a description. The text you enter here appears on the task list and task details pages.
  7. Optional: If you want to limit how long the task can run before being automatically cancelled, under Timeout, select Yes and specify a time interval (such as 5 minutes).
  8. Under Task parameters, add optional parameters and enter values for the optional and required parameters on the list.
    Important: You must click Add to task for each optional parameter-value pair you add to the task.

    To view information about required and optional parameters for the task, select View task metadata below the Concurrency limit field.

    Express values as strings, arrays, objects, integers, or Booleans. You must express empty strings by entering a pair of double quotation marks with no space between (""). Structured values, like arrays, must be valid JSON.

    Tasks that have default values use the default values when running unless you specify other values.

    Note: The parameters you supply the first time you run a task are used for subsequent task runs when you use Run again on the Task details page.
  9. Click Next: Select nodes.
  10. Under Node selection method, from the dropdown, select PQL query.
  11. 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.
      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" } }
  12. Click Submit query and click Refresh node list to update the node results.
  13. If you change or edit the query after it runs, click Submit query again.
  14. 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.
  15. 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.
  16. Schedule the task or, to run the task immediately, click Run task.
    You can view the task job status and a list of previous and scheduled tasks on the Tasks page.
    To rerun a task, click on the relevant ID and click Run again, choosing whether to rerun it on all nodes or only the nodes that failed during the initial run.
Results
Important: Unless you converted your PQL query to a node list, each time you run this task 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 task 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 task 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.

Schedule a task

Schedule a task to perform single-action executions at a particular date and time or on a recurring schedule.

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 permissions necessary to run tasks.

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, in the Orchestration section, click Tasks.
  2. Click Run a task in the upper right corner of the Tasks page.
  3. In the Code environment field, select the environment where you installed the module containing the task you want to run. The default is production.
  4. In the Task field, select a task to run. For example, service.
    Note: If the tasks you expect are not available, you either have no tasks installed, or you don't have the correct permissions to run them.
  5. Optional: In the Concurrency limit field, specify the number of nodes on which the task can be executed simultaneously.
  6. Optional: In the Task description field, provide a description. The text you enter here appears on the task list and task details pages.
  7. Optional: If you want to limit how long the task can run before being automatically cancelled, under Timeout, select Yes and specify a time interval (such as 5 minutes).
  8. Under Task parameters, add optional parameters and enter values for the optional and required parameters on the list.
    Important: You must click Add to task for each optional parameter-value pair you add to the task.

    To view information about required and optional parameters for the task, select View task metadata below the Concurrency limit field.

    Express values as strings, arrays, objects, integers, or Booleans. You must express empty strings by entering a pair of double quotation marks with no space between (""). Structured values, like arrays, must be valid JSON.

    Tasks that have default values use the default values when running unless you specify other values.

    Note: The parameters you supply the first time you run a task are used for subsequent task runs when you use Run again on the Task details page.
  9. Click Next: Select nodes.
  10. 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 a task on one or more specific nodes, Run a task on a PQL query, and Run a task on a node group.
  11. When you have used one of the node selection methods to select the nodes you want to target click Next: Review and schedule.
  12. Under Schedule, select Later and choose a start date, time, time zone, and frequency for the job to run.
  13. 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.
  14. Click Schedule task.
Results
Your job appears on the Scheduled Tasks tab of the Tasks page.

Edit a scheduled task

You can view and edit a scheduled task 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 task created by another user, you must have the appropriate role-based permissions to do so.
  1. In the console, go to Tasks and switch to the Scheduled Tasks tab.
  2. In the list of scheduled tasks, locate the task job you want to edit and click the view icon.
  3. On the View scheduled task page, click Edit task in the upper right corner.
  4. Make your required changes and click Save changes.

Delete a scheduled task

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