Tasks

A task is a script that controls the application of state (SLS) on one or more minions.
To create tasks in Salt.Box, task templates are used, which can be downloaded from the SLS repositories.

info

For information on connecting repositories and a list of available templates, see these sections of the online documentation:
Task templates
SLS Repositories

Creating a task

Selecting the performers of the task

To create tasks in Salt.Box, use the minions page (you can go to this page via the Minions item in the main menu).

Salt.Box has an algorithm that determines the target minions (i.e. the minions on which the task will be executed) when creating a task:

1. All minions of the current active collection (i.e. collection selected by the user from among those available to him)

   (this option is applied by default)

2. The set of minions that is the result of applying a filter to the original collection

3. Minions selected by the user from the result of applying a filter to the original collection

The Fig. 1 shows an example in which the root collection of minions is selected by the user, then a filter is applied to this collection by the Minion ID field, and then a group of minions is selected from the result of applying the filter (the selection of minions is done by marking them with flags).

Figure 1. Selecting the performers of the task

Selecting a task template and entering general task parameters

Select the desired template.
If the template list is empty, synchronize templates as specified in the Task templates section.

Specify the general parameters of the task as shown in the Fig. 2.
The Table 1 provides a description of the general parameters of the task.
All parameters except Salt Masters are mandatory.

Figure 2. Task creation dialog

Table 1. General task parameters

Parameter	Description
Task Template	The task template to use
Salt Masters	Limit on executing master servers: if this parameter is specified, the task will be executed only on target minions registered on the specified master if this parameter is not specified, the task will be executed on target minions regardless of which master they are registered on
Batch Size	The size of the «execution window» (the maximum number of simultaneously executed tasks). Value 0 means unlimited
Max Retries	Number of attempts to execute a task in case of unsuccessful completion

Entering parameters defined in the template

The set of parameters defined in the template depends on the corresponding SLS file.
The Fig. 3 shows an example of a set of parameters defined in the Package Install template selected by the user.

Figure 3. Entering parameters defined in the template

Confirmation of task creation

After entering the parameters, click the Create Task button.
The task will be created, the task card will open Fig. 4.
The initial status of the new task is “created”.

Task card

Figure 4. Task card

The task card consists of two blocks:

• task attributes block Fig. 4 [1]

  the list of task attributes is given in the Table 2

• task execution block
  • the Minions tab Fig. 4 [2]

    the tab displays the list of processed targets (minions on which the task is running)

  • the Jobs tab Fig. 4 [3]

    the tab displays the list of jobs executed as part of the task

  • theа Job Returns tab Fig. 4 [4]

    the tab displays the list of JSON expressions—the results of executing jobs on minions

Table 2. Task attributes

Attribute	Purpose
Status	Task status
Created	Task creation time
Pending Jobs	Number of pending jobs
Processed Jobs	Number of jobs executed as part of the task
Processed Minions	Number of minions the task was performed on
Failed Minions	Number of minions on which the task failed

The order of task execution and its statuses

Task execution graph

The Fig. 5 shows the task execution graph.

The conditions for transitions between task statuses, performed automatically or by certain user actions, are given in the Table 3.

Figure 5. Task execution graph

Table 3. Transition table of the task execution graph

Edge label	Transition condition
1	The user clicked the Run button
2	The user clicked the Stop button
3	The system has performed all the necessary operations to stop the task
4	The user clicked the Run button
5	The task was completed successfully. Post-processing tasks have been created for the current task
6	The user clicked the Stop button in a child task that was started during post-processing of the current task
7	The user clicked the Run button (resumed execution) in a child task that was started during post-processing of the current task
8	Post-processing of the current task has been completed successfully
9	The task was completed successfully. There are no post-processing tasks created for the current task

Graph of execution of a job as part of a task

A job as part of a task is a Salt.Box object that combines a set of individual SaltStak Jobs sent to individual minions that are targeted and controls their execution.
Each individual minion forms its own Job Return response with the result of executing the SaltStak Job.
The resulting status of a job as part of a task thus depends on whether all jobs on individual minions have been successfully executed.

The Fig. 6 shows the graph of execution of a job as part of a task.

The conditions for transitions between job statuses are given in the Table 4.

Figure 6. Graph of execution of a job as part of a task

Table 4. Transition table of the graph of execution of a job as part of a task

Edge label	Transition condition
1	Confirmation from salt-master about creation of SaltStack Job received. Waiting for Job Return responses
2	All Job Returns received, all positive
3	All Job Returns received, there are answers with errors

Graph of execution of a job on a minion

The Fig. 7 shows the Graph of execution of a job on a minion.

The conditions for transitions between job statuses are given in the Table 5.

Figure 7. Graph of job execution on a minion

Table 5. Transition table of the graph of job execution on a minion

Edge label	Transition condition
1	Received confirmation about creating SaltStack Job from salt-master, minion was targeted. Waiting for Job Return on minion
2	Received successful Job Return on minion
3	Received negative Job Return on minion
4	Received confirmation about creating SaltStack Job from salt-master, but minion was not targeted for some reason

Task execution diagram

Figure 8. Task execution diagram

Table 6. Interactions on the task execution diagram

Interaction #	Description
1	If the minions that are the target of a task are specified using compound targeting, and either the Batch size or max. jobs parameter is specified, then the target will be converted to a set of minion lists before the commands are created. Each list will contain Batch size minions.
2	Creating Salt.Box jobs. First, max. jobs jobs will be created, subsequent jobs will be created as the previously created jobs are executed.
3	Each created Salt.Box job makes a call to the salt-master service, which generates an event of the job type: salt/job/<JID>/new.
4	The generated salt/job/<JID>/new events are published on the built-in ZeroMQ bus.
5, 6, 7, 8	In the diagram, the label "Minions of some Job #X" denotes a group of minions that are the targets of one (arbitrarily taken) job (Job #X), created in step #2. Similarly, the label "Minions of some Job #Y" denotes a group of minions that are the targets of some other job (Job #Y). Both groups contain Batch size minions. The label "SaltStak job delivered" in the diagram denotes the moments of receiving the job published on the ZeroMQ bus by minions. The moments of receiving the job are asynchronous due to different reaction times of minions. As an example, the diagram shows that minions of the group "Minions of some Job #Y" receive jobs later than minions of the group "Minions of some Job #X", and publish responses significantly later (so responses are not shown within the diagram).
9, 10	After executing the job, each minion sends a response ("Job Return") to the ZeroMQ bus.
11	The response of the last minion of the group "Minions of some Job #X" (i.e. the response published on the bus last).
12, 13	The reverse chain of minion responses from SaltStack to Salt.Box.
14	The task event handler receives a signal that all minions of the Job #X job have sent their responses (or have not responded during the timeout).
15	The Job #X command completion signal initiates the creation of the next command with the next group of Batch size addressee minions. This ensures that no more than max. jobs jobs are executed simultaneously.
16	The newly created Salt.Box job calls the salt-master service, which generates an event of the job type: salt/job/<JID>/new.
17	The salt/job/<JID>/new event is published on the built-in ZeroMQ bus.