cmd interface — VMware Salt API

cmd interface — VMware Salt API

cmd 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

get_cmd_details(jid: <class 'str'>, minion_id_exact: str | None, minion_id: str | None, master_id: str | None, has_errors: bool | None, has_return: bool | None, sort_by: str | None = alter_time, reverse: bool | None, page: int | None, limit: int | None = 50)
Returns: <class 'dict'>

Query commands based on jid and retrieve more detailed data.

jid:A job ID to match against.
minion_id_exact:Filter by a minion_id that match exactly. Also full return data will be returned.
minion_id:Filter by a minion_id search.
master_id:Filter by a master_id search.
has_errors:Filter by whether there were errors, True|False.
has_return:Filter by whether return data was recieved, True|False.
sort_by:Sort by the specified field, such as 'alter_time'.
reverse:Sort ascending (False) or descending (True).
page:This specifies which page, after the first, of results to return. Often used with limit.
limit:This is how many records to return at a time. The default is 50. Often used with page.

Examples

Request
from sseapiclient import APIClient
client = APIClient('http://localhost', 'root', 'salt')
client.api.cmd.get_cmd_details(
    jid="20190726204734431402"
)
get_cmd_status(jids: list[str])
Returns: <class 'list'>

Get the status of a command

jids:list of JIDs
get_cmds(daterange: list | None, jid: str | None, master_id: str | None, state: list | None, state_invert: bool | None, job_uuid: uuid.UUID | None, job_names: list | None, sched_uuid: uuid.UUID | None, sched_names: list | None, tgt_uuid: uuid.UUID | None, tgt_names: list | None, fun: str | None, highstate: bool | None, cmd: str | None, users: list | None, include_adhoc: bool | None, include_adhoc_scheduled: str | None = all, filter_find_job: bool | None = True, filter_refresh_grains: bool | None = True, sort_by: str | None = start_time, reverse: bool | None = True, page: int | None, limit: int | None = 50)
Returns: <class 'dict'>

Query commands based on a number of properties.

For more information on commands and jobs, see the VMware Salt documentation on Broadcom's TechDocs.

Parameters

cmd:

A command name to match against.
daterange:

A comma-separated list of two date strings in ISO 8601 format.
filter_find_job:

Exclude commands referring to saltutil.find_job.
filter_refresh_grains:

Exclude commands referring to saltutil.refresh_grains.
fun:

Command (function) name that was called for this job.
highstate:

True if the job submitted was call to state.highstate
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). This parameter is deprecated. Use include_adhoc_scheduled instead. Until the removal of this parameter, it will take precedence over include_adhoc_scheduled if it is present. If it is not present or is passed a value of None, the value of include_adhoc_scheduled will be honored.
include_adhoc_scheduled:

One of all, scheduled, or adhoc. Filters jobs based on if they are scheduled, unscheduled (aka "on the fly" or "ad-hoc", or show all jobs regardless of what started them.)
limit:

This is how many records to return at a time. The default is 50. Often used with page.
jid:

A job ID to match against.
job_names:

A list of job names to match against.
job_uuid:

Every job gets a jid and a UUID. This is the uuid for the job.
master_id:

Master ID
page:

This specifies which page, after the first, of results to return. Often used with limit.
reverse:

Sort ascending (False) or descending (True).
sched_names:

A list of schedule names to match against.
sched_uuid:

A schedule UUID to match against.
sort_by:

Sort by the specified field, such as 'start_time'.
state_invert:

Return commands that do not have the specified state.
state:

Find commands in one of these states, 'new', 'retrieved', 'skipped', 'pausing', 'paused', 'resuming', 'resumed', 'completed_missing_returns', 'completed_failures', 'completed_all_successful', 'stopping', 'stopped', or 'disabled'. Note that state may contain completed when no minions have returned.
tgt_names:

A list of target names to match against.
tgt_uuid:

Commands can be targeted directly or via a saved target group. This is the UUID of the target group used to submit the command.
users:

A list of users to match against.

Example:

client.api.cmd.get_cmds()

