docs: reorganize (#309)

* docs: reorganize

* docs: add new tutorials

* docs: hide incomplete documentation

---------

Co-authored-by: Lucas Marques <lucas.marques@theodo.com>

deploy/charts/burrito/values.yaml

@@ -344,6 +344,10 @@ datastore:
     labels:
       app.kubernetes.io/component: datastore
       app.kubernetes.io/name: burrito-datastore
+  serviceAccount:
+    metadata:
+      annotations: {}
+      labels: {}
   deployment:
     # -- Annotations to be added to the pods generated by the Burrito datastore deployment
     podAnnotations:

docs/contributing.md

@@ -0,0 +1 @@
+# TODO - contributing.md

docs/examples/terraform-layer.yaml

@@ -0,0 +1,15 @@
+apiVersion: config.terraform.padok.cloud/v1alpha1
+kind: TerraformLayer
+metadata:
+  name: my-layer
+  namespace: burrito-project
+spec:
+  branch: main
+  path: terraform
+  remediationStrategy:
+    autoApply: false
+  repository:
+    name: my-repository
+    namespace: burrito-project
+  terraform:
+    version: 1.3.1

docs/examples/terraform-repository.yaml

@@ -0,0 +1,8 @@
+apiVersion: config.terraform.padok.cloud/v1alpha1
+kind: TerraformRepository
+metadata:
+  name: my-repository
+  namespace: burrito-project
+spec:
+  repository:
+    url: https://github.com/padok-team/burrito-examples

docs/examples/values-simple.yaml

@@ -0,0 +1,17 @@
+config:
+  burrito:
+    controller:
+      timers:
+        driftDetection: 10m # run drift detection every 10 minutes
+        onError: 10s # wait 10 seconds before retrying on error
+        waitAction: 1m # wait 1 minute before retrying on locked layer
+        failureGracePeriod: 30s # set a grace period of 30 seconds before retrying on failure (increases exponentially with the amount of failed retries)
+    datastore:
+      storage:
+        mock: true # use a mock storage for the datastore (useful for testing, not recommended for production)
+tenants:
+  - namespace:
+      create: true
+      name: "burrito-project"
+    serviceAccounts:
+    - name: burrito-runner

docs/faq.md

@@ -0,0 +1 @@
+# TODO - FAQ

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/guides/iac-drift-detection.md

@@ -0,0 +1,175 @@
+# Burrito Drift Detection
+
+Drift detection is the core feature of Burrito. It allows you to monitor the drift between your Terraform state and your infrastructure in real-time.
+Burrito continuously plans your Terraform code by launching runner pods that will download the Terraform code, plan it, and store the result in its datastore.
+
+## Exercise
+
+Follow the steps below to set up Burrito on a local cluster and start planning your Terraform code automatically.
+
+### Requirements
+
+- 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
+
+### Install Burrito
+
+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
+```
+
+With this command, you installed burrito with the following configuration:
+
+```yaml
+config:
+  burrito:
+    controller:
+      timers:
+        driftDetection: 10m # run drift detection every 10 minutes
+        onError: 10s # wait 10 seconds before retrying on error
+        waitAction: 1m # wait 1 minute before retrying on locked layer
+        failureGracePeriod: 30s # set a grace period of 30 seconds before retrying on failure (increases exponentially with the amount of failed retries)
+    datastore:
+      storage:
+        mock: true # use a mock storage for the datastore (useful for testing, not recommended for production)
+tenants:
+  - namespace:
+      create: true
+      name: "burrito-project"
+```
+
+Burrito should be up and running in the `burrito-system` namespace.
+
+```bash
+kubectl get pods -n burrito-system
+```
+
+Output:
+```
+NAME                                   READY   STATUS    RESTARTS   AGE
+burrito-controllers-6945797c5d-kjfl2   1/1     Running   0          2m00s
+burrito-datastore-94d999f54-kbg9z      1/1     Running   0          2m00s
+burrito-server-764f75766b-qw5nx        1/1     Running   0          2m00s
+```
+
+### Connect Burrito to Terraform code on GitHub
+
+You will use the [example Terraform code](https://github.com/padok-team/burrito-examples) that we have prepared for you.
+This repository contains simple Terraform and Terragrunt with local random-pets resources that you can use to test Burrito.
+
+Create a TerraformRepository resource in the `burrito-system` namespace:
+
+```bash
+kubectl apply -f https://raw.githubusercontent.com/padok-team/burrito/main/docs/examples/terraform-repository.yaml
+```
+
+Here is the content of the `TerraformRepository` resource that you have created
+
+```yaml
+apiVersion: config.terraform.padok.cloud/v1alpha1
+kind: TerraformRepository
+metadata:
+  name: my-repo
+  namespace: burrito-project
+spec:
+  repository:
+    url: git@github.com:padok-team/burrito-examples.git
+```
+
+Create a `TerraformLayer` resource in the `burrito-system` namespace, referencing the `TerraformRepository` you just created. For now, the autoApply is set to false, so the layer will only plan the Terraform code and not apply it.
+
+```bash
+kubectl apply -f https://raw.githubusercontent.com/padok-team/burrito/main/docs/examples/terraform-layer.yaml
+```
+
+```yaml
+apiVersion: config.terraform.padok.cloud/v1alpha1
+kind: TerraformLayer
+metadata:
+  name: my-layer
+  namespace: burrito-project
+spec:
+  branch: main
+  path: terraform
+  remediationStrategy:
+    autoApply: false
+  repository:
+    name: my-repository
+    namespace: burrito-project
+  terraform:
+    version: 1.3.1
+```
+
+Check that your Terraform code is being planned by Burrito:
+
+```bash
+kubectl get pods -n burrito-project
+```
+
+Output:
+
+```bash
+NAME                   READY   STATUS      RESTARTS   AGE
+my-layer-apply-xntrg   0/1     Completed   0          82s
+```
+
+The `TerraformLayer` should have been updated with the result of the plan. You can check the status of the `TerraformLayer` directly by querying the `TerraformLayer` resource, or by checking the burrito UI.
+
+```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
+```
+
+```bash
+kubectl port-forward svc/burrito-server -n burrito-system 8080:80
+```
+
+![Burrito drift example](../assets/demo/drift-example.png)
+
+Activate the autoApply feature by updating the `TerraformLayer` resource:
+
+```bash
+kubectl patch tfl my-layer -n burrito-project --type merge --patch '{"spec":{"remediationStrategy":{"autoApply":true}}}'
+```
+
+Check that the Terraform code was applied:
+
+```bash
+kubectl get pods -n burrito-project
+```
+
+Output:
+
+```bash
+NAME                   READY   STATUS      RESTARTS   AGE
+my-layer-apply-bxlcr   0/1     Completed   0          54s
+my-layer-plan-jv86k    0/1     Completed   0          7m22s
+```
+
+```bash
+kubectl get tfl -n burrito-project
+```
+
+Output:
+
+```bash
+NAME       STATE   REPOSITORY      BRANCH   PATH        LAST RESULT
+my-layer   Idle    my-repository   main     terraform   Apply Successful
+```
+
+### Conclusion
+
+You have successfully set up Burrito on a local cluster and planned your Terraform code automatically. You can now monitor the drift between your Terraform state and your infrastructure in real-time.
+
+## Next steps
+
+- Learn how to [configure a PR/MR workflow](../pr-mr-workflow.md)

docs/guides/index.md

@@ -0,0 +1,7 @@
+# Getting started
+
+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.
+- [UI Overview](./ui-overview.md): Learn how to navigate the Burrito UI.