diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 355304b6..fc3c3091 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -3,8 +3,15 @@ on: push: branches: - main + pull_request: + branches: + - main + paths: + - "docs/**" + permissions: contents: write + jobs: deploy: runs-on: ubuntu-latest @@ -15,9 +22,22 @@ jobs: python-version: 3.x - uses: actions/cache@1bd1e32a3bdc45362d1e726936510720a7c30a57 # v4 with: - key: mkdocs-material-${{ github.sha }} + key: mkdocs-material-${{ github.ref }} path: .cache restore-keys: | mkdocs-material- + - run: pip install mkdocs-material - - run: mkdocs gh-deploy --force + + - name: Lint Markdown files + uses: DavidAnson/markdownlint-cli2-action@v19 + with: + config: 'docs/.markdownlint.jsonc' + globs: 'docs/**/*.md' + + - name: Build pages + run: mkdocs build --strict + + - name: Deploy pages + run: mkdocs gh-deploy --strict --force + if: github.ref == 'refs/heads/main' diff --git a/docs/.markdownlint.jsonc b/docs/.markdownlint.jsonc new file mode 100644 index 00000000..0c73c755 --- /dev/null +++ b/docs/.markdownlint.jsonc @@ -0,0 +1,7 @@ +{ + "line-length": false, + "no-inline-html": false, + "no-alt-text": false, + "no-duplicate-heading": false, + "ul-indent": false +} \ No newline at end of file diff --git a/docs/contributing.md b/docs/contributing.md index c0773c47..3f871349 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -56,22 +56,25 @@ Follow these steps to install a minimal working configuration of Burrito on a Ki - A datastore running with mock storage (in-memory) - A `TerraformRepository` and an associated `TerraformLayer` resource in the `burrito-project` namespace, pointing to the [padok-team/burrito-examples](https://github.com/padok-team/burrito-examples) repository -*Before starting, check that your local Kind cluster is running and that your context is set to target this cluster* +*Before starting, check that your local Kind cluster is running and that your context is set to target this cluster.* 1. **Install cert-manager on your cluster:** -```bash -helm repo add bitnami https://charts.bitnami.com/bitnami -helm upgrade --install -n cert-manager --create-namespace cert-manager bitnami/cert-manager --set installCRDs=true -``` + + ```bash + helm repo add bitnami https://charts.bitnami.com/bitnami + helm upgrade --install -n cert-manager --create-namespace cert-manager bitnami/cert-manager --set installCRDs=true + ``` + 2. **Fork and clone this repository.** 3. **Run the following command to build a local image of Burrito, load it into your Kind cluster, and install Burrito with development Helm values:** - + ```bash make upgrade-dev-kind ``` 4. **Check that Burrito is running in the `burrito-system` namespace:** + ```bash kubectl get pods -n burrito-system ``` @@ -134,7 +137,7 @@ helm upgrade --install -n cert-manager --create-namespace cert-manager bitnami/c The output should be similar to: - ``` + ```text NAME READY STATUS RESTARTS AGE my-layer-apply-gxjhd 0/1 Completed 0 2m36s ``` @@ -157,7 +160,7 @@ Check the [Makefile](https://github.com/padok-team/burrito/blob/main/Makefile) f ### Advanced Settings -**Configure a GitHub Token for TENV** +**Configure a GitHub Token for TENV:** It is strongly recommended to create a GitHub token with no specific rights to bypass the GitHub API rate limiting. Append the following configuration to your development `TerraformRepository` resources: diff --git a/docs/getting-started.md b/docs/getting-started.md index bf69b490..f7f49236 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -18,6 +18,7 @@ Copy and modify the [default values](https://github.com/padok-team/burrito/blob/ 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 in step 3. For example, here is a default `values.yaml` file: + ```yaml config: datastore: @@ -47,14 +48,18 @@ This will create a new namespace, `burrito-system`, where Burrito services will Create a Kubernetes `Secret` to reference the necessary credentials to clone your IaC repository (GitHub or GitLab) + !!! info Supported authentication methods are: + - Username and password - SSH private key - GitHub App - GitHub API token - GitLab API token - More information on how to create a secret can be found in the [Secrets](./secrets/index.md) section. + + More information on how to create a secret can be found in the [Git Authentication](./operator-manual/git-authentication.md) section. + ```yaml kind: Secret @@ -116,4 +121,3 @@ The controller will create a runner pod in your tenant namespace to synchronize - 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/guides/iac-drift-detection.md b/docs/guides/iac-drift-detection.md index 351b8fc4..e57cb388 100644 --- a/docs/guides/iac-drift-detection.md +++ b/docs/guides/iac-drift-detection.md @@ -48,7 +48,8 @@ kubectl get pods -n burrito-system ``` Output: -``` + +```text NAME READY STATUS RESTARTS AGE burrito-controllers-6945797c5d-kjfl2 1/1 Running 0 2m00s burrito-datastore-94d999f54-kbg9z 1/1 Running 0 2m00s @@ -82,7 +83,7 @@ spec: enabled: true ``` -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. +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 @@ -173,4 +174,4 @@ You have successfully set up Burrito on a local cluster and planned your Terrafo ## Next steps -- Learn how to [configure a PR/MR workflow](../pr-mr-workflow.md) +- Learn how to [configure a PR/MR workflow](../operator-manual/pr-mr-workflow.md) diff --git a/docs/guides/index.md b/docs/guides/index.md index 9a528c4e..c03555ba 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -1,7 +1,7 @@ # Getting started -Follow the 3 guides below to understand how to use 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. -- [UI Overview](./ui-overview.md): Learn how to navigate the Burrito UI. +- [UI Overview](./ui.md): Learn how to navigate the Burrito UI. diff --git a/docs/guides/pr-mr-workflow.md b/docs/guides/pr-mr-workflow.md index 74c675c0..0114fa54 100644 --- a/docs/guides/pr-mr-workflow.md +++ b/docs/guides/pr-mr-workflow.md @@ -37,6 +37,7 @@ Now let's configure the GitHub webhook. Expose the `burrito-server` kubernetes s 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. Reference your webhook secret in the secret associated to your repository, in the `webhookSecret` key. Your `TerraformRepository` resource and secret should look like this: + ```yaml apiVersion: config.terraform.padok.cloud/v1alpha1 kind: TerraformRepository @@ -62,7 +63,7 @@ stringData: -----BEGIN RSA PRIVATE KEY----- my-private-key -----END RSA PRIVATE KEY----- - webhookSecret: "my-webhook-secret" + webhookSecret: "my-webhook-secret" ``` ### Experiment with the PR/MR workflow diff --git a/docs/index.md b/docs/index.md index 27a3893d..1426666b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -5,9 +5,8 @@ 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. +- [Operator Manual](./operator-manual/index.md) is a detailed guide to help you understand how to install and configure Burrito. +- [User Guide](./user-guide/index.md) is a detailed guide to help you understand how to setup and use Burrito resources. - [Contributing](./contributing.md) provides information on how to contribute to the Burrito project. - diff --git a/docs/installation/with-helm.md b/docs/installation/with-helm.md index a5099fdf..fcba4062 100644 --- a/docs/installation/with-helm.md +++ b/docs/installation/with-helm.md @@ -31,7 +31,6 @@ 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 diff --git a/docs/installation/with-static-manifests.md b/docs/installation/with-static-manifests.md index eb581f00..4ee3632f 100644 --- a/docs/installation/with-static-manifests.md +++ b/docs/installation/with-static-manifests.md @@ -8,7 +8,7 @@ ## Install burrito !!! info - This will install a mono-tenant version of burrito. See the [Helm installation method](./with-helm.md) for a [multi-tenant-architecture](../multi-tenant-architecture.md). + This will install a mono-tenant version of burrito. See the [Helm installation method](./with-helm.md) for a [multi-tenant-architecture](..//operator-manual/multi-tenant-architecture.md). ```bash kubectl create namespace burrito diff --git a/docs/operator-manual/git-authentication.md b/docs/operator-manual/git-authentication.md index b677e0bd..2d5c7af6 100644 --- a/docs/operator-manual/git-authentication.md +++ b/docs/operator-manual/git-authentication.md @@ -4,44 +4,53 @@ This section will guide you through the different ways to authenticate to a git repository. Authentication is required for: + - Cloning a private repository - Implementing the [PR/MR workflow](./pr-mr-workflow.md) +- Setting up the webhook for listening to push / pull requests events Available authentication methods: + - Username and password (only supports cloning) - SSH private key (only supports cloning) -- GitHub App +- [GitHub App](https://docs.github.com/en/apps) - GitHub API token - GitLab API token ## Repository Secret The `TerraformRepository` spec allows you to specify a secret that contains the credentials to authenticate to a git repository. -The secret must be created in the same namespace as the `TerraformRepository` and be referenced in `spec.repository.secretName`. +The secret must be created in the **same namespace** as the `TerraformRepository` and be referenced in `spec.repository.secretName`. ### Expected keys To add an authentication method for a repository, the secret must contain the following keys: -Username and password: +Username and password (Git's HTTPS authentication): + - `username` - `password` -SSH private key: +SSH private key (Git's SSH authentication): + - `sshPrivateKey` GitHub App: + - `githubAppId` - `githubAppInstallationId` - `githubAppPrivateKey` GitHub API token: + - `githubToken` GitLab API token: + - `gitlabToken` For the PR/MR workflow, the Kubernetes secret must also contain the webhook secret: + - `webhookSecret` Example of a Kubernetes secret for a GitHub repository, using authentication with a GitHub App and implementing the PR workflow: @@ -60,7 +69,7 @@ stringData: -----BEGIN RSA PRIVATE KEY----- my-private-key -----END RSA PRIVATE KEY----- - webhookSecret: "my-webhook-secret" + webhookSecret: "my-webhook-secret" ``` ### Behavior diff --git a/docs/operator-manual/multi-tenant-architecture.md b/docs/operator-manual/multi-tenant-architecture.md index 3e786ffe..0ef6486b 100644 --- a/docs/operator-manual/multi-tenant-architecture.md +++ b/docs/operator-manual/multi-tenant-architecture.md @@ -2,7 +2,7 @@