RPCResponse(riq=5,
            ret={'count': 1,
                 'results': [
                     {'cmd': 'local',
                      'duration': None,
                      'expected': 2,
                      'fun': 'disk.usage',
                      'is_highstate': False,
                      'jid': '20190416202619938862',
                      'job_desc': None,
                      'job_name': None,
                      'job_source': 'raas',
                      'job_uuid': None,
                      'masters_done': ['master1'],
                      'masters_to': ['master1'],
                      'origination': 'Ad-Hoc',
                      'returned': 1,
                      'returned_failed': 0,
                      'returned_good': 1,
                      'sched_name': None,
                      'sched_uuid': None,
                      'start_time': '2019-04-16T20:26:19.93886Z',
                      'state': 'retrieved',
                      'tgt_desc': None,
                      'tgt_name': None,
                      'tgt_uuid': None,
                      'user': 'root',
                      'user_uuid': '80c67364-cb31-4f4b-972a-e7ea3f752bb8'}]},
            error=None,
            warnings=[])
get_highstate_minion_details(minion_id: <class 'str'>, state: str | None, sls: str | None, saltenv: str | None, jid: str | None, result: bool | None, changes: bool | None, comment: str | None, test: bool | None, filter_summary: bool | None, sort_by: str | None, reverse: bool | None, page: int | None, limit: int | None = 50)
Returns: <class 'dict'>

Get the most recent highstate details for a particular minion

Parameters

param minion_id:Get highstate details for this minion (required, exact match)
param state:Filter results by matching states (substring match)
param sls:Filter results by matching SLS files (substring match)
param saltenv:Filter results by matching saltenv (substring match)
param jid:Filter results by jid (substring match)
param result:Report only successful (True) or failed (False) states
param changes:Report only states that resulted in changes (True) or no changes (False)
param comment:Report only states with matching comments (substring match)
param test:Report only results from dry runs (True), default is to exclude
param filter_summary:Pass True to filter summary data by query args (default False)
param sort_by:One of: state, sls, saltenv, jid, run_num, result, changes, duration, comment
param reverse:Pass True to sort descending
param page:Specify which page of results to return, default is 0 (first page)
param limit:How many records to return per call, default is 50

Example:

client.api.cmd.get_highstate_minion_details(minion_id='dev01', limit=3)

RPCResponse(riq=7,
    ret={
        'summary': {
            'total_states': 9,
            'states_failed': 0,
            'states_succeeded': 9,
            'states_changed': 0,
            'states_unchanged': 9,
            'total_duration': 63264.21
        },
        'count': 9,
        'results': [
            {
                'state': 'install_apache',
                'sls': 'web',
                'saltenv': 'pre',
                'jid': '20220828231050673988',
                'run_num': 0,
                'result': True,
                'duration': 11043.26,
                'num_changes': 0,
                'changes': {},
                'comment': 'No changes made.'
            },
            {
                'state': 'ensure_service_running',
                'sls': 'web',
                'saltenv': 'pre',
                'jid': '20220828231050673988',
                'run_num': 1,
                'result': True,
                'duration': 10009.25,
                'num_changes': 0,
                'changes': {},
                'comment': 'No changes made.'
            },
            {
                'state': 'default_html_page',
                'sls': 'web',
                'saltenv': 'pre',
                'jid': '20220828231050673988',
                'run_num': 2,
                'result': True,
                'duration': 9023.58,
                'num_changes': 0,
                'changes': {},
                'comment': 'No changes made.'
            }
        ]
    },
    error=None,
    warnings=[])
get_highstate_minions(tgt_uuid: uuid.UUID | None, master_id: str | None, minion_id: str | None, saltenv: str | None, jid: str | None, result: bool | None, changes: bool | None, test: bool | None, age_limit: int | None, filter_summary: bool | None, sort_by: str | None, reverse: bool | None, page: int | None, limit: int | None = 50)
Returns: <class 'dict'>

Get minion information from the most recent highstate runs

Parameters

param tgt_uuid:Report minions in this target group
param master_id:Report minions on this master (substring match)
param minion_id:Report minions with matching ids (substring match)
param saltenv:Report minions with results from this saltenv (substring match)
param jid:Report minions that reported results for this jid (substring match)
param result:Report only successful (True) or failed (False) minions
param changes:Match only minions reporting changes (True) or no changes (False)
param test:Report only results from dry runs (True), default is to exclude
param age_limit:Ignore data older than this (minutes), default is no age limit
param filter_summary:Pass True to filter summary data by query args (default False)
param sort_by:One of: minion_id, total_states, states_failed, states_succeeded, states_changed, states_unchanged, total_duration
param reverse:Pass True to sort descending
param page:Specify which page of results to return, default is 0 (first page)
param limit:How many records to return per call, default is 50

Example:

client.api.cmd.get_highstate_minions(limit=1)

