Mattermost

Install BotKube to the Mattermost team

Follow the steps below to install BotKube in your Mattermost Team (v5.11.1).

1. Enable Personal Access Token

Login with System Admin account, and in the Menu proceed to System console > Integrations > Custom Integrations and enable Personal Access Token.

mm_token_access

2. Create BotKube user

To create a BotKube user, if not already created, proceed to menu and Get team invite link. Logout from admin account and paste the link in the address bar and create a user with the username BotKube.

mm_botkube_user

3. Manage Roles for BotKube user

Login as System Admin, in the Menu proceed to System console > Users. For BotKube user, Manage Roles and allow tokens and post_all access.

mm_botkube_roles

4. Create Token for BotKube user

Login as BotKube user, in the Menu proceed to Account Settings > Security > Personal Access Token > Create and save the token.

mm_botkube_token

5. Add BotKube to a channel

Add BotKube user created to the channel you want to receive notifications in.

Configure /botkubehelp Slash Command

1. First, go to Main Menu > Integrations > Slash Commands. (If you don’t have the Integrations option in your Main Menu, slash commands may not be enabled on your Mattermost server or may be disabled for non-admins. Enable them from System Console > Integrations > Custom Integrations in prior versions)

2. Click Add Slash Command and add following details for the command and click Save.

FieldValue
TitleBotKube
DescriptionShow BotKube help
Command Trigger Wordbotkubehelp
Request URLhttps://botkube.herokuapp.com/help
Request MethodPOST
AutocompleteTrue

mm_botkube_slash_cmd

3. Verify executing /botkubehelp in a channel.

mm_botkube_help

Install BotKube in Kubernetes cluster

BotKube install: Using helm

  • We will be using helm to install BotKube in Kubernetes. Follow this guide to install helm if you don’t have it installed already
  • Clone the BotKube github repository.
$ git clone https://github.com/infracloudio/botkube.git
  • Update default config in helm/botkube/values.yaml to watch the resources you want (by default you will receive create, delete and error events for all the resources in all the namespaces). If you are not interested in events about particular resource, just remove its entry from the config file.
  • Deploy BotKube backend using helm install in your cluster.
$ helm install --name botkube --namespace botkube \
--set config.communications.mattermost.enabled=true \
--set config.communications.mattermost.url=<MATTERMOST_SERVER_URL> \
--set config.communications.mattermost.cert=<MATTERMOST_CERT> \
--set config.communications.mattermost.token=<MATTERMOST_TOKEN> \
--set config.communications.mattermost.team=<MATTERMOST_TEAM> \
--set config.communications.mattermost.channel=<MATTERMOST_CHANNEL> \
--set config.settings.clustername=<CLUSTER_NAME> \
--set config.settings.allowkubectl=<ALLOW_KUBECTL> \
helm/botkube

where,
- MATTERMOST_ENABLED set true to enable Mattermost support for BotKube
- MATTERMOST_SERVER_URL is the URL where Mattermost is running
- MATTERMOST_CERT is the SSL certificate file for HTTPS connection. Place it in Helm directory and specify the path
- MATTERMOST_TOKEN is the Token received by creating Personal Access Token for BotKube user
- MATTERMOST_TEAM is the Team name where BotKube is added
- MATTERMOST_CHANNEL is the Channel name where BotKube is added and used for communication
- CLUSTER_NAME is the cluster name set in the incoming messages
- ALLOW_KUBECTL set true to allow kubectl command execution by BotKube on the cluster

  • To deploy with TLS, replace MATTERMOST_CERT with the location of SSL certificate file placed in Helm directory. Leave this value to None if deploying without TLS.

Configuration syntax is explained here.

  • Send @BotKube ping in the channel to see if BotKube is running and responding.


Using kubectl

  • Make sure that you have kubectl cli installed and have access to Kubernetes cluster
  • Download deployment specs yaml
$ wget -q https://raw.githubusercontent.com/infracloudio/botkube/master/deploy-all-in-one.yaml
  • Open downloaded deploy-all-in-one.yaml and update the configuration.
    Set MATTERMOST_ENABLED, MATTERMOST_SERVER_URL, MATTERMOST_TOKEN, MATTERMOST_TEAM, MATTERMOST_CHANNEL, clustername, allowkubectl and update the resource events configuration you want to receive notifications for in the configmap.

where,
- MATTERMOST_ENABLED set true to enable Mattermost support for BotKube
- MATTERMOST_SERVER_URL is the URL where Mattermost is running
- MATTERMOST_TOKEN is the Token received by creating Personal Access Token for BotKube user
- MATTERMOST_TEAM is the Team name where BotKube is added
- MATTERMOST_CHANNEL is the Channel name where BotKube is added and used for communication
- clustername is the cluster name set in the incoming messages
- allowkubectl set true to allow kubectl command execution by BotKube on the cluster

Configuration syntax is explained here.

  • Create botkube namespace and deploy resources
$ kubectl create ns botkube && kubectl create -f deploy-all-in-one.yaml -n botkube
  • Check pod status in botkube namespace. Once running, send @BotKube ping in the Slack channel to confirm if BotKube is responding correctly.

  • To deploy with TLS, download and use deploy-all-in-one-tls.yaml. Replace ENCODED_CERTIFICATE with your base64 encoded certificate value in the secret. To get a base64 encoded value of your certificate, use below command and replace with the certificate name.

$ cat <YOUR_CERTIFICATE> | base64 -w 0 


Remove BotKube from Mattermost Team

- Deactive or remove BotKube user from Mattermost Team. Login as System Admin, in the Menu proceed to System console -> Users -> Deactivate
- Archive Channel created for BotKube communication if required.

Remove BotKube from Kubernetes cluster

Using helm

If you have installed BotKube backend using helm, execute following command to completely remove BotKube and related resources from your cluster

$ helm delete --purge botkube

BotKube install: Using kubectl

$ kubectl delete -f https://raw.githubusercontent.com/infracloudio/botkube/master/deploy-all-in-one.yaml -n botkube