-With our [Helm chart](./install/with-helm.md) we provide a way to setup multi-tenancy with burrito. This is useful when working at scale, when you controls multiple Terraform projects with burrito across several teams. +With our [Helm chart](../installation/with-helm.md) we provide a way to setup multi-tenancy with burrito. This is useful when working at scale, when you controls multiple Terraform projects with burrito across several teams. The setup is split across multiple Kubernetes namespaces: @@ -15,7 +15,7 @@ Thanks to Kubernetes native RBAC system you can restrict access for your users o ### 1. Configure basic tenants -In the `values.yaml` of the [Helm chart](./install/with-helm.md), add the following: +In the `values.yaml` of the [Helm chart](../installation/with-helm.md), add the following: ```yaml tenants: diff --git a/docs/operator-manual/pr-mr-workflow.md b/docs/operator-manual/pr-mr-workflow.md index f65bb3e1..e1cda878 100644 --- a/docs/operator-manual/pr-mr-workflow.md +++ b/docs/operator-manual/pr-mr-workflow.md @@ -49,6 +49,7 @@ With those 3 conditions, we defined 3 states: 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. @@ -61,11 +62,11 @@ You can create and register GitHub Apps in your personal GitHub account or in an Follow the instructions in the GitHub documentation on [Creating a GitHub App](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app). Populate the settings as follows: - **GitHub App Name**: Choose a name for your GitHub App. For example, something featuring `burrito`. -- **Homepage URL**: Enter https://padok-team.github.io/burrito. -- **Webhook**: Deselect Active. The app doesn't use this webhook events mechanism at the moment. -- **Permissions**: Configure the following **Repository Permissions**. - - **Metadata**: Select Read-only. - - **Pull requests**: Select Read & write. This is required to issue comments on pull requests. +- **Homepage URL**: Enter . +- **Webhook**: Unselect Active. The app doesn't use this webhook events mechanism at the moment. +- **Permissions**: Configure the following **Repository Permissions**: + - **Metadata**: Select Read-only. + - **Pull requests**: Select Read & write. This is required to issue comments on pull requests. - Where can this GitHub App be installed: Select **Any account**. #### Creating a custom badge for your GitHub App @@ -86,13 +87,12 @@ Follow the instructions in the GitHub documentation on [Installing your own GitH You need the **Installation ID** and **App ID** to configure Burrito. + 1. Get the **Installation ID** from the URL of the installed app, such as: - -