RPCResponse(riq=4,
    ret={
        'summary': {
            'total_minions': 97,
            'avg_states_per_minion': 9.71,
            'minions_failed': 19,
            'minions_succeeded': 78,
            'minions_changed': 3,
            'minions_unchanged': 94,
            'avg_duration': 64888.62
        },
        'count': 97,
        'results': [
            {
                'master_uuid': '1d19cf58-cb2f-4190-8f1d-32e462bbd91c',
                'master_id': 'master_dev',
                'minion_id': 'dev01',
                'jids': ['20220828231050673988'],
                'saltenvs': ['pre'],
                'total_states': 9,
                'states_failed': 0,
                'states_succeeded': 9,
                'states_changed': 0,
                'states_unchanged': 9,
                'total_duration': 63264.21
            }
        ]
    },
    error=None,
    warnings=[]
)
get_highstate_state_details(state: <class 'str'>, master_id: str | None, minion_id: str | None, saltenv: str | None, jid: str | None, result: bool | None, changes: bool | None, comment: str | None, test: bool | None, filter_summary: bool | None, sort_by: str | None, reverse: bool | None, page: int | None, limit: int | None = 50)
Returns: <class 'dict'>

Get the most recent highstate details for a particular state

Parameters

param state:Get highstate details for this state (required, exact match)
param master_id:Filter results by master id (substring match)
param minion_id:Filter results by minion id (substring match)
param result:Report only successful (True) or failed (False) minions
param changes:Report only minions that made changes (True) or no changes (False)
param comment:Report only minions with matching comments (substring match)
param test:Report only results from dry runs (True), default is to exclude
param filter_summary:Pass True to filter summary data by query args (default False)
param sort_by:One of: minion_id, saltenv, jid, result, changes, duration, comment
param reverse:Pass True to sort descending
param page:Specify which page of results to return, default is 0 (first page)
param limit:How many records to return per call, default is 50

Example:

client.api.cmd.get_highstate_state_details('ensure_service_running', limit=3)

RPCResponse(riq=13,
    ret={
        'summary': {
            'total_minions': 97,
            'minions_failed': 0,
            'minions_succeeded': 97,
            'minions_changed': 3,
            'minions_unchanged': 94,
            'avg_duration': 10047.06
        },
        'count': 97,
        'results': [
            {
                'master_id': 'master_dev',
                'minion_id': 'dev01',
                'jid': '20220828231050673988',
                'saltenv': 'pre',
                'result': True,
                'duration': 10009.25,
                'num_changes': 0,
                'changes': {},
                'comment': 'No changes made.'
            },
            {
                'master_id': 'master_dev',
                'minion_id': 'dev02',
                'jid': '20220828231050673988',
                'saltenv': 'pre',
                'result': True,
                'duration': 10007.84,
                'num_changes': 0,
                'changes': {},
                'comment': 'No changes made.'
            },
            {
                'master_id': 'master_dev',
                'minion_id': 'dev03',
                'jid': '20220828231050673988',
                'saltenv': 'pre',
                'result': True,
                'duration': 10084.85,
                'num_changes': 0,
                'changes': {},
                'comment': 'No changes made.'
            }
        ]
    },
    error=None,
    warnings=[])
get_highstate_states(state: str | None, sls: str | None, saltenv: str | None, jid: str | None, result: bool | None, changes: bool | None, test: bool | None, age_limit: int | None, filter_summary: bool | None, sort_by: str | None, reverse: bool | None, page: int | None, limit: int | None = 50)
Returns: <class 'dict'>

Get state information from the most recent highstate runs

Parameters

param state:Report states with matching names (substring match)
param sls:Report states from matching sls files (substring match)
param saltenv:Report results run against matching saltenvs (substring match)
param jid:Report results from jid (substring match)
param result:Report only successful (True) or failed (False) states
param changes:Match only states reporting changes (True) or no changes (False)
param test:Report only results from dry runs (True)
param age_limit:Ignore data older than this (minutes), default is no age limit
param filter_summary:Pass True to filter summary data by query args (default False)
param sort_by:One of: state, sls, total_minions, minions_failed, minions_succeeded, minions_changed, minions_unchanged, avg_duration
param reverse:Pass True to sort descending
param page:Specify which page of results to return, default is 0 (first page)
param limit:How many records to return per call, default is 50

Example

client.api.cmd.get_highstate_states(limit=3)

