diff --git a/docs/installation/slack/assets/cloud_slack_command_all_clusters.png b/docs/installation/slack/assets/cloud_slack_command_all_clusters.png new file mode 100644 index 00000000..f0629ad8 Binary files /dev/null and b/docs/installation/slack/assets/cloud_slack_command_all_clusters.png differ diff --git a/docs/installation/slack/assets/cloud_slack_command_help.png b/docs/installation/slack/assets/cloud_slack_command_help.png new file mode 100644 index 00000000..a141f676 Binary files /dev/null and b/docs/installation/slack/assets/cloud_slack_command_help.png differ diff --git a/docs/installation/slack/assets/cloud_slack_command_list_instances.png b/docs/installation/slack/assets/cloud_slack_command_list_instances.png new file mode 100644 index 00000000..ff0f1375 Binary files /dev/null and b/docs/installation/slack/assets/cloud_slack_command_list_instances.png differ diff --git a/docs/installation/slack/assets/cloud_slack_command_set_default.png b/docs/installation/slack/assets/cloud_slack_command_set_default.png new file mode 100644 index 00000000..cf489aed Binary files /dev/null and b/docs/installation/slack/assets/cloud_slack_command_set_default.png differ diff --git a/docs/installation/slack/cloud-slack.md b/docs/installation/slack/cloud-slack.md index 873515bb..be800e48 100644 --- a/docs/installation/slack/cloud-slack.md +++ b/docs/installation/slack/cloud-slack.md @@ -10,7 +10,11 @@ The Botkube Cloud Slack App uses Botkube Cloud services to manage channels and r - A Botkube Cloud account with active subscription. - You can try out the Botkube Cloud Slack App for free by creating an account in the [Botkube Web App](https://app.botkube.io) and starting a free trial. +You can try out the Botkube Cloud Slack App for free by creating an account in the [Botkube Web App](https://app.botkube.io) and starting a free trial. You will need an active subscription to continue using the Botkube Cloud Slack App after the trial period. + +:::warning +Once you downgrade your subscription to free, you will not be able to use Botkube commands whereas you will continue to receive notification from Slack. +::: ## Create a Botkube Cloud Instance with Cloud Slack @@ -58,6 +62,30 @@ The Botkube Cloud Slack App uses Botkube Cloud services to manage channels and r ![Cloud Slack Summary](assets/cloud_slack_summary.png "Cloud Slack summary") +## Using Botkube Cloud Slack App + +You can start using Botkube Cloud Slack App by typing `@Botkube cloud help` in the Slack channel you configured in one of the previous steps. + +![Cloud Slack Command Help](assets/cloud_slack_command_help.png "Cloud Slack command help") + +### Listing Cloud Instances + +You can list all the Botkube Cloud instances by typing `@Botkube cloud list instances` in the Slack channel or click the button `List connected instances` in the help command response. +Besides the instance `name`, `ID`, and `status` in the list response, you can also see a button `Get details` that you can click to go to instance details on Botkube Cloud Dashboard. + +![Cloud Slack List Instances](assets/cloud_slack_command_list_instances.png "Cloud Slack list instances") + +### Setting Default Cloud Instances + +Once a Botkube command is executed, it will be handled on target kubernetes cluster specified with `--cluster-name` flag. However, this is an optional flag, +where if you have not specified it, Botkube Cloud will select the first instance. However, you can also achieve setting default instance with command `@Botkube cloud set default-instance instance_id`. + +![Cloud Slack Set Default Instances](assets/cloud_slack_command_set_default.png "Cloud Slack set default instance") + +After this point, all of your commands will be executed on the default instance. Moreover, if you want to execute a command on all the target clusters, you can use `--all-clusters` flag. + +![Cloud Slack All Clusters](assets/cloud_slack_command_all_clusters.png "Cloud Slack all clusters") + ## Clean up 1. Go to Botkube Cloud instances page and click `Manage` button of the instance you want to remove. diff --git a/docs/installation/slack/socket-slack/cloud.md b/docs/installation/slack/socket-slack/cloud.md index 01608f7d..6d231a23 100644 --- a/docs/installation/slack/socket-slack/cloud.md +++ b/docs/installation/slack/socket-slack/cloud.md @@ -10,7 +10,168 @@ sidebar_position: 3 ## Install Socket Slack App in Your Slack workspace -// TODO: Basically copy "Install Socket Slack App in Your Slack workspace" and adjust it so that env variables are not needed. +Botkube uses interactive messaging to provide better experience. Interactive messaging needs a Slack App with Socket Mode enabled and currently this is not suitable for Slack App Directory listing. For this reason, you need to create a Slack App in your own Slack workspace and use it for Botkube deployment. + +:::warning +**Multi-cluster caveat:** The architecture of socket-based Slack apps has a limitation on the routing of executor commands. If you would like to use [Botkube executors](../../../configuration/executor/index.md) (e.g. kubectl commands) and have multiple Kubernetes clusters, you need to create and install a Botkube Slack app for each cluster. This is required so that the Slack to Botkube connections go to the right place. We recommend you set the name of each app to reflect the cluster it will connect to in the next steps. + +To learn more about the Slack Socket API limitation, see the [comment](https://github.com/slackapi/bolt-js/issues/1263#issuecomment-1006372826) in the official Slack bot framework repository. + +The [Botkube Cloud Slack App](#botkube-cloud-slack-app) does not have this limitation. +::: + +Follow the steps below to create and install Botkube Slack app to your Slack workspace. + +### Create Slack app + +1. Go to [Slack App console](https://api.slack.com/apps) to create an application. +1. Click **Create New App** and select **From an app manifest** in the popup to create application from manifest. + + ![Create App from Manifest](../assets/slack_add_app.png "Slack add app") + +1. Select a workspace where you want to create application and click **Next**. + + ![Select Workspace](../assets/slack_select_workspace.png "Slack select workspace") + +1. Select **YAML** tab, copy & paste one of the following manifests, and click **Next**, and then **Create**. + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +
+ + + +```yaml +display_information: + name: Botkube + description: Botkube + background_color: "#a653a6" +features: + bot_user: + display_name: Botkube + always_online: false +oauth_config: + scopes: + bot: + - channels:read + - app_mentions:read + - reactions:write + - chat:write + - files:write + - users:read # Remote configuration only: Used to get Real Name for audit reporting +settings: + event_subscriptions: + bot_events: + - app_mention + interactivity: + is_enabled: true + org_deploy_enabled: false + socket_mode_enabled: true + token_rotation_enabled: false +``` + + + + +```yaml +display_information: + name: Botkube + description: Botkube + background_color: "#a653a6" +features: + bot_user: + display_name: Botkube + always_online: false +oauth_config: + scopes: + bot: + - groups:read + - app_mentions:read + - reactions:write + - chat:write + - files:write + - users:read # Remote configuration only: Used to get Real Name for audit reporting +settings: + event_subscriptions: + bot_events: + - app_mention + interactivity: + is_enabled: true + org_deploy_enabled: false + socket_mode_enabled: true + token_rotation_enabled: false +``` + + + + +```yaml +display_information: + name: Botkube + description: Botkube + background_color: "#a653a6" +features: + bot_user: + display_name: Botkube + always_online: false +oauth_config: + scopes: + bot: + - channels:read + - groups:read + - app_mentions:read + - reactions:write + - chat:write + - files:write + - users:read # Remote configuration only: Used to get Real Name for audit reporting +settings: + event_subscriptions: + bot_events: + - app_mention + interactivity: + is_enabled: true + org_deploy_enabled: false + socket_mode_enabled: true + token_rotation_enabled: false +``` + + + +
+ +### Install Botkube to the Slack workspace + +Once the application is created, you will be redirected to application details page. Press the **Install your app** button, select the workspace and click **Allow to finish installation**. + +![Install Slack App](../assets/slack_install_app.png "Slack install app") + +### Obtain Bot Token + +Follow the steps to obtain the Bot Token: + +1. Select **OAuth & Permissions** section on the left sidebar. On this page you can copy the bot token which starts with `xoxb...`. + + ![Retrieve Slack Bot Token](../assets/slack_retrieve_bot_token.png "Slack Bot Token") + +:::tip +Please note down the `Bot User Oauth Token` for the next step. +::: + +### Generate and obtain App-Level Token + +Slack App with Socket Mode requires an App-Level Token for the websocket connection. + +Follow the steps to generate an App-Level Token: + +1. Select **Basic Information** link from the left sidebar and scroll down to section **App-Level Token**. Click on the **Generate Token and Scopes** button. +1. Enter a **Name**, select `connections:write` scope, and click **Generate**. + + ![Generate App-Level Token](../assets/slack_generate_app_token.png "Slack App Token") + + ![Retrieve App-Level Token](../assets/slack_retrieve_app_token.png "Slack Retrieve App Token") + +Please note down the `Token` for the next step. ## Create a Botkube Cloud Instance @@ -33,8 +194,8 @@ sidebar_position: 3 5. Provide the Slack app details as described follows and click `Next` button. - **Display :** This is the name of the Slack app which will be displayed in your platform list. - - **App Token:** Grab `SLACK_API_APP_TOKEN` as described [here](./self-hosted.md#generate-and-obtain-app-level-token). - - **Bot Token:** Grab `SLACK_API_BOT_TOKEN` as described [here](./self-hosted.md#obtain-bot-token). + - **App Token:** Use the app token noted down in the previous step. + - **Bot Token:** Use the bot token noted down in the previous step. - **Channel Name:** Slack channel where you can execute Botkube commands and receive notification. ![Cloud Slack Credentials](../assets/cloud_slack_credentials.png "Cloud Slack credentials")