The Salt Event System is used to fire off events enabling third party applications or external processes to react to behavior within Salt. The event system uses a publish-subscribe pattern, otherwise know as pub/sub.
The event system is comprised of a two primary components, which make up the concept of an Event Bus:
The event sockets, which publish events
The event library, which can listen to events and send events into the salt system
Events are published onto the event bus and event bus subscribers listen for the published events.
The event bus is used for both inter-process communication as well as network transport in Salt. Inter-process communication is provided through UNIX domain sockets (UDX).
The Salt Master and each Salt Minion has their own event bus.
Salt's event system is used heavily within Salt and it is also written to integrate heavily with existing tooling and scripts. There is a variety of ways to consume it.
The quickest way to watch the event bus is by calling the state.event
runner
:
salt-run state.event pretty=True
That runner is designed to interact with the event bus from external tools and shell scripts. See the documentation for more examples.
Salt's event bus can be consumed
salt.netapi.rest_cherrypy.app.Events
as an HTTP stream from
external tools or services.
curl -SsNk https://salt-api.example.com:8000/events?token=05A3
Python scripts can access the event bus only as the same system user that Salt is running as.
The event system is accessed via the event library and can only be accessed
by the same system user that Salt is running as. To listen to events a
SaltEvent object needs to be created and then the get_event function needs to
be run. The SaltEvent object needs to know the location that the Salt Unix
sockets are kept. In the configuration this is the sock_dir
option. The
sock_dir
option defaults to "/var/run/salt/master" on most systems.
The following code will check for a single event:
import salt.config
import salt.utils.event
opts = salt.config.client_config("/etc/salt/master")
event = salt.utils.event.get_event(
"master", sock_dir=opts["sock_dir"], transport=opts["transport"], opts=opts
)
data = event.get_event()
Events will also use a "tag". Tags allow for events to be filtered by prefix. By default all events will be returned. If only authentication events are desired, then pass the tag "salt/auth".
The get_event
method has a default poll time assigned of 5 seconds. To
change this time set the "wait" option.
The following example will only listen for auth events and will wait for 10 seconds instead of the default 5.
data = event.get_event(wait=10, tag="salt/auth")
To retrieve the tag as well as the event data, pass full=True
:
evdata = event.get_event(wait=10, tag="salt/job", full=True)
tag, data = evdata["tag"], evdata["data"]
Instead of looking for a single event, the iter_events
method can be used to
make a generator which will continually yield salt events.
The iter_events method also accepts a tag but not a wait time:
for data in event.iter_events(tag="salt/auth"):
print(data)
And finally event tags can be globbed, such as they can be in the Reactor, using the fnmatch library.
import fnmatch
import salt.config
import salt.utils.event
opts = salt.config.client_config("/etc/salt/master")
sevent = salt.utils.event.get_event(
"master", sock_dir=opts["sock_dir"], transport=opts["transport"], opts=opts
)
while True:
ret = sevent.get_event(full=True)
if ret is None:
continue
if fnmatch.fnmatch(ret["tag"], "salt/job/*/ret/*"):
do_something_with_job_return(ret["data"])
It is possible to fire events on either the minion's local bus or to fire events intended for the master.
To fire a local event from the minion on the command line call the
event.fire
execution function:
salt-call event.fire '{"data": "message to be sent in the event"}' 'tag'
To fire an event to be sent up to the master from the minion call the
event.send
execution function. Remember
YAML can be used at the CLI in function arguments:
salt-call event.send 'myco/mytag/success' '{success: True, message: "It works!"}'
If a process is listening on the minion, it may be useful for a user on the master to fire an event to it. An example of listening local events on a minion on a non-Windows system:
# Job on minion
import salt.utils.event
opts = salt.config.minion_config("/etc/salt/minion")
event = salt.utils.event.MinionEvent(opts)
for evdata in event.iter_events(match_type="regex", tag="custom/.*"):
# do your processing here...
...
And an example of listening local events on a Windows system:
# Job on minion
import salt.utils.event
opts = salt.config.minion_config(salt.minion.DEFAULT_MINION_OPTS)
event = salt.utils.event.MinionEvent(opts)
for evdata in event.iter_events(match_type="regex", tag="custom/.*"):
# do your processing here...
...
salt minionname event.fire '{"data": "message for the minion"}' 'customtag/african/unladen'
Events can be very useful when writing execution modules, in order to inform various processes on the master when a certain task has taken place. This is easily done using the normal cross-calling syntax:
# /srv/salt/_modules/my_custom_module.py
def do_something():
"""
Do something and fire an event to the master when finished
CLI Example::
salt '*' my_custom_module:do_something
"""
# do something!
__salt__["event.send"](
"myco/my_custom_module/finished",
{"finished": True, "message": "The something is finished!",},
)
Firing events from custom Python code is quite simple and mirrors how it is done at the CLI:
import salt.client
caller = salt.client.Caller()
ret = caller.cmd(
"event.send", "myco/event/success", {"success": True, "message": "It works!"}
)
if not ret:
# the event could not be sent, process the error here
...