Running tasks from the console

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

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

There are three ways to specify the job target (the nodes you want to run tasks on):

  • A static node list

  • A Puppet Query Language (PQL) query

  • A node group

You can't combine these methods, and if you switch from one to the other, the target list clears and starts over. In other words, if you create a target list by using a node list, switching to a PQL query clears the node list. You can do a one-time conversion of a PQL query to a static node list if you want to add or remove nodes from the query results.

Run a task on a node list

Create a list of target nodes when you need to run a task on a specific set of nodes that isn't easily defined by a PQL query.

Before you begin

Install the tasks you want to use.

Make sure you have permission to run the tasks.

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

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. This defaults to 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 Job description field, provide a description. The text you enter here appears on the job list and job details pages.
  6. Optional: If you want to limit how long the task can run before being automatically cancelled, select Yes for Timeout and select the duration and unit (such as five minutes).
  7. Under Task parameters, add optional parameters and enter values for the optional and required parameters on the list.
    Important: You must click Add parameter 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 Task field.

    Express values as strings, arrays, objects, integers, or Booleans. You must express empty strings as two double-quotes with no space between (such as: ""). 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.
  8. Optional: Under Schedule, select Later and choose a start date, time, time zone, and frequency for the job to run.
  9. From the list of target types, select Node list.
  10. Create the node list.
    1. Expand the Inventory nodes target.
    2. Enter the name of the node you want to find and click Search.
      Tip: The search does not handle regular expressions, but it does support partial matches.
    3. From the list of results, select the nodes that you want to add to your list. They are added to a table below.
    4. Repeat the search to add other nodes. You can select nodes from multiple searches to create the node list.
      Tip: To remove a node from the table, select the check box next to it and click Remove selected.
  11. Click Run task or Schedule job.
    Your task run appears on the Tasks page. To rerun the task, click Run again and choose to rerun the task on all nodes or only the nodes that failed during the initial run.
    Tip: You can filter run results by task name to find specific task runs.

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 permission to run the tasks on all nodes.

  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. This defaults to 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 Job description field, provide a description. The text you enter here appears on the job list and job details pages.
  6. Optional: If you want to limit how long the task can run before being automatically cancelled, select Yes for Timeout and select the duration and unit (such as five minutes).
  7. Under Task parameters, add optional parameters and enter values for the optional and required parameters on the list.
    Important: You must click Add parameter 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 Task field.

    Express values as strings, arrays, objects, integers, or Booleans. You must express empty strings as two double-quotes with no space between (such as: ""). 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.
  8. Optional: Under Schedule, select Later and choose a start date, time, time zone, and frequency for the job to run.
  9. From the list of target types, select Node list.
  10. Create the node list.
    1. Expand the SSH nodes target.
      Restriction: This target is available only for tasks permitted to run on all nodes.
    2. Enter the target host names and the credentials required to access them. If you use an SSH key, include begin and end tags.
    3. 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.
    4. Click Add nodes. They are added to the node table.
    5. 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.
  11. Click Run task or Schedule job.
    Your task run appears on the Tasks page. To rerun the task, click Run again and choose to rerun the task on all nodes or only the nodes that failed during the initial run.
    Tip: You can filter run results by task name to find specific task runs.

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 permission to run the tasks on all nodes.

  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. This defaults to 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 Job description field, provide a description. The text you enter here appears on the job list and job details pages.
  6. Optional: If you want to limit how long the task can run before being automatically cancelled, select Yes for Timeout and select the duration and unit (such as five minutes).
  7. Under Task parameters, add optional parameters and enter values for the optional and required parameters on the list.
    Important: You must click Add parameter 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 Task field.

    Express values as strings, arrays, objects, integers, or Booleans. You must express empty strings as two double-quotes with no space between (such as: ""). 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.
  8. Optional: Under Schedule, select Later and choose a start date, time, time zone, and frequency for the job to run.
  9. From the list of target types, select Node list.
  10. Create the node list.
    1. Expand the WinRM nodes target.
      Restriction: This target is available only for tasks permitted to run on all nodes.
    2. Enter the target host names and the credentials required to access them.
    3. 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.
    4. Click Add nodes. They are added to the node table.
    5. 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.
  11. Click Run task or Schedule job.
    Your task run appears on the Tasks page. To rerun the task, click Run again and choose to rerun the task on all nodes or only the nodes that failed during the initial run.
    Tip: You can filter run results by task name to find specific task runs.

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. This defaults to 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 Job description field, provide a description. The text you enter here appears on the job list and job details pages.
  6. Optional: If you want to limit how long the task can run before being automatically cancelled, select Yes for Timeout and select the duration and unit (such as five minutes).
  7. Under Task parameters, add optional parameters and enter values for the optional and required parameters on the list.
    Important: You must click Add parameter 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 Task field.

    Express values as strings, arrays, objects, integers, or Booleans. You must express empty strings as two double-quotes with no space between (such as: ""). 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.
  8. Optional: Under Schedule, select Later and choose a start date, time, time zone, and frequency for the job to run.
  9. From the list of target types, select PQL query.
  10. 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" } }
  11. Click Submit query and click Refresh to update the node results.
  12. If you change or edit the query after it runs, click Submit query again.
  13. 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.
  14. Click Run task or Schedule job.
    Your task run appears on the Tasks page. To rerun the task, click Run again and choose to rerun the task on all nodes or only the nodes that failed during the initial run.
    Tip: You can filter run results by task name to find specific task runs.
Results
Important: When you run this job, the PQL query runs again, and the job might run on a different set of nodes than what is currently displayed. If you want the job to run only on the list as displayed, convert the query to a static node list before you run the job.

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 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 permission to run the tasks.

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.
  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. This defaults to 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 Job description field, provide a description. The text you enter here appears on the job list and job details pages.
  6. Optional: If you want to limit how long the task can run before being automatically cancelled, select Yes for Timeout and select the duration and unit (such as five minutes).
  7. Under Task parameters, add optional parameters and enter values for the optional and required parameters on the list.
    Important: You must click Add parameter 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 Task field.

    Express values as strings, arrays, objects, integers, or Booleans. You must express empty strings as two double-quotes with no space between (such as: ""). 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.
  8. Optional: Under Schedule, select Later and choose a start date, time, time zone, and frequency for the job to run.
  9. From the list of target types, select Node group.
  10. In the Choose a node group box, type or select a node group, and click Select.
  11. Click Run task or Schedule job.
    Your task run appears on the Tasks page. To rerun the task, click Run again and choose to rerun the task on all nodes or only the nodes that failed during the initial run.
    Tip: You can filter run results by task name to find specific task runs.