docs: wip

deploy/charts/burrito/values.yaml

@@ -255,6 +255,10 @@ datastore:
     labels:
       app.kubernetes.io/component: datastore
       app.kubernetes.io/name: burrito-datastore
+  serviceAccount:
+    metadata:
+      annotations: {}
+      labels: {}
   deployment:
     podAnnotations:
       kubectl.kubernetes.io/default-container: burrito

docs/getting-started.md

@@ -3,37 +3,40 @@
 ## Pre-requisites
 
 - A kubernetes cluster
-- A bucket in a cloud provider (AWS, GCP, Azure)
-- cert-manager installed in your cluster (Will only be used for internal communications using a private CA)
+- [Optionnal for testing, necessary for production use] A storage bucket in a cloud provider (AWS, GCP, Azure)
+- [Optionnal, recommended for production use] cert-manager installed in your cluster (for internal encryption of plans and logs & provider cache)
 
 ## Requirements
 
-- Installed [helm](https://helm.sh/docs/intro/install/) command-line tool.
-- Have a [kubeconfig](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) file (default location is `~/.kube/config`).
-- Complete access for burrito to the bucket where logs and plans will be stored.
+- [helm](https://helm.sh/docs/intro/install/) CLI
+- Have a [kubeconfig](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) file (default location is `~/.kube/config`) to access your Kubernetes cluster
 
 ## 1. Install burrito
 
 Copy and modify the [default values](https://github.com/padok-team/burrito/blob/main/deploy/charts/burrito/values.yaml) to match your requirements.
 
+Make sure to configure a tenant by updating the `tenant` field in the `values.yaml` file. The associated namespace will be created automatically and used to deploy Burrito resources on step 3.
+
+!!! info
+    To try Burrito without setting up a local storage, set the `config.burrito.datastore.storage.mock` field to `true` in the `values.yaml` file. To persist data such as terraform logs, you must configure a storage bucket field. Make sure to specify a service account that has the necessary permissions to read/write to your remote bucket.
+
+Then, install Burrito using the following command:
+
 ```bash
 helm install burrito oci://ghcr.io/padok-team/charts/burrito -n burrito-system -f ./values.yaml
 ```
 
-This will create a new namespace, `burrito-system`, where burrito services will live.
-
-!!! warning
-    The installation manifests include `ClusterRoleBinding` resources that reference `burrito-system` namespace. If you are installing burrito into a different namespace then make sure to update the namespace reference.
+This will create a new namespace, `burrito-system`, where burrito services will be deployed.
 
 ## 2. Create a connection to a private repository
 
-Create a Kubernetes `Secret` which looks like:
+Create a Kubernetes `Secret` to reference the necessary credentials to clone your IaC repository (github or gitlab)
 
 ```yaml
 kind: Secret
 metadata:
   name: burrito-repo
-  namespace: burrito
+  namespace: <tenant-namespace>
 type: Opaque
 stringData:
   username: <my-username>
@@ -51,15 +54,15 @@ apiVersion: config.terraform.padok.cloud/v1alpha1
 kind: TerraformRepository
 metadata:
   name: burrito
-  namespace: burrito
+  namespace: <tenant-namespace>
 spec:
   repository:
-    url: <https_or_ssh_repository_url>
+    url: <https-or-ssh-repository-url>
     secretName: burrito-repo
 ```
 
 !!! info
-    You can also connect to a public repository by omitting `spec.repository.secretName` in your `TerraformRepository` definition.
+You can also connect to a public repository by omitting `spec.repository.secretName` in your `TerraformRepository` definition.
 
 ## 3. Synchronize a terraform layer
 
@@ -80,3 +83,10 @@ spec:
     name: burrito
     namespace: burrito
 ```
+
+The controller will create a runner pod in your tenant namespace to synchronize the repository and apply the terraform code.
+
+## Guides
+
+- For detailed guides on how to use Burrito, see the [Guides](./guides/index.md) section.
+- To learn more about advanced configuration and features, see the [Operator Manual](./operator-manual/index.md) section.

docs/getting-started/iac-drift-detection.md → docs/guides/iac-drift-detection.md

@@ -7,16 +7,15 @@ Burrito continuously plans your Terraform code by launching runner pods that wil
 
 Follow the steps below to set up Burrito on a local cluster and start planning your Terraform code automatically.
 
-### Set up a local cluster
+### Requirements
 
-1. Install [kind](https://kind.sigs.k8s.io/docs/user/quick-start/), [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) and [helm](https://helm.sh/docs/intro/install/).
-2. Create a new kind cluster:
+- A Kubernetes cluster (you can use [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) for a local cluster)
+- [Helm](https://helm.sh/docs/intro/install/) CLI
+- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) CLI
 
-```bash
-kind create cluster
-```
+### Install Burrito
 
-3. Install Burrito with Helm as described in the [installation guide](../installation/with-helm.md).
+Install Burrito with Helm as described in the [installation guide](../installation/with-helm.md), using the provided values file.
 
 ```bash
 helm upgrade --install burrito oci://ghcr.io/padok-team/charts/burrito -n burrito-system -f https://raw.githubusercontent.com/padok-team/burrito/main/docs/examples/values-simple.yaml

docs/getting-started/index.md → docs/guides/index.md

@@ -1,6 +1,6 @@
 # Getting started
 
-Follow the 3 steps below to get started with Burrito:
+Follow the 3 guides below to understand how to use Burrito: 
 
 - [IaC Drift detection](./iac-drift-detection.md): Quickly set up Burrito and start monitoring Terraform state drift.
 - [PR/MR plan/apply Workflow](./pr-mr-workflow.md): Configure Burrito to automatically plan and apply Terraform code on PR/MR.

docs/guides/pr-mr-workflow.md

@@ -0,0 +1,99 @@
+# PR/MR workflow
+
+Now that you have set up Burrito and planned your Terraform code automatically, you can configure a PR/MR workflow to never have to use the `terraform apply` command ever again.
+
+## Pre-requisites
+
+- You have set up Burrito on a cluster.
+- You set up TerraformRepository and TerraformLayer resources to plan your Terraform code automatically.
+
+### Setup a webhook and GitHub app for your repository
+
+To trigger the Burrito plan and apply workflow, you need to set up a webhook from your repository to your Burrito instance.
+Fork the [burrito-examples](https://github.com/padok-team/burrito-examples) repository and update the `TerraformRepository` resource to point to your forked repository.
+
+```yaml
+apiVersion: config.terraform.padok.cloud/v1alpha1
+kind: TerraformRepository
+metadata:
+  name: my-repository
+  namespace: burrito-project
+spec:
+  repository:
+    url: https://github.com/<your-github-handle>/burrito-examples
+```
+
+You will also need to setup a [GitHub App](https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps) to allow Burrito to comment on your PRs/MRs. Follow the instructions in the [PR/MR workflow](../operator-manual/pr-mr-workflow.md#configuration) section of the operator manual to set up the GitHub app.
+Make sure that you updated the Burrito values file to include the GitHub app ID, installation ID, and private key to the Burrito controller deployment.
+
+!!! info
+    Your controller deployment should now have the following environment variables:  
+    - `BURRITO_CONTROLLER_GITHUBCONFIG_APPID`: The App ID of your GitHub app.  
+    - `BURRITO_CONTROLLER_GITHUBCONFIG_INSTALLATIONID`: The Installation ID of your GitHub app.  
+    - `BURRITO_CONTROLLER_GITHUBCONFIG_PRIVATEKEY`: The private key of your GitHub app.  
+
+!!! note
+    You can also use a personal access token instead of a GitHub app. Your GitHub account will be used to comment on the PRs/MRs.
+    The environment variable to set is `BURRITO_CONTROLLER_GITHUBCONFIG_APITOKEN`
+
+Now let's configure the GitHub webhook. Expose the `burrito-server` kubernetes service to the internet using the method of your choice. (for testing purposes on a local cluster, you can use `kubectl port-forward` and [ngrok](https://ngrok.com/) to expose the service to the internet).
+
+Configure a webhook in your GitHub repository to point to the exposed `burrito-server` service. **Make sure to specify the `/api/webhook` path in the target url.** The webhook should be triggered on `push` and `pull_request` events. You can reference your webhook secret in a secret named `burrito-webhook-secret` in the controller namespace (`burrito-system` in this tutorial).
+
+```yaml
+kind: Secret
+metadata:
+  name: burrito-webhook-secret
+  namespace: burrito
+type: Opaque
+stringData:
+  burrito-webhook-secret: <my-webhook-secret>
+```
+
+You can also directly add the webhook secret as an environment variable of the `burrito-server` deployment. The variable name depends on your git provider. For GitHub, the environment variable is `BURRITO_SERVER_WEBHOOK_GITHUB_SECRET`.
+
+### Experiment with the PR/MR workflow
+
+Now that you have set up the webhook and GitHub app, you can experiment with the PR/MR workflow.
+Create a new branch in your forked repository and make some changes to the Terraform code. Push the changes to the branch and open a PR/MR against the main branch.
+
+A new TerraformPullRequest resource should be created in your tenant namespace. You can check the status of the resource by running:
+
+```bash
+kubectl get pr -n burrito-project
+```
+
+Output:
+
+```bash
+NAME              ID    STATE   PROVIDER   BASE   BRANCH
+my-repository-1   1     Idle    github     main   update-tf-code
+```
+
+A new TerraformLayer resource should also be created to plan the Terraform code. You can check the status of the resource by running:
+
+```bash
+kubectl get tfl -n burrito-project
+```
+
+Output:
+
+```bash
+NAME                  STATE         REPOSITORY      BRANCH           PATH        LAST RESULT
+my-layer              ApplyNeeded   my-repository   main             terraform   Plan: 3 to create, 0 to update, 0 to delete
+my-layer-pr-1-rxvrt   ApplyNeeded   my-repository   update-tf-code   terraform   Plan: 2 to create, 0 to update, 0 to delete
+```
+
+The Burrito server should have commented on the PR/MR with the plan output. You can check the comments on the PR/MR to see the plan output.
+
+![Pul request comment demo](../assets/demo/pr-demo.png)
+
+Set the `autoApply` field to `true` in the TerraformLayer resource to automatically apply the Terraform code upon merging the PR/MR.
+
+### Conclusion
+
+You have now set up a PR/MR workflow with Burrito to automatically plan and apply your Terraform code. You can now focus on writing Terraform code and let Burrito handle the rest.
+
+### Next steps
+
+- [Navigate the Burrito UI](../guides/ui.md) to see the status of the Terraform resources.

docs/index.md

@@ -4,6 +4,7 @@ This is the home of the Burrito documentation. Here you will find all the inform
 
 - [Overview](./overview.md) helps you understand what Burrito is all about.
 - [Getting Started](./getting-started.md) is a step-by-step guide to help you get started with Burrito.
+- [Guides](./guides/index.md) provides detailed tutorials to help you understand how to use Burrito.
 - [Operator Manual](./operator-manual/) is a detailed guide to help you understand how to install and configure Burrito.
 - [User Guide](./user-guide/) is a detailed guide to help you understand how to setup and use Burrito resources.
 - [Reference](./reference/) provides detailed information about the Burrito CRDs and their specifications.

docs/operator-manual/datastore.md

@@ -9,21 +9,25 @@ config:
   burrito:
     datastore:
       storage:
+        mock: <false|true> # default: false
         s3:
-          bucket: XXX
+          bucket: <bucket-name>
         gcs:
-          bucket: XXX
+          bucket: <bucket-name>
         azure:
-          storageAccount: XXX
-          container: XXX
+          storageAccount: <storage-account>
+          container: <container-name>
 ```
 
 !!! info
     Only one storage backend can be configured at a time.
 
+!!! warning
+    The `mock` storage backend is only for testing purposes and should not be used in production. If enabled, Burrito will store the data in memory and will lose it when the pod is restarted. It also might fill up the memory of the pod if too much data is stored.
+
 ## Authentication
 
-The different cloud provider implementations rely on the default credentials chain of the cloud provider SDKs.
+The different cloud provider implementations rely on the default credentials chain of the cloud provider SDKs. Use annotations and labels on the Burrito resources to specify the credentials to use.
 
 ## Authorization
 

docs/operator-manual/git-webhook.md

@@ -1,14 +1,29 @@
 # Setup a Git Webhook
 
-Create a webhook (with a secret!) in the repository you want to receive events from.
+## Expose Burrito server to the internet
 
-Then create a secret:
+Expose the `burrito-server` service to the internet using the method of your choice. (e.g. ingress, port-forward & ngrok for local testing...). Accessing the URL on the browser should display the Burrito UI.
 
+## Configure a webhook on GitHub or GitLab
+
+Create a webhook (with a secret!) in the repository you want to receive events from.  
+The target URL must point to the exposed `burrito-server` on the `/api/webhook` path.
+
+GitHub triggers:  
+The webhook should be triggered on `push` and `pull_request` events.
+
+GitLab triggers:  
+The webhook should be triggered on `Push events` from all branches and `Merge request events`.
+
+## Reference the webhook secret in the controller
+
+Create a secret called `burrito-webhook-secret` in the controller namespace with the webhook secret.
 ```yaml
 kind: Secret
+apiVersion: v1
 metadata:
   name: burrito-webhook-secret
-  namespace: burrito
+  namespace: burrito-system
 type: Opaque
 stringData:
   burrito-webhook-secret: <my-webhook-secret>

docs/operator-manual/pr-mr-workflow.md

@@ -45,6 +45,13 @@ With those 3 conditions, we defined 3 states:
 
 ## Configuration
 
+### Webhook
+
+Follow the instructions in [Setting up a Git Webhook](./git-webhook.md) to configure a webhook in your repository.
+The webhook will be used to trigger:
+- Drift detection when a push event is received.
+- The PR/MR workflow when a pull request event is received.
+
 ### GitHub with a dedicated GitHub App
 
 #### Create the GitHub App

docs/overview.md

@@ -47,7 +47,7 @@ Burrito is compatible with:
 
 ## Getting started
 
-Follow our [getting started guide](./getting-started.md) to quickly set up Burrito and start monitoring Terraform state drift.
-
-Deep dive into the [operator manual](./operator-manual/) to setup all the features of Burrito.
-Use the [user guide](./user-guide/) to understand how to setup and configure Burrito resources.
+- Follow the [getting started section](./getting-started.md) to quickly set up Burrito and start monitoring Terraform state drift.  
+- Follow the [guides](./guides/index.md) for detailed tutorials on how to use Burrito.  
+- Deep dive into the [operator manual](./operator-manual/) to setup advanced configurations and features.
+- Use the [user guide](./user-guide/) to learn how to configure Burrito resources according to your needs.

docs/reference/index.md

@@ -0,0 +1 @@
+# Reference index

mkdocs.yml

@@ -14,11 +14,12 @@ markdown_extensions:
 nav:
 - Home: index.md
 - Overview: overview.md
-- Getting Started:
-  - getting-started/index.md
-  - IaC Drift Detection: getting-started/iac-drift-detection.md
-  - PR/MR Workflow: getting-started/pr-mr-workflow.md
-  - UI Overview: getting-started/ui.md
+- Getting started: getting-started.md
+- Guides:
+  - guides/index.md
+  - IaC Drift Detection: guides/iac-drift-detection.md
+  - PR/MR Workflow: guides/pr-mr-workflow.md
+  - UI Overview: guides/ui.md
 - Installation:
   - Install with Helm (recommended): installation/with-helm.md
   - Install with static manifests: installation/with-static-manifests.md
@@ -39,6 +40,7 @@ nav:
   - user-guide/private-modules.md
   - user-guide/additionnal-trigger-path.md
 - Reference:
+  - reference/index.md
   - reference/api.md
   - reference/crds.md
 - FAQ: faq.md