mirror of
https://github.com/valitydev/salt.git
synced 2024-11-07 08:58:59 +00:00
137 lines
4.3 KiB
ReStructuredText
137 lines
4.3 KiB
ReStructuredText
=================
|
|
Salt Event System
|
|
=================
|
|
|
|
Salt 0.9.10 introduced the Salt Event System. This system is used to fire
|
|
off events enabling third party applications or external processes to react
|
|
to behavior within Salt.
|
|
|
|
The event system is comprised of a few components, the event sockets which
|
|
publish events, and the event library which can listen to events and send
|
|
events into the salt system.
|
|
|
|
Listening for Events
|
|
====================
|
|
|
|
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:
|
|
|
|
.. code-block:: python
|
|
|
|
import salt.utils.event
|
|
|
|
event = salt.utils.event.MasterEvent('/var/run/salt/master')
|
|
|
|
data = event.get_event()
|
|
|
|
Events will also use a "tag". A "tag" allows for events to be filtered. By
|
|
default all events will be returned, but if only authentication events are
|
|
desired, then pass the tag "auth". Also, the get_event method has a default
|
|
poll time assigned of 5 seconds, to change this time set the "wait" option.
|
|
This example will only listen for auth events and will wait for 10 seconds
|
|
instead of the default 5.
|
|
|
|
.. code-block:: python
|
|
|
|
import salt.utils.event
|
|
|
|
event = salt.utils.event.MasterEvent('/var/run/salt/master')
|
|
|
|
data = event.get_event(wait=10, tag='auth')
|
|
|
|
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:
|
|
|
|
.. code-block:: python
|
|
|
|
import salt.utils.event
|
|
|
|
event = salt.utils.event.MasterEvent('/var/run/salt/master')
|
|
|
|
for data in event.iter_events(tag='auth'):
|
|
print(data)
|
|
|
|
|
|
Firing Events
|
|
=============
|
|
|
|
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:
|
|
|
|
.. code-block:: bash
|
|
|
|
salt-call event.fire 'message to be sent in the event' 'tag'
|
|
|
|
To fire an event to be sent to the master, from the minion:
|
|
|
|
.. code-block:: bash
|
|
|
|
salt-call event.fire_master 'message for the master' 'tag'
|
|
|
|
If a process is listening on the minion, it may be useful for a user on the
|
|
master to fire an event to it:
|
|
|
|
.. code-block:: bash
|
|
|
|
salt minionname event.fire 'message for the minion' 'tag'
|
|
|
|
|
|
Firing Events From Code
|
|
=======================
|
|
|
|
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. In Salt
|
|
versions previous to 0.17.0, the basic code looks like:
|
|
|
|
.. code-block:: python
|
|
|
|
# Import the proper library
|
|
import salt.utils.event
|
|
# Fire deploy action
|
|
sock_dir = '/var/run/salt/minion'
|
|
event = salt.utils.event.SaltEvent('master', sock_dir)
|
|
event.fire_event('Message to be sent', 'tag')
|
|
|
|
In Salt version 0.17.0, the ability to send a payload with a more complex data
|
|
structure than a string was added. When using this interface, a Python
|
|
dictionary should be sent instead.
|
|
|
|
.. code-block:: python
|
|
|
|
# Import the proper library
|
|
import salt.utils.event
|
|
# Fire deploy action
|
|
sock_dir = '/var/run/salt/minion'
|
|
payload = {'sample-msg': 'this is a test',
|
|
'example': 'this is the same test'}
|
|
event = salt.utils.event.SaltEvent('master', sock_dir)
|
|
event.fire_event(payload, 'tag')
|
|
|
|
It should be noted that this code can be used in 3rd party applications as well.
|
|
So long as the salt-minion process is running, the minion socket can be used:
|
|
|
|
.. code-block:: python
|
|
|
|
sock_dir = '/var/run/salt/minion'
|
|
|
|
So long as the salt-master process is running, the master socket can be used:
|
|
|
|
.. code-block:: python
|
|
|
|
sock_dir = '/var/run/salt/master'
|
|
|
|
This allows 3rd party applications to harness the power of the Salt event bus
|
|
programmatically, without having to make other calls to Salt. A 3rd party
|
|
process can listen to the event bus on the master, and another 3rd party
|
|
process can fire events to the process on the master, which Salt will happily
|
|
pass along.
|
|
|