RPCResponse(riq=10,
    ret={
        'summary': {
            'total_states': 10,
            'avg_minions_per_state': 97.0,
            'states_failed': 1,
            'states_succeeded': 9,
            'states_changed': 7,
            'states_unchanged': 3,
            'avg_duration': 6547.77
        },
        'count': 10,
        'results': [
            {
                'state': 'clean_up',
                'sls': 'app',
                'total_minions': 70,
                'minions_failed': 0,
                'minions_succeeded': 70,
                'minions_changed': 0,
                'minions_unchanged': 70,
                'avg_duration': 2040.62,
                'jids': ['20220829081050673988'],
                'saltenvs': ['prod']
            },
            {
                'state': 'default_html_page',
                'sls': 'web',
                'total_minions': 100,
                'minions_failed': 0,
                'minions_succeeded': 100,
                'minions_changed': 3,
                'minions_unchanged': 97,
                'avg_duration': 9048.9,
                'jids': ['20220828231050673988', '20220829003551779461'],
                ],
                'saltenvs': ['pre', 'prod']
            },
            {
                'state': 'ensure_mysql_running',
                'sls': 'db',
                'total_minions': 100,
                'minions_failed': 20,
                'minions_succeeded': 80,
                'minions_changed': 3,
                'minions_unchanged': 97,
                'avg_duration': 5047.29,
                'jids': ['20220828231050673988', '20220829003551779461'],
                'saltenvs': ['pre', 'prod']
            }
        ]
    },
    error=None,
    warnings=[])
get_highstate_stats(begin_date: datetime.date | None, end_date: datetime.date | None, reverse: bool | None)
Returns: <class 'dict'>

Get daily historical highstate summary statistics.

Parameters

param begin_date:Get statistics beginning at this date (default: earliest available).
param end_date:Get statistics ending at this date (default: today).
param reverse:Pass True to sort from most recent to least recent

Example:

client.api.cmd.get_highstate_stats(begin_date='2022-08-31', reverse=True)

RPCResponse(riq=16,
    ret={
        'count': 3,
        'results': [
            {
                'date': '2022-09-02',
                'total_minions': 107,
                'minions_changed': 0,
                'minions_unchanged': 107,
                'minions_succeeded': 107,
                'minions_failed': 0,
                'minion_avg_duration': 32100.0,
                'total_states': 10,
                'states_changed': 2,
                'states_unchanged': 8,
                'states_succeeded': 8,
                'states_failed': 2
            },
            {
                'date': '2022-09-01',
                'total_minions': 107,
                'minions_changed': 0,
                'minions_unchanged': 107,
                'minions_succeeded': 107,
                'minions_failed': 0,
                'minion_avg_duration': 32097.0,
                'total_states': 10,
                'states_changed': 0,
                'states_unchanged': 10,
                'states_succeeded': 10,
                'states_failed': 0
            },
            {
                'date': '2022-08-31',
                'total_minions': 107,
                'minions_changed': 1,
                'minions_unchanged': 106,
                'minions_succeeded': 107,
                'minions_failed': 0,
                'minion_avg_duration': 32106.0,
                'total_states': 10,
                'states_changed': 0,
                'states_unchanged': 10,
                'states_succeeded': 10,
                'states_failed': 0
            }
        ]
    },
    error=None,
    warnings=[]
)
pause_job(job_uuid: uuid.UUID | None, jid: str | None)
Returns: <class 'str'>

Pass a pause command through to the masters. Note that the pause command is itself a command, so this method returns a jid corresponding to the state.pause call.

param job_uuid:UUID of the job to attempt to pause
param jid:Jid of the job to attempt to pause
return:a Jid corresponding to the pause command
resume_job(job_uuid: uuid.UUID | None, jid: str | None)
Returns: <class 'str'>

Pass a resume command through to the masters

param job_uuid:UUID of the job to attempt to resume
param jid:Jid of the job to attempt to resume
return:a Jid corresponding to the resume command
route_cmd(job_uuid: uuid.UUID | None, cmd: str | None, fun: str | None, masters: list[str] | None, arg: dict | None, tgt: dict | None, tgt_uuid: uuid.UUID | None, jid: str | None, disposition: list[str] | None)
Returns: <class 'str'>

Create a command and route it to Salt. For more information on commands and jobs, see the VMware Salt documentation on Broadcom's TechDocs.

Parameters

