Salt runners are convenience applications executed with the salt-run command.
Salt runners work similarly to Salt execution modules however they execute on the Salt master itself instead of remote Salt minions.
A Salt runner can be a simple client call or a complex application.
See also
A Salt runner is written in a similar manner to a Salt execution module. Both are Python modules which contain functions and each public function is a runner which may be executed via the salt-run command.
For example, if a Python module named test.py
is created in the runners
directory and contains a function called foo
, the test
runner could be
invoked with the following command:
# salt-run test.foo
Runners have several options for controlling output.
Any print
statement in a runner is automatically also
fired onto the master event bus where. For example:
def a_runner(outputter=None, display_progress=False):
print("Hello world")
...
The above would result in an event fired as follows:
Event fired at Tue Jan 13 15:26:45 2015
*************************
Tag: salt/run/20150113152644070246/print
Data:
{'_stamp': '2015-01-13T15:26:45.078707',
'data': 'hello',
'outputter': 'pprint'}
A runner may also send a progress event, which is displayed to the user during
runner execution and is also passed across the event bus if the display_progress
argument to a runner is set to True.
A custom runner may send its own progress event by using the
__jid_event_.fire_event()
method as shown here:
if display_progress:
__jid_event__.fire_event({"message": "A progress message"}, "progress")
The above would produce output on the console reading: A progress message
as well as an event on the event similar to:
Event fired at Tue Jan 13 15:21:20 2015
*************************
Tag: salt/run/20150113152118341421/progress
Data:
{'_stamp': '2015-01-13T15:21:20.390053',
'message': "A progress message"}
A runner could use the same approach to send an event with a customized tag
onto the event bus by replacing the second argument (progress
) with
whatever tag is desired. However, this will not be shown on the command-line
and will only be fired onto the event bus.
A runner may be fired asynchronously which will immediately return control. In
this case, no output will be display to the user if salt-run
is being used
from the command-line. If used programmatically, no results will be returned.
If results are desired, they must be gathered either by firing events on the
bus from the runner and then watching for them or by some other means.
Note
When running a runner in asynchronous mode, the --progress
flag will
not deliver output to the salt-run CLI. However, progress events will
still be fired on the bus.
In synchronous mode, which is the default, control will not be returned until the runner has finished executing.
To add custom runners, put them in a directory and add it to
runner_dirs
in the master configuration file.
Examples of runners can be found in the Salt distribution:
A simple runner that returns a well-formatted list of the minions that are responding to Salt calls could look like this:
# Import salt modules
import salt.client
def up():
"""
Print a list of all of the minions that are up
"""
client = salt.client.LocalClient(__opts__["conf_file"])
minions = client.cmd("*", "test.version", timeout=1)
for minion in sorted(minions):
print(minion)