schedule interface — VMware Salt API

schedule interface — VMware Salt API

schedule 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

futures(sched_names: list[str] | None, job_names: list[str] | None, tgt_names: list[str] | None, uuid: uuid.UUID | None, fun: str | None, state: list[str] | None, state_invert: bool | None, sort_by: str | None = start_time, daterange: list | None, page: int | None, limit: int | None = 100, reverse: bool | None)
Returns: <class 'dict'>

Get a list of future times when the scheduled jobs will execute. If jobs is passed in then only the futures for those jobs will be calculated. By default the job times will be queried out for 8 weeks

Parameters

list sched_names:Matching names of the schedule entries to return
list job_names:A list of job names to query
list tgt_names:Filter by target names in the schedule.
UUID uuid:Filter by schedule uuid.
list state:A list of states to match
list state_invert:A list of states to exclude
str fun:The name of the function that was run
str sort_by:Field to sort by. One of 'fun', 'tgt_name', 'job_name', 'sched_name', 'start_time', 'state'.
list daterange:A list of two date strings in ISO 8601 format in UTC. If the provided dates are in a different offset, they will be converted to UTC prior to the date range constraining.
int page:Which page of the records to return (offset = page * limit)
int limit:The number of job instances to return, defaults to 100
bool reverse:Sort ascending (False) or descending (True).

The parameter daterange, which is a date string in ISO8601 format has a sibling parameter, daterange_fmt, which is a string that can represent an alternate date and time format used to parse the daterange values.

get(names: list | None, show_past: bool | None, query: str | None, cmd: str | None, fun: str | None, masters: list[str] | None, tgt: str | None, arg: bool | None, kwarg: bool | None, state: list[str] | None, enabled: bool | None, uuid: uuid.UUID | None, job_names: list | None, tgt_names: list | None, sort_by: str | None, reverse: bool | None, limit: int | None = 50, page: int | None, expired: bool | None)
Returns: <class 'dict'>

Return the full schedule json structure.

For more information on schedules, see the VMware Salt documentation on Broadcom's TechDocs.

param list names:Matching names of the schedule entries to return
param bool show_past:Include entries that were scheduled to run in the past.
param str query:The text to search for in args or kwargs
param str cmd:One of local, runner, ssh, wheel
param str fun:The name of the function that was run
param list masters:A list of masters that the job was assigned to
param str tgt:A target string to search for
param bool arg:Whether to search inside *args
param bool kwarg:Whether to search inside **kwargs
param list state:A list of states to match
param bool enabled:is the scheduled item enabled to run or not
param UUID uuid:Schedule UUID to match
param list job_names:A list of job names to match
param list tgt_names:A list of target group names to match
param str sort_by:Field to sort by
param bool reverse:Pass True to sort in descending order
param int limit:How many records to return at a time
param int page:Which page of the records to return (offset = page * limit)

NOTE: passing ['*'] as the value of masters will match the literal value * in the list of masters. get() is setup this way so it will be possible to look up schedules that are targeted at all masters. If * was treated as the wildcard, it would always match any job targeted

at any master
get_inflight(uuid: uuid.UUID | None, sched_names: list | None, job_names: list | None, tgt_names: list | None, fun: str | None, cmd: str | None, paused: bool | None, include_adhoc: bool | None, filter_find_job: bool | None = True, sort_by: str | None, reverse: bool | None, limit: int | None = 50, page: int | None)
Returns: <class 'dict'>

Get a list of jobs that are in progress.

Parameters

cmd:A command name to match against.
filter_find_job:Exclude commands referring to saltutil.find_job.
fun:Command (function) name that was called for this job.
include_adhoc:When this is true, you can search jobs that are running (in-flight), but were not scheduled via the scheduler API (ad-hoc).
job_names:A list of job names to match against.
page:This specifies which page, after the first, of results to return.
limit:Limit search to this number of jobs.
reverse:Sort ascending (False) or descending (True).
sched_names:A list of schedule names to match against.
sort_by:Sort by the specified field, such as 'start_time'.
tgt_names:A list of target names to match against.
paused:Filter on only paused jobs.
remove(uuid: <class 'uuid.UUID'>)
Returns: <class 'bool'>

Remove a schedule by uuid.