job_uuid:UUID for this job, can be None in which case RaaS will generate a new UUID.
cmd:One of local (for targeting minions), runner (master-level command), or wheel (master wheel calls)
fun:Dotted-notation function to run (e.g. test.ping or network.ipaddrs)
masters:A list of master names that should receive this command. Applicable only for runner and wheel commands. For local cmds all targeting is specified in tgt.
arg:A dictionary containing the keys arg and/or kwarg representing arguments to pass to the fun being called.
tgt:A dictionary containing targeting information. A target can contain a master name of * to indicate all VMware Salt-connected masters. If * is present, it must be the only master listed in tgt.
tgt_uuid:The UUID of an existing target group that should receive this command.
jid:Optional jid for the command. If not supplied, a jid will be generated.
disposition:Command disposition. See the discussion below.

Either tgt or tgt_uuid should be used, but not both.

tgt has the following form:

{
  name_of_master: {
    "tgt": target_string,
    "tgt_type": target_type
  },
  another_master: {
    "tgt": target_string,
    "tgt_type": target_type
  },
  ...
}

The disposition parameter determines how runner and wheel commands are routed. The default behavior is to route these commands to each entity represented in the command's masters list. If any such entity is a cluster-id instead of a salt-master id, the command will be routed to one master in that cluster. This behavior corresponds to the disposition value ["all-masters", "any-in-cluster"].

In other words, the string "all-masters" causes the command to be routed to all the entities represented in the command's masters list, and the string "any-in-cluster" means that when the command is routed to a cluster, one arbitrary salt-master from that cluster will execute the command.

To change the routing of a command, two other strings can be included in the disposition list.

  • Passing "any-master" causes the command to be routed to a single arbitrary entity from the command masters list.
  • Passing "all-in-cluster" causes the command to be routed to all salt-masters within each cluster receiving the command.

Here are some route_cmd() examples with descriptions of how the commands are routed:

  • route_cmd(..., masters=["master1", "master2"]) routes the command to both salt-masters
  • route_cmd(..., masters=["m1", "m2"], disposition=["any-master"]) routes the command to salt-master m1 or salt-master m2
  • route_cmd(..., masters=["master_dev", "cluster_prod"]) routes the command to the master_dev salt-master and to one arbitrary salt-master within the cluster_prod cluster
  • route_cmd(..., masters=["cluster1"], disposition=["all-in-cluster"]) routes the command to all salt-masters within the cluster1 cluster
  • route_cmd(..., masters=["c1", "c2"], disposition=["any-master", "all-in-cluster"]) routes the command to cluster c1 or cluster c2, and within the chosen cluster, all salt-masters will receive the command.
  • route_cmd(..., masters=["m1", "c1"], disposition=["any-master", "all-in-cluster"]) routes the command either to salt-master m1 or to cluster c1. If the command is routed to cluster c1, all salt-masters within that cluster will receive it.

General route_cmd() examples follow.

Example:
client.api.cmd.route_cmd(
    cmd="local",
    fun="cmd.run",
    tgt={"master3_master": {"tgt": "master3", "tgt_type": "glob"}},
    arg={"arg": ["ls /etc"]},
)

client.api.cmd.route_cmd(
    job_uuid="5c5cc410-4f9f-11e6-88bc-080027a7289c",
    tgt={"master3_master": {"tgt": "*", "tgt_type": "glob"}},
)
Example with an argument:
client.api.cmd.route_cmd(
    cmd="local",
    fun="cmd.run",
    tgt={"master3_master": {"tgt": "master3", "tgt_type": "glob"}},
    arg={"arg": ["ls /etc"]},
)
Example of a state execution with pillar data:
client.api.cmd.route_cmd(
    cmd="local",
    fun="state.apply",
    tgt={"master3_master": {"tgt": "master3", "tgt_type": "glob"}},
    arg={"arg": ["my_state"], "kwarg": {"pillar": {"key": "value"}}},
)
Example of an orchestration with pillar data:
client.api.cmd.route_cmd(
    cmd="runner",
    masters=["*"],
    fun="state.orch",
    arg={"kwarg": {"mods": "orch.my_orch", "pillar": {"key": "value"}}},
)
Example with an existing job_uuid
client.api.cmd.route_cmd(
    job_uuid="5c5cc410-4f9f-11e6-88bc-080027a7289c",
    tgt={"master3_master": {"tgt": "*", "tgt_type": "glob"}},
)
stop_job(job_uuid: uuid.UUID | None, jid: str | None)
Returns: <class 'str'>

Pass a 'soft_kill' command through to the masters.

param job_uuid:UUID of the job to attempt to kill
param jid:Jid of the job to attempt to kill
return:a Jid corresponding to the kill command
track_state(jid, master, state, minions, create_time)

Save tracking state for job