Jobs are used to run remote execution tasks, apply states, and start Salt runners. The Jobs workspace is where you can create, configure, and save job settings for reuse. Jobs are generally intended for system operations that need to be automated and executed multiple times and saves configuration time.

For example, you might have a job that creates and deploys a virtual machine and installs a base set of applications. You could run this job every time a new virtual machine needs to be deployed to ensure the same set of applications and configurations are applied to every deployment.

See SaltStack Config jobs workflow for an overview of how to use the Jobs workspace along with the other workspaces in SaltStack Config to create and use jobs for configuration management.

You can run jobs from within the Jobs workspace, the Minions workspace, or from other screens in the SaltStack Config user interface, depending on the nature of the job. You can also run jobs on a regular schedule or you could run them only as needed. Typically, jobs that run only when needed are referred to as ad-hoc jobs.

For more information about running jobs, see:

  • Running a job for information about running jobs in the Jobs workspace
  • Minions for information about running jobs in the Minions workspace
  • Schedules for information about running jobs on a schedule
Note: As part of VMware’s initiative to remove problematic terminology, the term Salt master will be replaced with a better term in SaltStack Config and related products and documentation. This terminology update may take a few release cycles before it is fully complete.

Job requirements

Each job in the Jobs workspace has predefined settings. You can edit settings on existing jobs or create a new job with its own unique settings.

In order for a job to run, it must include:

  • A function (the task that the job is meant to accomplish)
  • Either a target, a Salt master, or multiple Salt masters
  • Role-based permissions

You can define a target in a job’s settings or leave the target undefined to select a target each time the job runs. Defining a job’s target also prevents that job from running on nodes on which it should not be run. See Minions for more information.

The Jobs workspace allows you to define role-based access to each job. In addition to defining role access on the job, you must also assign roles permission to execute corresponding tasks in the Roles editor. See Roles and permissions for more information.

You can create new jobs and edit existing ones from the Jobs workspace. Once job settings are defined, you can run ad-hoc jobs, or create schedules to run jobs in the future. See Schedules for more information.

SaltStack Config includes a Run Command control that allows you to run a single command without defining a reusable job. This is useful for executing commands quickly, or running one-off jobs that are not part of your everyday workflow, for example when troubleshooting, or during initial configuration. See Running a command for more information.

You can also define which roles can view, edit, run, and delete different jobs.

Accessing the Jobs workspace

To use the Jobs workspace, click Config > Jobs on the side menu.

Creating a job

To create a new job:

  1. In the Jobs workspace, click Create job.
  2. Enter details for the new job. The details to enter depend on the type of job you want to create. See Job settings for more information.
  3. Click Save. The job is now available to run.

Running a job

To run an ad-hoc job:

  1. In the Jobs workspace, click the menu menu-icon-light next to the job you want to run.
  2. Click Run Now.
  3. In the popup, select a target to run the job on.
    Note: If the job is configured to include a target or Salt master, this is displayed for confirmation.
  4. Select additional options as required.
    • Set notification preferences
    • Select Run as Test (dry run) to run job as a test as required.
  5. Click Run Now.
    Note: You can also run jobs from the Minions workspace. See Minions.

Searching for a job

To view a list of the available jobs that have been created so far, access the Jobs workspace.

By default, only 20 jobs are shown on a page at a time. To view more jobs, click the Items per page menu at the bottom of the jobs table and select the desired number of jobs you want to view.

To find a specific job:

  1. In the Jobs workspace, click the filter button filter-icon for the column you want to search.
  2. Start typing the search criteria to see the rows filter instantly. For example, you might search for a job by the Salt module involved in a job by filtering the Function column.
    Note: You can also click any column name once to sort the rows in descending order. Click again to reverse the order. For more information about filtering, see Filtering and sorting table columns.

Filtering and sorting table columns

You can filter each column by selecting its filter icon filter-icon and selecting or typing your filter criteria. To clear a filter, click the Clear Filters button above the jobs table.

You can also sort a column by selecting the column name. To customize which columns display in the table, click the Show columns button show-columns-icon in the lower left corner of the table.

Note: Filters, column sorting, and column visibility settings are persistent for a given user, regardless of the device used to log in. This means that when a particular user logs in, he or she sees the same filtering, sorting, and visibility settings the next time he or she logs in until the filters are cleared or the sorting and visibility settings are changed.

Viewing job returns

