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. 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 (true or false). You must express empty strings as two double quotes with no space (""). Structured values, like an array, must be valid JSON.
    Tasks with default values run using the default value unless another value is specified.
    Note: The parameters you supplied the first time you ran a task will be used for subsequent tasks run when using the Run again feature on the Task details page.
  7. Optional: Under Schedule, select Later and choose a start date, time, time zone, and frequency for the job to run.
  8. From the list of target types, select Node list.
  9. Create the node list.
    1. Expand the Inventory nodes target.
    2. Enter the name of the node you want to find and click Search.
      Note: The search does not handle regular expressions but 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 checkbox next to it and click Remove selected.
  10. 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 on the nodes that failed during the initial run.
    Tip: 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. 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 (true or false). You must express empty strings as two double quotes with no space (""). Structured values, like an array, must be valid JSON.
    Tasks with default values run using the default value unless another value is specified.
    Note: The parameters you supplied the first time you ran a task will be used for subsequent tasks run when using the Run again feature on the Task details page.
  7. Optional: Under Schedule, select Later and choose a start date, time, time zone, and frequency for the job to run.
  8. From the list of target types, select Node list.
  9. Create the node list.
    1. Expand the SSH nodes target.
      Note: 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 a table below.
    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 checkbox next to it and click Remove selected.
  10. 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 on the nodes that failed during the initial run.
    Tip: 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. 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 (true or false). You must express empty strings as two double quotes with no space (""). Structured values, like an array, must be valid JSON.
    Tasks with default values run using the default value unless another value is specified.
    Note: The parameters you supplied the first time you ran a task will be used for subsequent tasks run when using the Run again feature on the Task details page.
  7. Optional: Under Schedule, select Later and choose a start date, time, time zone, and frequency for the job to run.
  8. From the list of target types, select Node list.
  9. Create the node list.
    1. Expand the WinRM nodes target.
      Note: 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 a table below.
    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 checkbox next to it and click Remove selected.
  10. 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 on the nodes that failed during the initial run.
    Tip: 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 permissions 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. 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 (true or false). You must express empty strings as two double quotes with no space (""). Structured values, like an array, must be valid JSON.
    Tasks with default values run using the default value unless another value is specified.
    Note: The parameters you supplied the first time you ran a task will be used for subsequent tasks run when using the Run again feature on the Task details page.
  7. Optional: Under Schedule, select Later and choose a start date, time, time zone, and frequency for the job to run.
  8. From the list of target types, select PQL query.
  9. 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 is 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" } }
  10. Click Submit query and click Refresh to update the node results.
  11. If you change or edit the query after it runs, click Submit query again.
  12. 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.
    Note: 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. 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 on the nodes that failed during the initial run.
    Tip: 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 PQL queries to the console and quickly access them when running jobs.

  1. On the primary server, copy the custom_pql_queries.json.example file and remove the .example suffix:
    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 do not have permissions to view a node group, or the node group doesn't have any matching nodes, that node group won't be listed as an option for viewing. In addition, a node group does not appear if no rules have been specified for it.
  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. 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 (true or false). You must express empty strings as two double quotes with no space (""). Structured values, like an array, must be valid JSON.
    Tasks with default values run using the default value unless another value is specified.
    Note: The parameters you supplied the first time you ran a task will be used for subsequent tasks run when using the Run again feature on the Task details page.
  7. Optional: Under Schedule, select Later and choose a start date, time, time zone, and frequency for the job to run.
  8. From the list of target types, select Node group.
  9. In the Choose a node group box, type or select a node group, and click Select.
  10. 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 on the nodes that failed during the initial run.
    Tip: Filter run results by task name to find specific task runs.