diff --git a/deploy/charts/burrito/values.yaml b/deploy/charts/burrito/values.yaml index adcff639..78d512eb 100644 --- a/deploy/charts/burrito/values.yaml +++ b/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: diff --git a/docs/.DS_Store b/docs/.DS_Store new file mode 100644 index 00000000..670fe7f2 Binary files /dev/null and b/docs/.DS_Store differ diff --git a/docs/assets/demo/drift-example.png b/docs/assets/demo/drift-example.png new file mode 100644 index 00000000..d2879fe4 Binary files /dev/null and b/docs/assets/demo/drift-example.png differ diff --git a/docs/assets/demo/homepage.png b/docs/assets/demo/homepage.png new file mode 100644 index 00000000..dccf33fd Binary files /dev/null and b/docs/assets/demo/homepage.png differ diff --git a/docs/assets/demo/logs.png b/docs/assets/demo/logs.png new file mode 100644 index 00000000..edc4a690 Binary files /dev/null and b/docs/assets/demo/logs.png differ diff --git a/docs/assets/demo/pr-demo.png b/docs/assets/demo/pr-demo.png new file mode 100644 index 00000000..677bafb5 Binary files /dev/null and b/docs/assets/demo/pr-demo.png differ diff --git a/docs/examples/terraform-layer.yaml b/docs/examples/terraform-layer.yaml new file mode 100644 index 00000000..b3572d1a --- /dev/null +++ b/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 diff --git a/docs/examples/terraform-repository.yaml b/docs/examples/terraform-repository.yaml new file mode 100644 index 00000000..38ca8e86 --- /dev/null +++ b/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 diff --git a/docs/examples/values-simple.yaml b/docs/examples/values-simple.yaml new file mode 100644 index 00000000..1b8a4a30 --- /dev/null +++ b/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 diff --git a/docs/faq.md b/docs/faq.md index b7211b1e..c02c3a81 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -1,26 +1 @@ -# Overview - -## What is burrito? - -**Burrito** is a TACoS (**T**erraform **A**utomation **Co**llaboration **S**oftware) Kubernetes Operator. - -![demo](assets/demo/demo.gif) - -## Why burrito? - -[`terraform`](https://www.terraform.io/) is a tremendous tool to manage your infrastructure in IaC. -However, it lacks built-in solutions for managing [state drift](https://developer.hashicorp.com/terraform/tutorials/state/resource-drift). - -Additionally, configuring a CI/CD pipeline for Terraform can be challenging and often varies depending on the selected tools - -Finally, currently, there is no easy way to navigate your Terraform state to truly understand the modifications it undergoes when running `terraform apply`. - -`burrito` aims to tackle those issues by: - -- Planning continuously your Terraform code and run applies if needed -- Offering an out of the box PR/MR integration so you do not have to write CI/CD pipelines for Terraform ever again -- Showing your state's modifications in a simple Web UI - -## Getting started - -Follow our [getting started guide](./getting-started.md). Further user oriented [documentation](./user-guide/) is provided for additional features. +# TODO - FAQ diff --git a/docs/getting-started.md b/docs/getting-started.md index 8fc759b2..717e0d69 100644 --- a/docs/getting-started.md +++ b/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: type: Opaque stringData: username: @@ -51,15 +54,15 @@ apiVersion: config.terraform.padok.cloud/v1alpha1 kind: TerraformRepository metadata: name: burrito - namespace: burrito + namespace: spec: repository: - url: + 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. diff --git a/docs/getting-started/iac-drift-detection.md b/docs/getting-started/iac-drift-detection.md deleted file mode 100644 index 72cb0261..00000000 --- a/docs/getting-started/iac-drift-detection.md +++ /dev/null @@ -1 +0,0 @@ -# TODO - IAC Drift Detection tutorial diff --git a/docs/getting-started/pr-mr-workflow.md b/docs/getting-started/pr-mr-workflow.md deleted file mode 100644 index 58665e31..00000000 --- a/docs/getting-started/pr-mr-workflow.md +++ /dev/null @@ -1 +0,0 @@ -# TODO - PR/MR plan/apply workflow diff --git a/docs/getting-started/ui.md b/docs/getting-started/ui.md deleted file mode 100644 index 45f0d4f4..00000000 --- a/docs/getting-started/ui.md +++ /dev/null @@ -1 +0,0 @@ -# TODO - UI Overview diff --git a/docs/guides/iac-drift-detection.md b/docs/guides/iac-drift-detection.md new file mode 100644 index 00000000..a931ac9a --- /dev/null +++ b/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) diff --git a/docs/guides/index.md b/docs/guides/index.md new file mode 100644 index 00000000..9a528c4e --- /dev/null +++ b/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. diff --git a/docs/guides/pr-mr-workflow.md b/docs/guides/pr-mr-workflow.md new file mode 100644 index 00000000..0572e95d --- /dev/null +++ b/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//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: +``` + +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. diff --git a/docs/guides/ui.md b/docs/guides/ui.md new file mode 100644 index 00000000..70c5c14c --- /dev/null +++ b/docs/guides/ui.md @@ -0,0 +1,43 @@ +# UI Overview + +The Burrito UI is a web-based interface that allows you to view the state of your Terraform layers and resources, as well as the drift between the desired and actual state of your infrastructure. + +## Pre-requisites + +- A running Burrito installation + +## Accessing the UI + +The Burrito UI is accessible via a web browser. To access the UI, you need to expose the `burrito-server` service locally or on a public URL. + +## Features + +### Homepage + +The homepage displays a list of all the Terraform layers that have been added to Burrito. Each layer is displayed as a card with the following information: + +- Namespace +- Repository +- Branch +- Code path +- Last plan result +- State (Error, Out-of-sync, OK) + +![Homepage](../assets/demo/homepage.png) + +### Terraform / Terragrunt logs + +Click on the layer card to view the Terraform or Terragrunt logs for that layer. You can explore previous runs and view the logs for each run. The maximum number of logs to keep is configurable. +![Logs](../assets/demo/logs.png) + +A dedicated page for exploring the logs is also available. + +### More to come + +Burrito is under active development, and we are working on adding more features to the UI such as: + +- "Plan and apply" buttons +- Notifications +- User management +- Pull request view + ... and more! diff --git a/docs/index.md b/docs/index.md index 5491e461..d62e1714 100644 --- a/docs/index.md +++ b/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. diff --git a/docs/installation/with-helm.md b/docs/installation/with-helm.md new file mode 100644 index 00000000..a5099fdf --- /dev/null +++ b/docs/installation/with-helm.md @@ -0,0 +1,60 @@ +# Install burrito with Helm + +## Requirements + +- Installed [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) command-line tool +- Installed [helm](https://helm.sh/docs/intro/install/) command-line tool **(version v3.8.0 and further)** +- Have access to a Kubernetes cluster + +## 1. Basic installation + +!!! info + Our Helm chart is published in an [OCI-based registry](https://helm.sh/docs/topics/registries/) (ghcr.io). You must use Helm v3.8.0 or above. + +```bash +helm install burrito oci://ghcr.io/padok-team/charts/burrito -n burrito-system --create-namespace +``` + +This will create a new namespace, `burrito-system`, where the burrito core components will live. + +You can change the chart's version with any version available on [our Chart registry](https://github.com/padok-team/burrito/pkgs/container/charts%2Fburrito). + +## 2. Burrito Helm configuration + +The Burrito configuration is managed through Helm values files, which can be overridden at installation time. + +You can find the default values of the Burrito Helm chart by running: + +```bash +helm show values oci://ghcr.io/padok-team/charts/burrito +``` + +The [source code](https://github.com/padok-team/burrito/tree/main/deploy/charts/burrito) and [values file](https://github.com/padok-team/burrito/blob/main/deploy/charts/burrito/values.yaml) of the chart is available on [burrito GitHub repository](https://github.com/padok-team/burrito). + + +Here is an example of a simple burrito Helm values file that you can use to bootstrap your installation: + +```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" + serviceAccounts: + - name: burrito-runner + annotations: + iam.gke.io/gcp-service-account: burrito@company-project.iam.gserviceaccount.com # example: use GKE Workload Identity to have access to GCP infrastructure +``` + +!!! info + Learn more about these values in the chart's [README file](https://github.com/padok-team/burrito/tree/main/deploy/charts/burrito/README.md) and [Multi-tenant architecture](../operator-manual/multi-tenant-architecture.md). diff --git a/docs/operator-manual/install/with-static-manifests.md b/docs/installation/with-static-manifests.md similarity index 100% rename from docs/operator-manual/install/with-static-manifests.md rename to docs/installation/with-static-manifests.md diff --git a/docs/operator-manual/datastore.md b/docs/operator-manual/datastore.md index 8e9f95b8..559aece9 100644 --- a/docs/operator-manual/datastore.md +++ b/docs/operator-manual/datastore.md @@ -9,21 +9,25 @@ config: burrito: datastore: storage: + mock: # default: false s3: - bucket: XXX + bucket: gcs: - bucket: XXX + bucket: azure: - storageAccount: XXX - container: XXX + storageAccount: + container: ``` !!! 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 service account associated to the datastore by updating the `datastore.serviceAccount.metadata` field to specify the credentials to use. (e.g. `iam.amazonaws.com/role` for AWS) ## Authorization diff --git a/docs/operator-manual/git-webhook.md b/docs/operator-manual/git-webhook.md index e5db120f..36213cea 100644 --- a/docs/operator-manual/git-webhook.md +++ b/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: diff --git a/docs/operator-manual/install/with-helm.md b/docs/operator-manual/install/with-helm.md deleted file mode 100644 index 3b6edd50..00000000 --- a/docs/operator-manual/install/with-helm.md +++ /dev/null @@ -1,68 +0,0 @@ -# Install burrito with Helm - -## Requirements - -- Installed [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) command-line tool -- Installed [helm](https://helm.sh/docs/intro/install/) command-line tool **(version v3.8.0 and further)** -- Have a [kubeconfig](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/) file (default location is `~/.kube/config`) - -## 1. Install burrito - -!!! info - Our Helm chart is published in an [OCI-based registry](https://helm.sh/docs/topics/registries/) (ghcr.io). You must use Helm v3.8.0 or above. - -```bash -helm install burrito oci://ghcr.io/padok-team/charts/burrito -n burrito-system --create-namespace -``` - -This will create a new namespace, `burrito-system`, where the burrito operator will live. - -You can change the chart's version with any version available on [our Chart registry](https://github.com/padok-team/burrito/pkgs/container/charts%2Fburrito). - -## 2. Override values - -You can inspect the chart's values with Helm. - -```bash -helm show values oci://ghcr.io/padok-team/charts/burrito -``` - -The chart's source code is available on [burrito GitHub repository](https://github.com/padok-team/burrito). - -Here is an example of values file overriding some default values of burrito: - -```yaml -tenants: - # Example tenant with 1 service account having additional role bindings - - namespace: - create: true - name: "burrito-project-1" - labels: {} - annotations: {} - serviceAccounts: - - name: runner-project-1 - additionalRoleBindings: - - name: custom - role: - kind: ClusterRole - name: custom-role - annotations: {} - labels: {} - # Example tenant with multiple service accounts using GKE Workload Identity - - namespace: - create: true - name: "burrito-project-1" - serviceAccounts: - - name: runner-frontend - annotations: - iam.gke.io/gcp-service-account: burrito-frontend@company-project.iam.gserviceaccount.com - - name: runner-backend - annotations: - iam.gke.io/gcp-service-account: burrito-backend@company-project.iam.gserviceaccount.com - - name: runner-network - annotations: - iam.gke.io/gcp-service-account: burrito-network@company-project.iam.gserviceaccount.com -``` - -!!! info - Learn more about these values in [Advanced Configuration](../advanced-configuration.md) and [Multi-tenant architecture](../multi-tenant-architecture.md). diff --git a/docs/operator-manual/pr-mr-workflow.md b/docs/operator-manual/pr-mr-workflow.md index 38775015..b50dbbcb 100644 --- a/docs/operator-manual/pr-mr-workflow.md +++ b/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 diff --git a/docs/overview.md b/docs/overview.md index b7211b1e..f6d4a484 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -4,23 +4,50 @@ **Burrito** is a TACoS (**T**erraform **A**utomation **Co**llaboration **S**oftware) Kubernetes Operator. -![demo](assets/demo/demo.gif) +Burrito is designed to help you manage and automate your infrastructure as code in a Kubernetes-native way. In simple terms, it aims at being the _[ArgoCD](https://argoproj.github.io/cd/) for Infrastructure as Code_. + +![Burrito UI Overview](assets/demo/ui.png) ## Why burrito? [`terraform`](https://www.terraform.io/) is a tremendous tool to manage your infrastructure in IaC. -However, it lacks built-in solutions for managing [state drift](https://developer.hashicorp.com/terraform/tutorials/state/resource-drift). +However, it lacks built-in solutions for + +- Managing [state drift](https://developer.hashicorp.com/terraform/tutorials/state/resource-drift). +- Continuous planning and applying of your Terraform code +- Easy navigation of Terraform state + +### State drift + +Burrito provides a way to **continuously plan your Terraform code and apply it** . This way, you can ensure that your infrastructure is always up to date with your code, or at least be aware of the drift. +This is especially useful when you have multiple people working on the same Terraform codebase. Burrito will help you detect drifts and resolve them before they become a problem. + +### Continuous planning and applying + +Configuring a CI/CD pipeline for Terraform can be challenging because it often varies depending on the selected tools. Burrito offers an **out-of-the-box PR/MR integration**, so you don't have to write CI/CD pipelines for Terraform ever again. This ensures that you won't have to deal with: + +- Managing state locks +- Managing Terraform versions +- Saving Terraform plan logs and results +- Integrating auditing tools (like [Checkov](https://www.checkov.io/)) + +When a PR/MR is opened, Burrito will automatically plan the Terraform code and comment the MR/PR with the plan. This way, you can easily see the impact of the changes before applying them. Once the PR/MR is merged, Burrito will apply the Terraform code. + +### Navigation of your Terraform state -Additionally, configuring a CI/CD pipeline for Terraform can be challenging and often varies depending on the selected tools +With its curated UI, Burrito provides a way to easily navigate your Terraform state, see the resources, and their dependencies. This way, you can easily see the impact of a change before applying it. [Not yet implemented] -Finally, currently, there is no easy way to navigate your Terraform state to truly understand the modifications it undergoes when running `terraform apply`. +## Compatibility -`burrito` aims to tackle those issues by: +Burrito is compatible with: -- Planning continuously your Terraform code and run applies if needed -- Offering an out of the box PR/MR integration so you do not have to write CI/CD pipelines for Terraform ever again -- Showing your state's modifications in a simple Web UI +- Terraform +- Terragrunt +- OpenTofu (coming soon) ## Getting started -Follow our [getting started guide](./getting-started.md). Further user oriented [documentation](./user-guide/) is provided for additional features. +- 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. diff --git a/docs/reference/index.md b/docs/reference/index.md new file mode 100644 index 00000000..36a513ed --- /dev/null +++ b/docs/reference/index.md @@ -0,0 +1 @@ +# Reference index diff --git a/mkdocs.yml b/mkdocs.yml index 1ca1c239..f6934812 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,9 +1,11 @@ -site_name: burrito +site_name: Burrito repo_url: https://github.com/padok-team/burrito theme: name: material favicon: assets/icon/burrito.png logo: assets/icon/burrito.png + features: + - navigation.indexes markdown_extensions: - codehilite - admonition @@ -12,14 +14,16 @@ markdown_extensions: nav: - Home: index.md - Overview: overview.md -- Getting Started: - - 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 - Operator Manual: - - Install: - - With static manifests: operator-manual/install/with-static-manifests.md - - With our Helm chart: operator-manual/install/with-helm.md - operator-manual/index.md - operator-manual/architecture.md - operator-manual/git-webhook.md @@ -36,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