Salt is used to execute functions across a wide variety of locations in a wide variety of ways. It does this by mapping the function name and function parameters within a data structure (JSON-serializable). Unfortunately, there is a variety of formats in different parts of Salt for doing so.

salt-lowdata-formats.rst

Various formats of mapping data to function calls in Salt

Note

Legend

mod

Module name

fun

Function name (in module)

arg

Positional argument

arg0

First positional argument

argname:

Introspected variable name for positional argument

kwarg

Keyword argument

CLI

salt '*' mod.fun arg arg kwarg=val kwarg=val
salt '*' mod.fun1,mod.fun2 arg,arg arg,arg kwarg=val,kwarg=val  # accurate?

salt '*' state.sls apache
salt '*' state.sls mods=apache
salt '*' state.sls mods=apache test=true
salt '*' status.uptime,disk.usage ,hda1     # compound command

Python

LocalClient

In LocalClient the singular arg and kwarg are sent to the minion for when the minion executes the function. The plural args and kwargs are used by LocalClient itself on the master.

import salt.client
c = salt.client.LocalClient()

c = LocalClient(__opts__)
c.cmd('*', 'mod.fun', arg)
c.cmd('*', 'mod.fun', [arg])
c.cmd('*', 'mod.fun', arg=[arg])
c.cmd('*', 'mod.fun', kwarg={key: val})

c.cmd('*', 'status.uptime')
c.cmd('*', 'status.uptime', 'human_readable=True')
c.cmd('*', 'status.uptime', ['human_readable=True'])
c.cmd('*', 'status.uptime', arg=['human_readable=True'])
c.cmd('*', 'status.uptime', kwarg={'human_readable': True})
c.cmd('*', 'status.uptime', kwarg={'human_readable': True},
    username='saltdev', password='saltdev', eauth='auto')

RunnerClient / WheelClient

RunnerClient and WheelClient historically had no format_call support for positional args. Support was added in #25243 but in the plurarl form not singular, differing from LocalClient.

The function signatures for cmd, cmd_sync, cmd_async, et al differ wildly between the two. See the Python API docs for examples.

https://docs.saltstack.com/en/latest/ref/clients/index.html#runnerclient

States

arg0:
  mod:
    - fun
    - kwarg: val

arg0:
  mod.fun:
    - kwarg: val

id:
  mod.fun:
    - name: arg0
    - kwarg: val

Scheduler

schedule:
  somename:
    function: mod.fun
    args:
      - arg
    minutes: 30

Mine

mine_functions:
  mod.fun: []   # no args

mine_functions:
  mod.fun:
    - arg
    - arg

mine_functions:
  mod.fun:
    - kwarg: val

mine_functions:
  alias:
    mine_function: mod.fun
    kwarg: val

Overstate

somename:
  function:
    mod.fun:
      - arg

Orchestrate

Same as regular states (yay!).

Reactor

# runner modules; maps directly to RunnerClient
somename:
  runner.mod.fun:
    - kwarg: val

# execution modules; maps directly to LocalClient
somename:
  cmd.mod.fun:
    - kwarg: val
    - arg:
      - arg

do_state_run:
  cmd.state.sls:
    - tgt: '*'
    - arg:
      - apache

do_state_run:
  cmd.state.sls:
    - tgt: '*'
    - kwarg:
        mods: apache

salt-api

Urlencoded format:

client=clientname&fun=mod.fun&arg=arg
client=clientname&fun=mod.fun&arg=arg&arg=arg
client=clientname&fun=mod.fun&arg=arg&arg=arg&arg=kwarg=val

client=local&fun=state.sls&arg=apache
client=local&fun=state.sls&arg=apache&arg=test=true

JSON format (maps directly to LocalClient, RunnerClient):

[{
    "client": "local",
    "fun": "mod.fun",
    "arg": "val",
    "arg": "kwarg=val"
}]

[{
    "client": "local",
    "fun": "state.sls",
    "arg": ["apache", "test=true"]
}]

[{
    "client": "local",
    "fun": "state.sls",
    "kwarg": {"mods": "apache", "test": true}
}]

Positional args not possible; see RunnerClient above for details.

[{
    "client": "runner",
    "fun": "mod.fun",
    "kwarg": "val"
}]

[{
    "client": "runner",
    "fun": "jobs.lookup_jid",
    "jid": "12345"
}]