param uuid:The uuid of the schedule to be removed.
save(name: <class 'str'>, schedule: <class 'dict'>, masters: list | None, cmd: str | None, arg: dict | None, tgt: dict | None, tgt_uuid: uuid.UUID | None, job_uuid: uuid.UUID | None, uuid: uuid.UUID | None, fun: str | None, function: <class 'str'> = job.run, enabled: bool | None = True)
Returns: <class 'uuid.UUID'>

Add/update a component in the schedule.

For more information on schedules, see the VMware Salt documentation on Broadcom's TechDocs.

param str name:The name of the schedule item
param dict schedule:A dictionary with schedule details.
param list masters:List of masters on which to execute runner and wheel commands.
param str cmd:One of local, runner, ssh, wheel
param dict arg:Argument dictionary containing kwargs and args for fun below
param dict tgt:The minion target dictionary (use this or tgt_uuid, not both)
param str tgt_uuid:a UUID for an already saved target (use this or tgt, not both)
param str job_uuid:a UUID for an already saved job (use this or fun+arg, not both)
param str fun:The function to run (use this or job_uuid, not both)
param bool enabled:Set the schedule job enabled or disabled

arg should have this format:

arg: { 'arg': [<arg1>, <arg2>, ..., <argn>],
       'kwarg': { '<key1>': <val1>,
                  '<key2>': <val2>,
                  ...
                  '<keyn>': <valn> }
    }

schedule should have this format:

schedule: { '<descriptor1>': <value1>,
            '<descriptor2>': <value1>,
            ...
            '<descriptorn>': <valuen> }

Descriptor above can be a number of things like seconds, once, when, cron, etc. See the VMware Salt documentation for a complete list.

save_skip(uuids: list[str] | None, skip: bool | None)
Returns: <class 'dict'>

Update a list of futures (by UUID) skip flag

Parameters

list uuids:A list of future uuids to set skip flag for.
boolean skip:True or False to skip future
search_history(query: str | None, cmd: str | None, name: bool | None, fun: str | None, masters: str | None, tgt: str | None, arg: bool | None, kwarg: bool | None, daterange: list | None, limit: <class 'int'> = 50, page: <class 'int'>)
Returns: <class 'dict'>

Query the logs of past scheduler runs.

Parameters

str query:The text to search for
bool name:Whether to search schedule names
str cmd:One of local, runner, ssh, wheel
str fun:The name of the function that was run
list masters:The master(s) that the job was assigned to
str tgt:A target string to search for
bool arg:Whether to search inside *args
bool kwarg:Whether to search inside **kwargs
list daterange:A list of two date strings in ISO 8601 format
int limit:How many records to return at a time
int page:Which page of the records to return (offset = page * limit)

The parameter daterange, which is a date string in ISO8601 format has a sibling parameter, daterange_fmt, which is a string that can represent an alternate date and time format used to parse the daterange values.

update(name: str | None, schedule: dict | None, masters: list | None, cmd: str | None, arg: dict | None, tgt: dict | None, tgt_uuid: uuid.UUID | None, job_uuid: uuid.UUID | None, uuid: uuid.UUID | None, fun: str | None, function: <class 'str'> = job.run, enabled: bool | None, delete_fields: list[str] | None)
Returns: <class 'uuid.UUID'>

Update a schedule.

For more information on schedules, see the VMware Salt documentation on Broadcom's TechDocs.

param str name:The name of the schedule item
param dict schedule:A dictionary with schedule details.
param list masters:List of masters on which to execute runner and wheel commands.
param str cmd:One of local, runner, ssh, wheel
param dict arg:Argument dictionary containing kwargs and args for fun below
param dict tgt:The minion target dictionary (use this or tgt_uuid, not both)
param str tgt_uuid:a UUID for an already saved target (use this or tgt, not both)
param str job_uuid:a UUID for an already saved job (use this or fun+arg, not both)
param str fun:The function to run (use this or job_uuid, not both)
param bool enabled:Set the schedule job enabled or disabled

arg should have this format:

arg: { 'arg': [<arg1>, <arg2>, ..., <argn>],
       'kwarg': { '<key1>': <val1>,
                  '<key2>': <val2>,
                  ...
                  '<keyn>': <valn> }
    }

schedule should have this format:

schedule: { '<descriptor1>': <value1>,
            '<descriptor2>': <value1>,
            ...
            '<descriptorn>': <valuen> }

Descriptor above can be a number of things like seconds, once, when, cron, etc. See the VMware Salt documentation for a complete list.