mirror of
https://github.com/saltstack/salt.git
synced 2025-04-17 10:10:20 +00:00
Improve the slack engine docs
This explains the target/tgt_type options, adds some usage examples, and makes a few other documentation tweaks.
This commit is contained in:
Erik Johnson
parent
dde9c0640d
commit
56e8a1eb93
2 changed files with 64 additions and 35 deletions
|
|
@ -1,3 +1,5 @@
|
|||
.. _event-system:
|
||||
|
||||
============
|
||||
Event System
|
||||
============
|
||||
|
|
@ -12,8 +14,8 @@ Event Bus
|
|||
The event system is comprised of a two primary components, which make up the
|
||||
concept of an Event Bus:
|
||||
|
||||
* The event sockets which publishes events.
|
||||
* The event library which can listen to events and send events into the salt system.
|
||||
- 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.
|
||||
|
|
@ -237,4 +239,4 @@ done at the CLI:
|
|||
'success': True,
|
||||
'message': "It works!",
|
||||
}
|
||||
)
|
||||
)
|
||||
|
|
|
|||
|
|
@ -2,11 +2,13 @@
|
|||
'''
|
||||
An engine that reads messages from Slack and can act on them
|
||||
|
||||
.. versionadded: 2016.3.0
|
||||
|
||||
:depends: `slackclient <https://pypi.org/project/slackclient/>`_ Python module
|
||||
|
||||
.. important::
|
||||
This engine requires a bot user. To create a bot user, first go to the
|
||||
Custom Integrations page in your Slack Workspace. Copy and paste the
|
||||
**Custom Integrations** page in your Slack Workspace. Copy and paste the
|
||||
following URL, and replace ``myworkspace`` with the proper value for your
|
||||
workspace:
|
||||
|
||||
|
|
@ -15,8 +17,8 @@ An engine that reads messages from Slack and can act on them
|
|||
Next, click on the ``Bots`` integration and request installation. Once
|
||||
approved by an admin, you will be able to proceed with adding the bot user.
|
||||
Once the bot user has been added, you can configure it by adding an avatar,
|
||||
setting the display name, etc. You'll also at this time have access to your
|
||||
API token, which will be needed to configure this engine.
|
||||
setting the display name, etc. You will also at this time have access to
|
||||
your API token, which will be needed to configure this engine.
|
||||
|
||||
Finally, add this bot user to a channel by switching to the channel and
|
||||
using ``/invite @mybotuser``. Keep in mind that this engine will process
|
||||
|
|
@ -25,23 +27,58 @@ An engine that reads messages from Slack and can act on them
|
|||
Slack users which are allowed to run commands.
|
||||
|
||||
|
||||
1. When the ``control`` parameter is set to ``True`` and a message is prefaced
|
||||
with the ``trigger`` (which defaults to ``!``) then the engine will
|
||||
validate that the user has permission, and if so will run the command
|
||||
This engine has two boolean configuration parameters that toggle specific
|
||||
features (both default to ``False``):
|
||||
|
||||
2. In addition, when the parameter ``fire_all`` is set (defaults to False),
|
||||
all other messages (the messages that aren't control messages) will be
|
||||
fired off to the salt event bus with the tag prefixed by the string
|
||||
provided by the ``tag`` config option (defaults to ``salt/engines/slack``).
|
||||
1. ``control`` - If set to ``True``, then any message which starts with the
|
||||
trigger string (which defaults to ``!`` and can be overridden by setting the
|
||||
``trigger`` option in the engine configuration) will be interpreted as a
|
||||
Salt CLI command and the engine will attempt to run it. The permissions
|
||||
defined in the various ``groups`` will determine if the Slack user is
|
||||
allowed to run the command. The ``targets`` and ``default_target`` options
|
||||
can be used to set targets for a given command, but the engine can also read
|
||||
the following two keyword arguments:
|
||||
|
||||
This allows for configuration to be gotten from either the engine config, or from
|
||||
the saltmaster's minion pillar.
|
||||
- ``target`` - The target expression to use for the command
|
||||
|
||||
.. versionadded: 2016.3.0
|
||||
- ``tgt_type`` - The match type, can be one of ``glob``, ``list``,
|
||||
``pcre``, ``grain``, ``grain_pcre``, ``pillar``, ``nodegroup``, ``range``,
|
||||
``ipcidr``, or ``compound``. The default value is ``glob``.
|
||||
|
||||
:configuration: Example configuration using only a 'default' group. The default
|
||||
group is not special. In addition, other groups are being loaded from
|
||||
pillars.
|
||||
Here are a few examples:
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
!test.ping target=*
|
||||
!state.apply foo target=os:CentOS tgt_type=grain
|
||||
!pkg.version mypkg target=role:database tgt_type=pillar
|
||||
|
||||
2. ``fire_all`` - If set to ``True``, all messages which are not prefixed with
|
||||
the trigger string will fired as events onto Salt's ref:`event bus
|
||||
<event-system>`. The tag for these veents will be prefixed with the string
|
||||
specified by the ``tag`` config option (default: ``salt/engines/slack``).
|
||||
|
||||
|
||||
The ``groups_pillar_name`` config option can be used to pull group
|
||||
configuration from the specified pillar key.
|
||||
|
||||
.. note::
|
||||
In order to use ``groups_pillar_name``, the engine must be running as a
|
||||
minion running on the master, so that the ``Caller`` client can be used to
|
||||
retrieve that minions pillar data, because the master process does not have
|
||||
pillar data.
|
||||
|
||||
|
||||
Configuration Examples
|
||||
======================
|
||||
|
||||
.. versionchanged:: 2017.7.0
|
||||
Access control group support added
|
||||
|
||||
This example uses a single group called ``default``. In addition, other groups
|
||||
are being loaded from pillar data. The group names do not have any
|
||||
significance, it is the users and commands defined within them that are used to
|
||||
determine whether the Slack user has permission to run the desired command.
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
|
|
@ -54,7 +91,7 @@ the saltmaster's minion pillar.
|
|||
groups:
|
||||
default:
|
||||
users:
|
||||
- *
|
||||
- '*'
|
||||
commands:
|
||||
- test.ping
|
||||
- cmd.run
|
||||
|
|
@ -76,12 +113,9 @@ the saltmaster's minion pillar.
|
|||
target: saltmaster
|
||||
tgt_type: list
|
||||
|
||||
:configuration: Example configuration using the 'default' group and a
|
||||
non-default group and a pillar that will be merged in If the user is '*'
|
||||
(without the quotes) then the group's users or commands will match all
|
||||
users as appropriate
|
||||
|
||||
.. versionadded: 2017.7.0
|
||||
This example shows multiple groups applying to different users, with all users
|
||||
having access to run test.ping. Keep in mind that when using ``*``, the value
|
||||
must be quoted, or else PyYAML will fail to load the configuration.
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
|
|
@ -96,7 +130,7 @@ the saltmaster's minion pillar.
|
|||
groups:
|
||||
default:
|
||||
users:
|
||||
- *
|
||||
- '*'
|
||||
commands:
|
||||
- test.ping
|
||||
aliases:
|
||||
|
|
@ -108,13 +142,7 @@ the saltmaster's minion pillar.
|
|||
users:
|
||||
- garethgreenaway
|
||||
commands:
|
||||
- *
|
||||
|
||||
.. note:: groups_pillar_name
|
||||
|
||||
In order to use this, the engine must be running as a minion running on
|
||||
the master, so that the ``Caller`` client can be used to retrieve that
|
||||
minions pillar data, because the master process does not have pillars.
|
||||
- '*'
|
||||
|
||||
'''
|
||||
|
||||
|
|
@ -348,7 +376,6 @@ class SlackClient(object):
|
|||
cmdlist.append(cmditem)
|
||||
return cmdlist
|
||||
|
||||
# m_data -> m_data, _text -> test, all_slack_users -> all_slack_users,
|
||||
def control_message_target(self, slack_user_name, text, loaded_groups, trigger_string):
|
||||
'''Returns a tuple of (target, cmdline,) for the response
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue