Update configuration related docs (#102)

kubeshop · Jul 21, 2022 · 90394aa · 90394aa
1 parent c104368
commit 90394aa
Show file tree

Hide file tree

Showing 14 changed files with 282 additions and 192 deletions.
diff --git a/content/configuration/_index.md b/content/configuration/_index.md
@@ -2,23 +2,120 @@
 title: "Configuration"
 date: 2019-01-08T17:58:08+05:30
 draft: false
-weight: 10
+weight: 20
 ---
 
-BotKube backend allows you to specify the [resource](/configuration/resource) and [communication](/configuration/communication) settings. Check the individual documents for more detailed explanation on how to provide those configurations.
+BotKube backend allows you to specify [resource](/configuration/resource), [communication](/configuration/communication), and [global](/configuration/global) settings. Check the related documents for more detailed explanation.
+
+The configuration settings are read from two sources:
+
+- the configuration files specified by the `BOTKUBE_CONFIG_PATHS` environment variable or `--config/-c` flag. For example:
+
+  ```bash
+  export BOTKUBE_CONFIG_PATHS="global.yaml,team-b-specific.yaml"
+  # or
+  ./botkube --config "global.yaml,team-b-specific.yaml"
+  ```
+
+  {{% notice note %}}
+  You can split individual settings into multiple configuration files. The priority will be given to the last (right-most) file specified. See the [merging strategy](#merging-strategy) section for more details.
+  {{% /notice%}}
+
+- the exported [environment variables](#environment-variables) that overrides the configuration specified in the files.
 
 
 ### Updating the configuration at runtime
 
 You can update the configuration and use `helm upgrade` to update configuration values for the BotKube.
 
-You can also change resource configuration directly in ConfigMap - which is not recommended but is great for quick experimentation.
+You can also change configuration directly in ConfigMap and Secret - is not recommended but is great for quick experimentation.
+
+```bash
+# Change resources related settings
+kubectl edit configmap botkube-global-config -n botkube
+```
 
 ```bash
-$ kubectl edit configmap botkube-configmap -n botkube
+# Change communication related settings
+kubectl edit secret botkube-communication-secret -n botkube
 ```
+
 This command opens ConfigMap `specs` in default editor. Do the required changes, save and exit. The BotKube Pod will automatically restart to have these configurations in effect.
 
 ## Helm install options
 
 Advanced Helm install options are documented [here](/configuration/helm-chart-parameters).
+
+## Environment variables
+
+The individual communication settings can be specified via environment variables. They take priority and override the configuration specified in the file.
+
+To construct the environment variable name, take any property from the configuration file and make it uppercase. Use the underscore for properties that are nested. Use the double underscore for all camelCase properties. Finally, add the `BOTKUBE_` prefix.
+
+For example, such configuration property from YAML:
+
+```yaml
+settings:
+  kubectl:
+    defaultNamespace: 'NAMESPACE'
+```
+
+is mapped to the `BOTKUBE_SETTINGS_KUBECTL_DEFAULT__NAMESPACE` environment variable.
+
+This is a useful feature that allows you to store the overall configuration in a file, where sensitive data, such as tokens, can be put in environment variables. See the [**Tokens from Vault via CSI driver**](/configuration/communication/vault-csi/) tutorial for an example use-case.
+
+## Merging strategy
+
+BotKube allows you to split individual settings into multiple configuration files. The following rules apply:
+- The priority will be given to the last (right-most) file specified.
+- Objects are merged together and primitive fields are overridden. For example:
+  ```yaml
+  # a.yaml - first file
+  settings:
+    clusterName: dev-cluster
+    configWatcher: true
+    kubectl:
+      enabled: false
+  ```
+  ```yaml
+  # b.yaml - second file
+  settings:
+    kubectl:
+      enabled: true
+  ```
+
+  ```yaml
+  # result
+  settings:
+    clusterName: dev-cluster
+    configWatcher: true
+    kubectl:
+      enabled: true
+  ```
+
+- The arrays items are not merged, they are overridden. For example:
+
+  ```yaml
+  # a.yaml
+  settings:
+    kubectl:
+      enabled: true
+      commands:
+        verbs: ["api-resources", "api-versions", "cluster-info", "describe", "diff", "explain", "get", "logs", "top", "auth"]
+  ```
+  ```yaml
+  # b.yaml
+  settings:
+    kubectl:
+      commands:
+        verbs: ["get", "logs", "top", "auth"]
+  ```
+
+  ```yaml
+  # b.yaml
+  settings:
+    kubectl:
+      enabled: true
+      commands:
+        verbs: ["get", "logs", "top", "auth"]
+  ```
diff --git a/content/configuration/communication/_index.md b/content/configuration/communication/_index.md
@@ -1,21 +1,15 @@
 ---
 menutitle: "Communication"
 title: "Communication"
-weight: 30
+weight: 10
 ---
 
-BotKube backend reads communication settings from two sources:
-- the [comm_config.yaml](#file-syntax) file placed in the directory specified by the **CONFIG_PATH** environment variable,
-- the exported [environment variables](#environment-variables). They take priority and override the configuration specified in the file.
+The communication settings contains:
 
+- Communication platforms configuration,
+- Option to toggle notification type to short or long.
 
-## File syntax
-
-The communication configuration file contains:
-
-- communication platforms configuration,
-
-- option to toggle notification type to short or long.
+## Syntax
 
 ```yaml
 # Communication mediums configuration
@@ -28,9 +22,9 @@ communications:
                                         # want to receive notifications in
     token: 'SLACK_API_TOKEN'            # Slack token received after installing
                                         # BotKube Slack app to a workplace
-    notiftype: short                    # Change notification type short/long.
-                                        # notiftype is optional and default
-                                        # notification type is short (if not specified)
+    notification:
+      type: short                       # Change notification type short/long.
+                                        # Type is optional and default is short.
 
   # Settings for Mattermost
   mattermost:
@@ -40,25 +34,29 @@ communications:
     token: 'MATTERMOST_TOKEN'           # Personal Access token generated by BotKube user
     team: 'MATTERMOST_TEAM'             # Mattermost Team to configure with BotKube
     channel: 'MATTERMOST_CHANNEL'       # Mattermost Channel for receiving BotKube alerts
-    notiftype: short                    # Change notification type short/long you want to receive.
-                                        # notiftype is optional and default notification type is short (if not specified)
+    notification:
+      type: short                       # Change notification type short/long.
+                                        # Type is optional and default is short.
 
   # Settings for Microsoft Teams
   teams:
     enabled: false
     appID: 'APPLICATION_ID'
     appPassword: 'APPLICATION_PASSWORD'
     port: 3978
-    notiftype: short                    # Change notification type short/long you want to receive.
-                                        # notiftype is optional and default notification type is short (if not specified)
+    notification:
+      type: short                       # Change notification type short/long.
+                                        # Type is optional and default is short.
 
   # Settings for Discord
   discord:
     enabled: false
     token: 'DISCORD_TOKEN'	            # BotKube Bot Token
-    botid: 'DISCORD_BOT_ID'             # BotKube Application Client ID
+    botID: 'DISCORD_BOT_ID'             # BotKube Application Client ID
     channel: 'DISCORD_CHANNEL_ID'       # Discord Channel id for receiving BotKube alerts
-    notiftype: short                    # Change notification type short/long you want to receive. notiftype is optional and Default notification type is short (if not specified)
+    notification:
+      type: short                       # Change notification type short/long.
+                                        # Type is optional and default is short.
 
   # Settings for ELS
   elasticsearch:
@@ -90,20 +88,3 @@ communications:
 ```
 
 The default configuration for Helm chart can be found in [values.yaml](https://github.com/kubeshop/botkube/blob/main/helm/botkube/values.yaml).
-
-## Environment variables
-
-The individual communication settings can be specified via environment variables. They take priority and override the configuration specified in the file.
-
-
-To construct the environment variable name, take any property from the [configuration file](#file-syntax) and make it uppercase. Use the underscore for properties that are nested. That's all - you have the environment variable name!
-
-For example, such configuration property from YAML:
-```yaml
-communications:
-  slack:
-    token: 'SLACK_API_TOKEN'
-```
-is mapped to the `COMMUNICATIONS_SLACK_TOKEN` environment variable.
-
-This is a useful feature that allows you to store the overall configuration in a file, where sensitive data, such as tokens, can be put in environment variables. See the [**Tokens from Vault via CSI driver**](/configuration/communication/vault-csi/) tutorial for an example use-case.
diff --git a/content/configuration/global.md b/content/configuration/global.md
@@ -0,0 +1,42 @@
+---
+title: "Global"
+date: 2022-07-20T13:28:06+02:00
+draft: false
+weight: 21
+---
+
+The global settings contains:
+
+- Toggle `kubectl` command execution,
+- Configure `kubectl` commands BotKube can execute,
+- Restrict `kubectl` command execute to specific channel.
+
+## Syntax
+
+```yaml
+
+# Cluster Setting to manage command execution access
+settings:
+  # Set cluster name to differentiate incoming messages
+  clusterName: not-configured
+  # Kubectl executor configs
+  kubectl:
+    # Set true to enable kubectl commands execution
+    enabled: false
+    # List of allowed commands
+    commands:
+      # kubectl method which are allowed with BotKube command
+      verbs: ["api-resources", "api-versions", "cluster-info", "describe", "diff", "explain", "get", "logs", "top", "auth"]
+      # resources on which kubectl methods are allowed with BotKube commands
+      resources: ["deployments", "pods" , "namespaces", "daemonsets", "statefulsets", "storageclasses", "nodes"]
+    # set Namespace to execute botkube kubectl commands by default
+    defaultNamespace: default
+    # Set true to enable commands execution from configured channel only
+    restrictAccess: false
+  # Set true to enable config watcher
+  configWatcher: true
+  # Set false to disable upgrade notification
+  upgradeNotifier: true
+```
+
+The default configuration for Helm chart can be found in [values.yaml](https://github.com/kubeshop/botkube/blob/main/helm/botkube/values.yaml).