To view job returns:

  1. In the side menu, click Activity and then Completed to see a list of completed jobs.
  2. Select a job ID in the JID column to view the job return details. See Job returns for more information.

Editing a job

To update or change a job:

  1. In the Jobs workspace, select a job.
  2. Edit job details as needed and click Save when finished.

Defining job permissions

As an administrator, you can restrict which users can run specific jobs. To define these permissions:

  1. In the Jobs workspace, select a job to open the job’s details.
  2. In the job details page, click Role Access.
  3. In the dialog, select the level of access to enable for different roles and click Save.
  4. In the job details page, click Save.
    Note: In addition to defining role access on the job, you must also assign roles permission to execute corresponding tasks in the Roles editor. See Roles and permissions for more information.

Job settings

Define job settings based on the following options.

  • Name - Enter a name for the job. This will show in the Jobs, Minions, and Activity workspaces, as well as in the Roles editor.
  • Description - Enter a description for the job (optional). This description will show in your list of jobs in the Jobs workspace.
  • Command - Specify the command to run, choosing from:
    • salt - define a job to run on a target group of minions.
    • salt-run - define a job to run on a Salt master or group of Salt masters.
    Note: SaltStack Config includes a Run Command control that allows you to run a single command without defining a reusable job. This is useful for executing commands quickly, or running one-off jobs that are not part of your everyday workflow, for example when troubleshooting, or during initial configuration. For more information, see Running a command.
  • Targets - A target is the group of minions, across one or many Salt masters, that a job’s Salt command applies to. A Salt master can also be managed like a minion and can be a target if it is running the minion service. When salt is selected in Commands, you can optionally specify the target group of minions to run the job on. If the field is left blank, you will be prompted to select a target each time the job runs.
  • All Masters - The Salt master is a central node used to issue commands to minions. When salt-run is selected in Commands, you can specify which Salt master you should run the job against. By default, All Masters is selected. If you turn this option off, the Master menu appears.

    salt-run jobs are also known as Salt runners. Salt runners are modules used to execute convenience functions on the Salt master. For more on using salt-run, see Job settings.

  • Salt Masters - When salt-run is selected in Commands and All Masters is turned off, the Master menu appears. Click this menu and select the specific Salt master you want to run the job against. You can select multiple Salt masters if needed.
  • Function - Enter a function to define what happens when the job runs. You can define a single remote execution job, a state file job, or a Salt runner job. For a list of Salt functions, see Salt Module Reference.
    • Single remote execution jobs - To define a single remote execution job, include a function and any necessary arguments in the job settings.
    • State file jobs - A state file job applies states to a target, and can be based on at least one command. A state function is a function contained inside a state module which can manage the application of a particular state to a system. State functions frequently call out to one or more execution modules to perform a given task. A highstate applies all states defined in the top file. You can view and add state files in the File Server. See File Server.

      To apply a state file to a job, use the state.apply function. To perform a highstate, use the state.apply or state.highstate function in the job settings.

      When you add a state call to a job, additional fields display where you can select the state files you want to apply. You can also pass optional pillar overrides in JSON format.

      Note: Pillar data provided on the job page is sent along with the job and other authenticated minions might be able to see it. For increased data protection, assign sensitive data in standard pillar instead. See Pillars.

      For more on Salt States, see the Salt documentation: How do I use Salt States?.

    • Salt runners - A salt-run job applies to a Salt master or group of Salt masters. salt-run jobs are also known as Salt runners. Salt runners are modules used to execute convenience functions on the Salt master. You can use Salt runners to run orchestration, power minions remotely, call webhooks, and more. They are useful for executing tasks centrally or from a central starting point. For example, you could apply a highstate to all minions associated with a given Salt master.

      To configure an orchestration runner job, use the state.orchestrate function. When you add an orchestration call to a job, additional fields display where you can list the orchestration files you want to apply. You can also pass optional pillar overrides in JSON format.

      Note: Pillar data provided on the job page is sent along with the job and other authenticated minions might be able to see it. For increased data protection, assign sensitive data in standard pillar instead. See Pillars.

      For more on Salt runners, see the Salt Runners Reference.

  • Environments - Select the environment where the state or orchestration file is located. This is a subdirectory of the root directory in the File Server. See File Server.
  • Test (dry run) - Run a test job and generate a mock job return. If you select Test, the job will not run and no changes will be made. If this option is left unselected, you can choose to run the job as a test later when you run the job. Test (dry run) is available only for certain functions. For more information, contact your administrator.