salt.engines.slack module

An engine that reads messages from Slack and can act on them

depends: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 following URL, and replace myworkspace with the proper value for your workspace:

https://myworkspace.slack.com/apps/manage/custom-integrations

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 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 messages from each channel in which the bot is a member, so it is recommended to narrowly define the commands which can be executed, and the Slack users which are allowed to run commands.

This engine has two boolean configuration parameters that toggle specific features (both default to False):

  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:

    • target - The target expression to use for the command
    • 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.

    Here are a few examples:

    !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

Changed in version 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.

engines:
  - slack:
      token: 'xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx'
      control: True
      fire_all: False
      groups_pillar_name: 'slack_engine:groups_pillar'
      groups:
        default:
          users:
            - '*'
          commands:
            - test.ping
            - cmd.run
            - list_jobs
            - list_commands
          aliases:
            list_jobs:
              cmd: jobs.list_jobs
            list_commands:
              cmd: 'pillar.get salt:engines:slack:valid_commands target=saltmaster tgt_type=list'
          default_target:
            target: saltmaster
            tgt_type: glob
          targets:
            test.ping:
              target: '*'
              tgt_type: glob
            cmd.run:
              target: saltmaster
              tgt_type: list

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.

engines:
  - slack:
      groups_pillar: slack_engine_pillar
      token: 'xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx'
      control: True
      fire_all: True
      tag: salt/engines/slack
      groups_pillar_name: 'slack_engine:groups_pillar'
      groups:
        default:
          users:
            - '*'
          commands:
            - test.ping
          aliases:
            list_jobs:
              cmd: jobs.list_jobs
            list_commands:
              cmd: 'pillar.get salt:engines:slack:valid_commands target=saltmaster tgt_type=list'
        gods:
          users:
            - garethgreenaway
          commands:
            - '*'
salt.engines.slack.start(token, control=False, trigger=u'!', groups=None, groups_pillar_name=None, fire_all=False, tag=u'salt/engines/slack')

Listen to slack events and forward them to salt, new version