Update documentation after plugin extraction (#311)

kubeshop · Feb 26, 2024 · 5766397 · 5766397
1 parent 1b15b95
commit 5766397
Show file tree

Hide file tree

Showing 39 changed files with 1,317 additions and 804 deletions.
diff --git a/.mlc.config.json b/.mlc.config.json
@@ -11,6 +11,15 @@
     },
     {
       "pattern": "^https://botkube.herokuapp.com/help"
+    },
+    {
+      "pattern": "^https://get.helm.sh/helm-v3.6.3-.+.tar.gz//.+"
+    },
+    {
+      "pattern": "^https://github.com/zyedidia/eget/releases/download/v1.3.3/eget-1.3.3-.+.tar.gz//.+"
+    },
+    {
+      "pattern": "^https://github.com/cli/cli/releases/download/v2.32.1/gh_2.32.1_.+.(zip|tar.gz)//.+"
     }
   ],
   "replacementPatterns": []

diff --git a/docs/architecture/index.md b/docs/architecture/index.md
@@ -31,11 +31,9 @@ Plugin executor bridge is resolving the received Botkube command, calling the re
 
 ### Executor
 
-Executor is a binary that implements the [executor](https://github.com/kubeshop/botkube/blob/main/proto/executor.proto) Protocol Buffers contract. Executor runs a given command and returns the response in a synchronous way. For example, running `kubectl` or `helm` commands.
+Executor is a binary that implements the [executor](https://github.com/kubeshop/botkube/blob/main/proto/executor.proto) Protocol Buffers contract. Executor runs a given command, such as `kubectl` one, and returns the response in a synchronous way.
 
-Streaming command response is not supported. As a result, commands like `helm install --wait` doesn't work well, as the response won't be sent until the command finishes.
-
-The `kubectl` is a built-in Botkube executor. It will be extracted in the future Botkube releases.
+Streaming command response is not supported. As a result, commands which take a lot of time doesn't work well, as the response won't be sent until the command is finished.
 
 ### Plugin source bridge
 

diff --git a/docs/architecture/teams.md b/docs/architecture/teams.md
@@ -12,7 +12,7 @@ This document describes the communication between the Botkube Cloud control-plan
 ### Agent outbound connections
 
 - HTTPS: `https://api.segment.io/*`
-- HTTPS: `https://api.botkube.io/graphql`
+- HTTPS: `https://api.botkube.io/*`
 - HTTPS: `https://github.com/kubeshop/botkube/releases/download/*`
 - HTTP/2: `teams.botkube.io:50054`
 - Docker images: https://ghcr.io more about required ports you can on [About GitHub's IP addresses](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/about-githubs-ip-addresses):
@@ -35,23 +35,46 @@ The Botkube Agent Docker image is hosted on the GitHub Container registry, which
 
 ### Plugin manager
 
-During startup, the Botkube Agent downloads plugins index and all enabled plugins. Both the index and plugin archives are stored under a given Botkube GitHub release as [its assets](https://github.com/kubeshop/botkube/releases/tag/v1.8.0):
+The index and archives for open source plugins are stored under a given Botkube GitHub release as [its assets](https://github.com/kubeshop/botkube/releases/tag/v1.8.0):
 
 - Plugin index: `https://github.com/kubeshop/botkube/releases/download/{botkube_version}/plugins-index.yaml`, e.g., https://github.com/kubeshop/botkube/releases/download/v1.8.0/plugins-index.yaml
 - Plugin archive: `https://github.com/kubeshop/botkube/releases/download/{botkube_version}/{plugin_name_and_arch}.tar.gz` e.g., https://github.com/kubeshop/botkube/releases/download/v1.8.0/executor_kubectl_linux_amd64.tar.gz
-  - Plugin links can also be found in the `plugins-index.yaml` file
-
-All of them are stored under the `/tmp` folder mounted as the [`emptyDir`](https://github.com/kubeshop/botkube/blob/release-1.8/helm/botkube/templates/deployment.yaml#L146-L147). There is no Persistent Volume (PV), meaning that when the Agent Pod is, for example, rescheduled to another node, it downloads all dependencies again. To ensure that the [plugin manager](index.md#plugin-manager) does not make external calls, all required plugins must be present. You can achieve this by mounting a Persistent Volume Claim (PVC) at this path. Later, you can mount your Persistent Volume (PV) with cached plugins.
-
-### Plugins
-
-Each plugin may define required external dependencies that are downloaded by the [Plugin manager](#plugin-manager) at Agent startup. The whitelisting differs per plugin, as for now, those dependencies are taken from the official sources and are not mirrored to the Botkube Cloud registry. Here are the links that describe external dependencies for each officially supported plugin:
-
-- [`kubectl`](../configuration/executor/kubectl.md) executor: https://github.com/kubeshop/botkube/blob/release-1.8/internal/executor/kubectl/executor.go#L33-L42
-- [`exec`](../configuration/executor/exec.md) executor: https://github.com/kubeshop/botkube/blob/release-1.8/internal/executor/x/config.go#L29-L39
-- [`flux`](../configuration/executor/flux.md) executor: https://github.com/kubeshop/botkube/blob/release-1.8/internal/executor/flux/executor.go#L62-L81
-- [`helm`](../configuration/executor/helm.md) executor: https://github.com/kubeshop/botkube/blob/release-1.8/internal/executor/helm/executor.go#L24-L37
-- [`github-events`](../configuration/source/github-events.md) source: https://github.com/kubeshop/botkube/blob/release-1.8/cmd/executor/gh/main.go#L138-L157
+  - Plugin links can also be found in the `plugins-index.yaml` file.
+
+For the Botkube Cloud exclusive plugins, we serve plugin index via the Botkube Cloud API (`api.botkube.io`). As we use Google Cloud Storage as the storage provider, all the plugins are fetched from the `https://storage.googleapis.com` origin.
+
+During startup, the Botkube Agent downloads plugins index and all enabled plugins. They are stored under the `/tmp` folder mounted as the [`emptyDir`](https://github.com/kubeshop/botkube/blob/release-1.9/helm/botkube/templates/deployment.yaml#L146-L147). There is no Persistent Volume (PV), meaning that when the Agent Pod is, for example, rescheduled to another node, it downloads all dependencies again. To ensure that the [plugin manager](index.md#plugin-manager) does not make external calls, all required plugins must be present. You can achieve this by mounting a Persistent Volume Claim (PVC) at this path. Later, you can mount your Persistent Volume (PV) with cached plugins.
+
+### Plugin dependencies
+
+Each plugin may define required external dependencies that are downloaded by the [Plugin manager](#plugin-manager) at Agent startup. For now, those dependencies are taken from the official sources and are not mirrored to the Botkube Cloud registry. Here are the links that describe external dependencies for each officially supported plugin:
+
+- [`kubectl`](../configuration/executor/kubectl.md) executor: https://github.com/kubeshop/botkube/blob/release-1.9/internal/executor/kubectl/executor.go#L33-L42
+
+`helm` plugin:
+
+- `helm` dependency:
+  - https://get.helm.sh/helm-v3.6.3-darwin-amd64.tar.gz//darwin-amd64
+  - https://get.helm.sh/helm-v3.6.3-darwin-arm64.tar.gz//darwin-arm64
+  - https://get.helm.sh/helm-v3.6.3-linux-amd64.tar.gz//linux-amd64
+  - https://get.helm.sh/helm-v3.6.3-linux-arm64.tar.gz//linux-arm64
+- `exec` plugin:
+  - `eget` dependency:
+    - https://github.com/zyedidia/eget/releases/download/v1.3.3/eget-1.3.3-darwin_amd64.tar.gz//eget-1.3.3-darwin_amd64
+    - https://github.com/zyedidia/eget/releases/download/v1.3.3/eget-1.3.3-darwin_arm64.tar.gz//eget-1.3.3-darwin_arm64
+    - https://github.com/zyedidia/eget/releases/download/v1.3.3/eget-1.3.3-linux_amd64.tar.gz//eget-1.3.3-linux_amd64
+    - https://github.com/zyedidia/eget/releases/download/v1.3.3/eget-1.3.3-linux_arm64.tar.gz//eget-1.3.3-linux_arm64
+- `flux` plugin:
+  - `flux` dependency:
+    - https://github.com/fluxcd/flux2/releases/download/v2.0.1/flux_2.0.1_darwin_amd64.tar.gz
+    - https://github.com/fluxcd/flux2/releases/download/v2.0.1/flux_2.0.1_darwin_arm64.tar.gz
+    - https://github.com/fluxcd/flux2/releases/download/v2.0.1/flux_2.0.1_linux_amd64.tar.gz
+    - https://github.com/fluxcd/flux2/releases/download/v2.0.1/flux_2.0.1_linux_arm64.tar.gz
+  - `gh` dependency:
+    - https://github.com/cli/cli/releases/download/v2.32.1/gh_2.32.1_macOS_amd64.zip//gh_2.32.1_macOS_amd64/bin
+    - https://github.com/cli/cli/releases/download/v2.32.1/gh_2.32.1_macOS_arm64.zip//gh_2.32.1_macOS_arm64/bin
+    - https://github.com/cli/cli/releases/download/v2.32.1/gh_2.32.1_linux_amd64.tar.gz//gh_2.32.1_linux_amd64/bin
+    - https://github.com/cli/cli/releases/download/v2.32.1/gh_2.32.1_linux_arm64.tar.gz//gh_2.32.1_linux_arm64/bin
 
 If a plugin is not listed here, then it doesn't have any external dependencies.
 

diff --git a/docs/configuration/alias.md b/docs/configuration/alias.md
@@ -10,7 +10,21 @@ Aliases work for all commands, including executor plugins and Botkube built-in o
 
 Aliases are defined globally for the whole Botkube installation. Once they are configured, read the [Aliases](../usage/executor/index.md#aliases) section in Usage document.
 
-## Syntax
+## Botkube Cloud
+
+You can configure aliases in the Botkube Cloud dashboard.
+
+1. If you don't have an existing Botkube instance, create a new one, according to the [Installation](../installation/index.mdx) docs.
+2. From the [Botkube Cloud homepage](https://app.botkube.io), click the **Aliases** link in the top right corner.
+3. Click **Create new** button.
+4. Provide display name, alias and command.
+
+For example, for `exec` plugin, you can provide display name as `Exec alias`, alias as `x`, and command as `exec`.
+
+1. Select instances for which you want to enable the alias.
+1. Click **Apply** button.
+
+## Self-hosted Botkube syntax
 
 ```yaml
 # Custom aliases for given commands.

diff --git a/docs/configuration/communication/index.md b/docs/configuration/communication/index.md
@@ -9,6 +9,8 @@ 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.
@@ -26,9 +28,10 @@ Consider the following configuration:
 ```yaml
 communications:
   "first-group": # Your own alias of a given communication group
-    slack:
+    socketSlack:
       enabled: true
-      token: "{SLACK_TOKEN_1}" # Token for Botkube Slack app installed in Workspace 1
+      botToken: "{SLACK_BOT_TOKEN_1}" # Bot token for Botkube Slack app installed in Workspace 1
+      appToken: "{SLACK_APP_TOKEN_1}" # App token for Botkube Slack app installed in Workspace 1
       channels:
         "general": # Your own alias for the channel configuration
           name: general
@@ -44,9 +47,10 @@ communications:
             sources: # Notification sources configuration for a given channel
               - k8s-events
   "second-group": # Your own alias of a given communication group
-    slack:
+    socketSlack:
       enabled: true
-      token: "{SLACK_TOKEN_2}" # Token for Botkube Slack app installed in Workspace 2
+      botToken: "{SLACK_BOT_TOKEN_2}" # Bot token for Botkube Slack app installed in Workspace 2
+      appToken: "{SLACK_APP_TOKEN_2}" # App token for Botkube Slack app installed in Workspace 2
       channels:
         "primary-channel": # Your own alias for the channel configuration
           name: general
@@ -80,13 +84,6 @@ With executor bindings you can configure which executors are allowed in a given
 
 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](../source) document.
 
-## Known limitations
-
-Currently, [Microsoft Teams](../../installation/teams/) integration works differently than other bot integrations, such as Slack or Discord. While Microsoft Teams support multiple channels for forwarding notifications, you need to turn them on with `@Botkube enable notifications` on each channel. Microsoft Teams uses source and executor bindings defined under `communications.teams.bindings` property for all channels in the following way:
-
-- Executor bindings apply to all MS Teams channels where Botkube has access to.
-- Source bindings apply to all channels which have notification turned on with `@Botkube enable notifications` command.
-
 ## Syntax
 
 Each communication platform has specific options, however they share a similar syntax for consistency.
@@ -95,49 +92,51 @@ For example, bot integrations such as Slack, Mattermost or Discord have multicha
 ```yaml
 # 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}
+## Format: communications.{alias}
 communications:
   "default-group":
-    # Settings for Slack.
-    slack:
+    ## Settings for Slack with Socket Mode.
+    socketSlack:
       # If true, enables Slack bot.
       enabled: false
       # Map of configured channels. The property name under `channels` object is an alias for a given configuration.
       #
-      # Format: channels.{alias}
+      ## Format: channels.{alias}
       channels:
         "default":
           # Slack channel name without '#' prefix where you have added Botkube and want to receive notifications in.
           name: "SLACK_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-events
-      # Slack token.
-      token: "SLACK_API_TOKEN"
-
-    # Settings for Mattermost.
+              - k8s-err-events
+              - k8s-recommendation-events
+      # Slack bot token for your own Slack app.
+      # [Ref doc](https://api.slack.com/authentication/token-types).
+      botToken: ""
+      # Slack app-level token for your own Slack app.
+      # [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
+      # 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}
+      ## Format: channels.{alias}
       channels:
         "default":
           # The Mattermost channel name for receiving Botkube alerts.
@@ -152,31 +151,10 @@ communications:
               - k8s-default-tools
             # Notification sources configuration for a given channel.
             sources:
-              - k8s-events
+              - k8s-err-events
+              - k8s-recommendation-events
 
-    # Settings for MS Teams.
-    teams:
-      # If true, enables MS Teams bot.
-      enabled: false
-      # The Bot name set while registering Bot to MS Teams.
-      botName: "Botkube"
-      # The Botkube application ID generated while registering Bot to MS Teams.
-      appID: "APPLICATION_ID"
-      # The Botkube application password generated while registering Bot to MS Teams.
-      appPassword: "APPLICATION_PASSWORD"
-      bindings:
-        # Executor bindings apply to all MS Teams channels where Botkube has access to.
-        executors:
-          - k8s-default-tools
-        # Source bindings apply to all channels which have notification turned on with `@Botkube enable notifications` command.
-        sources:
-          - k8s-events
-      # The path in endpoint URL provided while registering Botkube to MS Teams.
-      messagePath: "/bots/teams"
-      # The Service port for bot endpoint on Botkube container.
-      port: 3978
-
-    # Settings for Discord.
+    ## Settings for Discord.
     discord:
       # If true, enables Discord bot.
       enabled: false
@@ -186,7 +164,7 @@ communications:
       botID: "DISCORD_BOT_ID"
       # Map of configured channels. The property name under `channels` object is an alias for a given configuration.
       #
-      # Format: channels.{alias}
+      ## Format: channels.{alias}
       channels:
         "default":
           # Discord channel ID for receiving Botkube alerts.
@@ -201,9 +179,10 @@ communications:
               - k8s-default-tools
             # Notification sources configuration for a given channel.
             sources:
-              - k8s-events
+              - k8s-err-events
+              - k8s-recommendation-events
 
-    # Settings for Elasticsearch.
+    ## Settings for Elasticsearch.
     elasticsearch:
       # If true, enables Elasticsearch.
       enabled: false
@@ -215,7 +194,7 @@ communications:
         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
+      # The server URL, e.g https://example.com:9243
       server: "ELASTICSEARCH_ADDRESS"
       # Basic Auth username.
       username: "ELASTICSEARCH_USERNAME"
@@ -224,9 +203,17 @@ communications:
       # 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}
+      ## Format: indices.{alias}
       indices:
         "default":
           # Configures Elasticsearch index settings.
@@ -237,18 +224,20 @@ communications:
           bindings:
             # Notification sources configuration for a given index.
             sources:
-              - k8s-events
+              - k8s-err-events
+              - k8s-recommendation-events
 
-    # Settings for Webhook.
+    ## 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.
+        # Notification sources configuration for the webhook.
         sources:
-          - k8s-events
+          - k8s-err-events
+          - k8s-recommendation-events
 ```
 
 The default configuration for Helm chart can be found in [values.yaml](https://github.com/kubeshop/botkube/blob/main/helm/botkube/values.yaml).
diff --git a/docs/configuration/executor/assets/flux-rbac.png b/docs/configuration/executor/assets/flux-rbac.png