cmd interface — VCF Salt API

cmd interface — VCF Salt API

cmd interface

The cmd interface is the primary execution engine for the VMware Salt for VCF Components API. It provides methods to route execution commands to target minions, query the real-time status of running jobs, and retrieve command execution details.

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
curl -k -X POST "https://<vcfms-hostname>/raas/rpc" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "resource": "cmd",
    "method": "get_cmd_details",
    "kwarg": {
      "jid": "20260726204734431402"
    }
  }'
get_cmd_status(jids: list[str])
Returns: <class 'list'>

Get the status of a command

jids:list of JIDs

Example

curl -k -X POST "https://<vcfms-hostname>/raas/rpc" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "resource": "cmd",
    "method": "get_cmd_status",
    "kwarg": {
      "jids": ["20260726204734431402"]
    }
  }'
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, 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 VCF 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.
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:

curl -k -X POST "https://<vcfms-hostname>/raas/rpc" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "resource": "cmd",
    "method": "get_cmds",
    "kwarg": {
      "limit": 1
    }
  }'
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

Example

curl -k -X POST "https://<vcfms-hostname>/raas/rpc" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "resource": "cmd",
    "method": "pause_job",
    "kwarg": {
      "jid": "20260726204734431402"
    }
  }'
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

Example

curl -k -X POST "https://<vcfms-hostname>/raas/rpc" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "resource": "cmd",
    "method": "resume_job",
    "kwarg": {
      "jid": "20260726204734431402"
    }
  }'
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 VCF 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 VCF 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.

General route_cmd() examples follow.

Example:
curl -k -X POST "https://<vcfms-hostname>/raas/rpc" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "resource": "cmd",
    "method": "route_cmd",
    "kwarg": {
      "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:
curl -k -X POST "https://<vcfms-hostname>/raas/rpc" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "resource": "cmd",
    "method": "route_cmd",
    "kwarg": {
      "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:
curl -k -X POST "https://<vcfms-hostname>/raas/rpc" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "resource": "cmd",
    "method": "route_cmd",
    "kwarg": {
      "cmd": "runner",
      "fun": "state.orch",
      "masters": ["*"],
      "arg": {
        "kwarg": {
          "mods": "orch.my_orch",
          "pillar": {
            "key": "value"
          }
        }
      }
    }
  }'
route_cmd_batch(commands: list[dict])
Returns: list[str]

Create multiple commands and route them to Salt in batch. This function calls route_cmd for each command in the provided list.

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

Parameters

commands:A list of command dictionaries, each containing the same parameters as route_cmd (job_uuid, cmd, fun, masters, arg, tgt, tgt_uuid, jid, disposition)

Returns

return:A list of JIDs corresponding to each command that was routed
Example:
curl -k -X POST "https://<vcfms-hostname>/raas/rpc" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "resource": "cmd",
    "method": "route_cmd_batch",
    "kwarg": {
      "commands": [
        {
          "cmd": "local",
          "fun": "test.ping",
          "tgt": {
            "master1": {
              "tgt": "*",
              "tgt_type": "glob"
            }
          }
        },
        {
          "cmd": "local",
          "fun": "cmd.run",
          "tgt": {
            "master1": {
              "tgt": "web*",
              "tgt_type": "glob"
            }
          },
          "arg": {
            "arg": ["uptime"]
          }
        }
      ]
    }
  }'
route_cmd_from_srns(srns: list[str], states: list[str], saltenv: <class 'str'> = base, derive_master: <class 'bool'>, pillar_variables: <class 'dict'>, state_params: <class 'dict'>)
Returns: dict[str, list[str]]

Create multiple commands from SRNs and route them to Salt in batch.

This function takes a list of SRNs (Salt Resource Names) and converts them into commands that can be executed via route_cmd_batch. SRNs are grouped by master, minion, and object_type to create efficient state.apply commands.

SRN format: salt:master_cluster_id:minion_id:object_type:object_id

Parameters:

srns:List of SRN strings to process (supports '*' wildcards)
states:List of Salt states to apply to each group
saltenv:Salt environment to use (default: "base")
derive_master:If True, derive master from minion when SRN contains '*' for master (default: False)
pillar_variables:Variables to be passed into pillar data (default: None)
state_params:Additional parameters to be passed to state.apply (default: None)

Returns:

return:A dict mapping JIDs to the list of original SRNs for tracking purposes
Example:
curl -k -X POST "https://<vcfms-hostname>/raas/rpc" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "resource": "cmd",
    "method": "route_cmd_from_srns",
    "kwarg": {
      "srns": [
        "salt:master_1:minion_1:vm:123",
        "salt:master_1:minion_1:vm:234",
        "salt:master_1:minion_2:vm:555"
      ],
      "states": ["foo", "bar", "baz"],
      "saltenv": "sse"
    }
  }'
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

Example

curl -k -X POST "https://<vcfms-hostname>/raas/rpc" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "resource": "cmd",
    "method": "stop_job",
    "kwarg": {
      "jid": "20260726204734431402"
    }
  }'
track_state(jid, master, state, minions, create_time)

Save tracking state for job

Example

curl -k -X POST "https://<vcfms-hostname>/raas/rpc" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <jwt_token>" \
  -d '{
    "resource": "cmd",
    "method": "track_state",
    "kwarg": {
      "jid": "20260726204734431402",
      "master": "master-01.local",
      "state": "running",
      "minions": ["minion-01.local"],
      "create_time": "2026-08-05T01:08:30Z"
    }
  }'