- +

2. Get the **App ID** from the app's General tab. - -

+

+ #### Generate a private key @@ -107,6 +107,7 @@ You need a private key for your GitHub app to configure Burrito. Add the credentials of your newly created app to the secret associated to your `TerraformRepository` resource. If the repository is public, create a secret in the same namespace as the `TerraformRepository` and reference it in the `spec.repository.secretName`. For example: + ```yaml apiVersion: config.terraform.padok.cloud/v1alpha1 kind: TerraformRepository @@ -145,9 +146,9 @@ You need a personal access token to configure Burrito. You can generate a person Follow the instructions in the GitHub documentation for [creating a personal access token](https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token): - It should be a **fine-grained token**. -- **Permissions**: Configure the following **Repository Permissions**. - - **Metadata**: Select Read-only. - - **Pull requests**: Select Read & write. This is required to issue comments on pull requests. +- **Permissions**: Configure the following **Repository Permissions**: + - **Metadata**: Select Read-only. + - **Pull requests**: Select Read & write. This is required to issue comments on pull requests. - Under **Repository access**, select which repositories you want the token to access. #### Configure Burrito @@ -155,6 +156,7 @@ Follow the instructions in the GitHub documentation for [creating a personal acc Set the `githubToken` key in the secret associated to your `TerraformRepository` resource. For example: + ```yaml apiVersion: config.terraform.padok.cloud/v1alpha1 kind: TerraformRepository @@ -188,8 +190,8 @@ You need a private token for your GitLab app to configure Burrito. You can gener Set the `gitlabToken` key in the secret associated to your `TerraformRepository` resource. - For example: + ```yaml apiVersion: config.terraform.padok.cloud/v1alpha1 kind: TerraformRepository diff --git a/docs/operator-manual/provider-caching.md b/docs/operator-manual/provider-caching.md index ec94c68c..94920bed 100644 --- a/docs/operator-manual/provider-caching.md +++ b/docs/operator-manual/provider-caching.md @@ -6,7 +6,7 @@ The Burrito Helm chart is packaged with [Hermitcrab](https://github.com/seal-io/ ## 1. Activate Hermitcrab on Burrito -Hermitcrab is available to use with Burrito when using the Helm chart. +Hermitcrab is available to use with Burrito when using the Helm chart. Set the `config.burrito.hermitcrab` parameter to true in your values file to activate Hermitcrab. As the Provider Network Mirror Protocol only supports HTTPS traffic, it is required to provide Burrito runners & the Hermitcrab server with some TLS configuration. By default, the Helm chart expects a secret named `burrito-hermitcrab-tls` to contain TLS configuration: `ca.crt`, `tls.crt`, and `tls.key`. @@ -14,7 +14,7 @@ As the Provider Network Mirror Protocol only supports HTTPS traffic, it is requi ### Option 1: Use Cert-Manager The Helm chart is packaged with Cert-Manager configuration to use for Burrito/Hermitcrab TLS encryption. -Assuming that Cert-Manager is installed on your cluster, set the `hermitcrab.tls.certmanager.use` parameter to `true`. This setting adds a Cert-Manager Certificate resource to be used with Burrito. +Assuming that Cert-Manager is installed on your cluster, set the `hermitcrab.tls.certmanager.use` parameter to `true`. This setting adds a Cert-Manager Certificate resource to be used with Burrito. Provide Certificate spec with the `hermitcrab.tls.certmanager.spec` value. You **must** set the `secretName` value to the same value specified in `config.burrito.hermitcrab.certificateSecretName` (default `burrito-hermitcrab-tls`) #### Example configuration with a self-signed issuer diff --git a/docs/overview.md b/docs/overview.md index e1e9df75..838babb5 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -41,14 +41,13 @@ With its curated UI, Burrito provides a way to easily navigate your Terraform st Burrito is compatible with: -- Terraform. -- Terragrunt. -- OpenTofu (coming soon). +- Terraform +- Terragrunt +- OpenTofu ## Getting Started -- 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 set up advanced configurations and features. -- Use the [user guide](./user-guide/) to learn how to configure Burrito resources according to your needs. - +- 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/index.md) to set up advanced configurations and features. +- Use the [user guide](./user-guide/index.md) to learn how to configure Burrito resources according to your needs.