diff --git a/docs/configuration/executor/flux.md b/docs/configuration/executor/flux.md new file mode 100644 index 00000000..7d96e7d6 --- /dev/null +++ b/docs/configuration/executor/flux.md @@ -0,0 +1,56 @@ +--- +id: flux +title: Flux +sidebar_position: 6 +--- + +The Botkube Flux executor plugin allows you to run the [`flux`](https://fluxcd.io/) CLI commands directly within the chat window of your chosen communication platform. + +The Flux plugin is hosted in the official Botkube plugin repository. To enable the Flux plugin, ensure that the `botkube` repository is defined under `plugins` in the [values.yaml](https://github.com/kubeshop/botkube/blob/main/helm/botkube/values.yaml) file. + +```yaml +plugins: + repositories: + botkube: + url: https://github.com/kubeshop/botkube/releases/download/v1.3.0/plugins-index.yaml +``` + +## Enabling plugin + +To enable the GitHub plugin, add the following flag to the Botkube [`install` command](../../cli/commands/botkube_install.md): + +```sh +--set 'executors.flux.botkube/flux.enabled'=true +``` + +The Flux plugin comes with integrated GitHub support. To enable it, you'll need a valid [GitHub token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token). Set the token using the following command: + +```sh +--set 'executors.flux.botkube/flux.config.github.auth.accessToken=' +``` + +By default, the Flux plugin has read-only access. To perform actions like creating or deleting Flux-related sources, you'll need to customize the [RBAC](../rbac.md#configuration). + +## Plugin Configuration Syntax + +```yaml +# Map of executors. The `executors` property name is an alias for a given configuration. +# Key name is used as a binding reference. +# +# Format: executors.{alias} +executors: + flux: + botkube/flux: + enabled: false + config: + github: + auth: + # GitHub access token. + # Instructions for token creation: https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/#creating-a-token. + # Lack of token may limit functionality, e.g., adding comments to pull requests or approving them. + accessToken: "" + log: + level: "info" +``` + +For the default Helm chart configuration, refer to the [values.yaml](https://github.com/kubeshop/botkube/blob/main/helm/botkube/values.yaml) file. diff --git a/docs/usage/executor/assets/flux-diff.gif b/docs/usage/executor/assets/flux-diff.gif new file mode 100644 index 00000000..6ffc20bd Binary files /dev/null and b/docs/usage/executor/assets/flux-diff.gif differ diff --git a/docs/usage/executor/assets/flux-interactivity.gif b/docs/usage/executor/assets/flux-interactivity.gif new file mode 100644 index 00000000..083a6bff Binary files /dev/null and b/docs/usage/executor/assets/flux-interactivity.gif differ diff --git a/docs/usage/executor/flux.md b/docs/usage/executor/flux.md new file mode 100644 index 00000000..e29ca0c1 --- /dev/null +++ b/docs/usage/executor/flux.md @@ -0,0 +1,89 @@ +--- +id: flux +title: "Flux" +sidebar_position: 5 +--- + +Botkube offers seamless execution of Flux CLI commands within your Kubernetes cluster. By default, Flux command execution is disabled. To enable it, refer to the [**Enabling plugin**](../../configuration/executor/flux.md#enabling-plugin) section. + +To execute the `flux` CLI commands, send a message in the channel where Botkube is present. For example: + +``` +@Botkube flux tutorial +``` + +## Interactive Usage + +We have also incorporated interactivity (tables, etc.) to simplify running Flux CLI commands e.g. from mobile devices. + +![flux-interactivity](../assets/flux-interactivity.gif) + +## Simplified Kustomization Diffing Flow + +With the Botkube Flux executor, you can execute a single command to perform a diff between a specific pull request and the cluster state. For instance: + +``` +@BotKube flux diff kustomization podinfo --path ./kustomize --github-ref [PR Number| URL | Branch] +``` + +![flux-diff](./assets/flux-diff.gif) + +This command automates several tasks: + +- Automatically discovering the associated GitHub repository for the given kustomization. +- Cloning the repository. +- Checking out a given pull request. +- Comparing pull request changes with the current cluster state. +- Sharing the diff report. + +The diff results are posted on the Slack channel, making it easy for team members to review and discuss the changes. Additionally, the returned message provides additional contextual actions: + +- Posting the diff report as a GitHub comment on the corresponding pull request. +- Approving the pull request. +- Viewing the pull request. + +### Prerequisite + +Before running the `flux diff` command, you need to update the Flux plugin RBAC configuration. This is necessary because the command performs a server-side dry run that requires patch permissions, as specified in the [Kubernetes documentation](https://kubernetes.io/docs/reference/using-api/api-concepts/#dry-run-authorization). + +Here's an example RBAC configuration: + +```yaml +executors: + flux: + botkube/flux: + enabled: true + config: + github: + auth: + accessToken: "ghp_" + + context: + rbac: + group: + type: Static + static: + values: ["flux-read-patch"] + +extraObjects: + - apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRole + metadata: + name: flux-read-patch + rules: + - apiGroups: ["*"] + resources: ["*"] + verbs: ["get", "watch", "list", "patch"] + - apiVersion: rbac.authorization.k8s.io/v1 + kind: ClusterRoleBinding + metadata: + name: flux-read-patch + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: flux-read-patch + subjects: + - kind: Group + name: flux-read-patch + apiGroup: rbac.authorization.k8s.io +```