Version: Unreleased 🚧

Communication

info

This document is applicable only for self-hosted installations. For Botkube Cloud installations, the Botkube Agent configuration is managed via the Botkube Cloud dashboard.

The communication settings contain:

Configuration for communication platforms scoped in separate communication groups,
Platform-specific options, such as multichannel configuration for platforms that support channels.

The settings are applicable only for self-hosted Botkube installation. Cloud Slack and Microsoft Teams platforms are exclusive to Botkube Cloud.

Communication groups

Communication group is a way to aggregate separate configurations for a set of communication platforms. You can specify multiple communication groups, and, in a result, support multiple Slack or Mattermost workspaces, Discord servers, or Elasticsearch server instances.

Also, most platforms also support another level of multiple configurations within a workspace. For example, Slack supports multichannel configuration. To learn more about platform-specific options, see the Syntax section.

note

The purpose of the communication group is to allow using multiple workspaces, e.g. for Slack or Mattermost. To use multiple channels inside the same workspace, don't define separate communication groups, but use channels property under a given communication platform instead.

Example

Consider the following configuration:

communications:
  "first-group": # Your own alias of a given communication group
    socketSlack:
      enabled: true
      botToken: "{SLACK_BOT_TOKEN_1}" # Bot token for Botkube App for Slack installed in Workspace 1
      appToken: "{SLACK_APP_TOKEN_1}" # App token for Botkube App for Slack installed in Workspace 1
      channels:
        "general": # Your own alias for the channel configuration
          name: general
          bindings:
            executors: # Executors configuration for a given channel
              - k8s-default-tools
            sources: # Notification sources configuration for a given channel
              - k8s-events
        "random": # Your own alias for the channel configuration
          name: random
          bindings:
            executors: [] # Executors configuration for a given channel
            sources: # Notification sources configuration for a given channel
              - k8s-events
  "second-group": # Your own alias of a given communication group
    socketSlack:
      enabled: true
      botToken: "{SLACK_BOT_TOKEN_2}" # Bot token for Botkube App for Slack installed in Workspace 2
      appToken: "{SLACK_APP_TOKEN_2}" # App token for Botkube App for Slack installed in Workspace 2
      channels:
        "primary-channel": # Your own alias for the channel configuration
          name: general
          notification:
            # If true, the notifications are not sent to the channel. They can be enabled with `@Botkube` command anytime.
            disabled: true
          bindings:
            executors: # Executors configuration for a given channel
              - k8s-default-tools
            sources: # Notification sources configuration for a given channel
              - k8s-events

The example YAML configuration definition results in the following configuration.

For Slack Workspace 1, as defined by the first communication group (first-group):

Notifications from k8s-events source are sent to the general and random channels.
Commands from the k8s-default-tools configuration can be executed in the general channel. On random channel executors are not configured.

For Slack Workspace 2, as defined by the second communication group (second-group):

Notifications are configured to be sent from the k8s-events source to the general channel. They are disabled by default, and can be enabled with @Botkube command or during Botkube upgrade.
Commands from the k8s-default-tools configuration can be executed in the general channel.

Source and Executor Bindings

Most of the communication platforms support executor and source bindings, which allows fine-tuning the notifications and allowed Botkube commands inside a given channel.

With executor bindings you can configure which executors are allowed in a given channel. To read more about executor configuration, see the Executor document.

With source bindings, you can specify which events are sent to a given channel (or, in case of Elasticsearch, index). To read more about source configuration, see the Source document.

Syntax

Each communication platform has specific options, however they share a similar syntax for consistency. For example, bot integrations such as Slack, Mattermost or Discord have multichannel support, that is you can configure multiple channels with separate bindings. Same with Elasticsearch - you can forward notifications to multiple Elasticsearch indices, according to the sources configuration.

