job interface — VMware Salt API

job interface

The LoadedMod class allows for the module loaded onto the sub to return custom sequencing, for instance it can be iterated over to return all functions

delete_job(job_uuid: <class 'uuid.UUID'>, force: bool | None)

Delete a job.

Parameters

job_uuid:	UUID referencing job to be deleted.
force:	Force deletion of target group even with schedule jobs depending on it(which will also get deleted).
raises FailedResourceDependency:	The job has one or more schedules that depend on it and force is false. The message in the exception identifies the dependent schedules.

get_job_access(job_uuid: <class 'uuid.UUID'>)

Returns: <class 'dict'>

Return access metadata for this job.

Parameters

job_uuid:	UUID referencing desired job.

get_jobs(job_uuid: uuid.UUID | None, name: str | None, desc: str | None, cmd: str | None, tgt_uuid: uuid.UUID | None, role_uuid: uuid.UUID | None, include_no_tgt_jobs: bool | None, fun: str | None, masters: list[str] | None, sort_by: str | None, reverse: bool | None, limit: int | None = 50, page: int | None)

Returns: <class 'dict'>

Get a job by uuid or search jobs by other query parameters.

Parameters

param uuid job_uuid:	UUID referencing job. If left blank, all jobs are returned.
param str name:	Text to search for in the job name
param str desc:	Text to search for in the job description
param str cmd:	Job command to match ('local', 'runner', 'wheel', or 'ssh')
param UUID tgt_uuid:	Target group UUID to match
param UUID role_uuid:	Role UUID to match (Admins only)
param bool include_no_tgt_jobs:	Include jobs that have no tgt_uuid as well
param str fun:	Salt function to match (e.g., 'test.ping')
param list masters:	List of salt master ids to match
param str sort_by:	Field to sort by ('name', 'desc', 'cmd', or 'fun')
param bool reverse:	Whether to sort in descending order
param int limit:	Maximum number of jobs to return, default 50
param int page:	Page of jobs to return (offset = page * limit)

The flag include_no_tgt_jobs is intended to be used when a list of jobs that can be run at the time is desired. For example, if a user clicks on a target in the GUI and is presented with a list of jobs that go with that target, we may also want to show jobs that have NO target attached since those jobs may be run regardless of what target is selected.

This flag has no effect if tgt_uuid is None.

The return payload is a dict with the following elements:

{
    'count': 100,     # total job count
    'limit': 50,  # results count
    'results': [...]  # jobs
}

save_job(name: str | None, desc: str | None, cmd: str | None, fun: str | None, arg: dict | None, masters: list[str] | None, job_uuid: uuid.UUID | None, tgt_uuid: uuid.UUID | None)

Returns: <class 'str'>

Create or update a job

Parameters

name:	Name to give to the job.
desc:	Descriptive text for job.
cmd:	One of local (for targeting minions), ssh (aka salt-ssh), runner (master-level command), wheel (master wheel calls)
fun:	Dotted-notation function to run (e.g. test.ping or network.ipaddrs)
arg:	A dictionary containing the keys arg and/or kwarg defining job inputs that can be supplied at execution time (details below)
masters:	A list of master names that should receive this command.
job_uuid:	UUID referencing job. If left blank, one will be generated. If not blank, but no job with this UUID exists, a new job is created. If not blank and a UUID exists, that job is updated with the passed information.
tgt_uuid:	UUID for a target group.

This endpoint returns the UUID for the job.

Job Inputs

A job input definition describes an argument that can be supplied at job execution time. Inputs make a job more flexible than if salt function arguments are all hard-coded. Currently only keyword job inputs are supported. Positional arguments and pillar data are sent verbatim to salt at job execution time.

When creating or updating a job, specify positional, keyword, and pillar job inputs in the arg parameter with the following structure:

arg = {
    "arg": [
        'hello',  # positional argument 0
        'world',  # positional argument 1
        # ...
    ],
    "kwarg": {
        "name1": {...},  # keyword job input `name1`
        "name2": {...},  # keyword job input `name2`
        # ...
        "pillar": {
            "pillar1": {...},  # pillar argument `pillar1`
            "pillar2": {...},  # pillar argument `pillar2`
            # ...
        }
    }

Each job input definition consists of the following fields:

{
    "display_name": "Display name goes here",               # description presented in the UI
    "input_type": "string" | "select" | "number" | "bool",  # "select" == choose one of the options in "select"
    "select": ["Option 1", "Option 2", "Option 3"],         # if input_type == "select"
    "default": "Default value",                             # should match input_type
    "help": "Helpful text",                                 # help presented in the UI
    "required": True | False,                               # True == must be specified at execution time
    "hidden": True | False,                                 # True == not presented in the UI
}

Required job inputs must be specified at job execution time, i.e., passed to cmd.route_cmd(). If a required input has a default value, it can be omitted from the route_cmd() payload. A hard-coded argument can be implemented by marking the input "required" and "hidden" and specifying the desired default value.

Here is an example invocation of save_job() and a call to route_cmd() to execute the job.

job_uuid = client.api.job.save_job(
    name="Deploy VM",
    desc=None,
    cmd="local",  # salt
    fun="state.apply",
    arg={
        "arg": ["West", 35],
        "kwarg": {
            "mods": {
                "display_name": "State",
                "input_type": "string",
                "default": "deploy_vm.sls",
                "help": None,
                "required": True,
                "hidden": True
            },
            "saltenv": {
                "display_name": "Environment",
                "input_type": "string",
                "default": "SSE",
                "help": None,
                "required": True,
                "hidden": True
            },
            "reason": {
                "display_name": "Comment / Reason",
                "input_type": "string",
                "default": "VM Deployment",
                "help": None,
                "required": True,
                "hidden": True
            },
        }
    },
    tgt_uuid="7f93b928-388b-11e6-b133-346895ecb8f3"  # all minions
)

jid = cmd.route_cmd(
    job_uuid=job_uuid,
    arg={
        "arg": []  # raas will copy positional args verbatim from the job
        "kwarg": {}  # raas will apply defaults for mods, saltenv, reason
    }

)

save_job_access(job_uuid: <class 'uuid.UUID'>, access_payload: <class 'dict'>)

Returns: <class 'uuid.UUID'>

Save access metadata for this job.

Parameters

job_uuid:	UUID referencing desired job.
access_payload:	Dictionary containing role names as keys and a list of allowed access types as values