# Map of communication groups. Communication group contains settings for multiple communication platforms.
# The property name under `communications` object is an alias for a given configuration group. You can define multiple communication groups with different names.
# @default -- See the `values.yaml` file for full object.
#
## Format: communications.{alias}
communications:
  "default-group":
    ## Settings for Slack with Socket Mode.
    socketSlack:
      # If true, enables bot for Slack.
      enabled: false
      # Map of configured channels. The property name under `channels` object is an alias for a given configuration.
      #
      ## Format: channels.{alias}
      channels:
        "default":
          # Slack channel name without '#' prefix where you have added Botkube and want to receive notifications in.
          name: "SLACK_CHANNEL"
          bindings:
            # Executors configuration for a given channel.
            executors:
              - k8s-default-tools
            # Notification sources configuration for a given channel.
            sources:
              - k8s-err-events
              - k8s-recommendation-events
      # Bot for Slack token for your own app for Slack.
      # [Ref doc](https://api.slack.com/authentication/token-types).
      botToken: ""
      # Slack app-level token for your own app for Slack.
      # [Ref doc](https://api.slack.com/authentication/token-types).
      appToken: ""
    ## Settings for Mattermost.
    mattermost:
      # If true, enables Mattermost bot.
      enabled: false
      # User in Mattermost which belongs the specified Personal Access token.
      botName: "Botkube"
      # The URL (including http/https schema) where Mattermost is running. e.g https://example.com:9243
      url: "MATTERMOST_SERVER_URL"
      # Personal Access token generated by Botkube user.
      token: "MATTERMOST_TOKEN"
      # The Mattermost Team name where Botkube is added.
      team: "MATTERMOST_TEAM"
      # Map of configured channels. The property name under `channels` object is an alias for a given configuration.
      #
      ## Format: channels.{alias}
      channels:
        "default":
          # The Mattermost channel name for receiving Botkube alerts.
          # The Botkube user needs to be added to it.
          name: "MATTERMOST_CHANNEL"
          notification:
            # If true, the notifications are not sent to the channel. They can be enabled with `@Botkube` command anytime.
            disabled: false
          bindings:
            # Executors configuration for a given channel.
            executors:
              - k8s-default-tools
            # Notification sources configuration for a given channel.
            sources:
              - k8s-err-events
              - k8s-recommendation-events

    ## Settings for Discord.
    discord:
      # If true, enables Discord bot.
      enabled: false
      # Botkube Bot Token.
      token: "DISCORD_TOKEN"
      # Botkube Application Client ID.
      botID: "DISCORD_BOT_ID"
      # Map of configured channels. The property name under `channels` object is an alias for a given configuration.
      #
      ## Format: channels.{alias}
      channels:
        "default":
          # Discord channel ID for receiving Botkube alerts.
          # The Botkube user needs to be added to it.
          id: "DISCORD_CHANNEL_ID"
          notification:
            # If true, the notifications are not sent to the channel. They can be enabled with `@Botkube` command anytime.
            disabled: false
          bindings:
            # Executors configuration for a given channel.
            executors:
              - k8s-default-tools
            # Notification sources configuration for a given channel.
            sources:
              - k8s-err-events
              - k8s-recommendation-events

    ## Settings for Elasticsearch.
    elasticsearch:
      # If true, enables Elasticsearch.
      enabled: false
      awsSigning:
        # If true, enables awsSigning using IAM for Elasticsearch hosted on AWS. Make sure AWS environment variables are set.
        # [Ref doc](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html).
        enabled: false
        # AWS region where Elasticsearch is deployed.
        awsRegion: "us-east-1"
        # AWS IAM Role arn to assume for credentials, use this only if you don't want to use the EC2 instance role or not running on AWS instance.
        roleArn: ""
      # The server URL, e.g https://example.com:9243
      server: "ELASTICSEARCH_ADDRESS"
      # Basic Auth username.
      username: "ELASTICSEARCH_USERNAME"
      # Basic Auth password.
      password: "ELASTICSEARCH_PASSWORD"
      # If true, skips the verification of TLS certificate of the Elastic nodes.
      # It's useful for clusters with self-signed certificates.
      skipTLSVerify: false
      # Specify the log level for Elasticsearch client. Leave empty to disable logging.
      ## Possible values: "info", "error", "trace".
      ## - "info": Logs information level messages.
      ## - "error": Logs information and error level messages.
      ## - "trace": Logs information, error, and trace level messages.
      ## To disable logging, simply leave the logLevel empty or remove the line.
      logLevel: ""

      # Map of configured indices. The `indices` property name is an alias for a given configuration.
      #
      ## Format: indices.{alias}
      indices:
        "default":
          # Configures Elasticsearch index settings.
          name: botkube
          type: botkube-event
          shards: 1
          replicas: 0
          bindings:
            # Notification sources configuration for a given index.
            sources:
              - k8s-err-events
              - k8s-recommendation-events

    ## Settings for Webhook.
    webhook:
      # If true, enables Webhook.
      enabled: false
      # The Webhook URL, e.g.: https://example.com:80
      url: "WEBHOOK_URL"
      bindings:
        # Notification sources configuration for the webhook.
        sources:
          - k8s-err-events
          - k8s-recommendation-events

The default configuration for Helm chart can be found in values.yaml.

Communication groups​

Example​

Source and Executor Bindings​

Syntax​

Communication groups

Example

Source and Executor Bindings

Syntax