docs: complete the readme (#46)

* docs: init readme parts * docs: add apache 2.0 license * docs: add instanciation of repoitory/layer and env vars configuration * feat: remove need of : for env vars * feat: expose redis URL param * feat: update config to use int for ports * feat: use time.Duration type for controller timers * fix: use time.Duration for default timers' values * docs: use docs folder * docs: add usage section * docs: add license badge * docs: add the why of the tool * docs: fix some typos * docs: add how it works section * docs: add architectural overview and components description * docs: add implementation details * docs: generate tables of contents * chore: change default redis url * fix: rename redis database flag * docs: add webhooki setup in usage * feat: use string for ports config * feat: move webhook config inside server's * chore: put back old flags to make it work * feat: change server port to server addr * fix(controllers): inverted metrics and health check probes addr * fix(ci): build-args were passed as one arg * docs(ports): default ports were wrong * chore: add install manifest * docs: ad disntallation guidelines * Update README.md Co-authored-by: Alan-pad <[email protected]> * Apply suggestions from code review Co-authored-by: Alan-pad <[email protected]> * docs(markdown): linting * chore: use logrus as logging library and change variable naming * docs: separate advanced usage and getting started * docs: add link to CRD doc * fix(rbac): controllers require events access to work with leader election * docs: add demo gif --------- Co-authored-by: Alan <[email protected]> Co-authored-by: Alan-pad <[email protected]>
padok-team · Feb 21, 2023 · 1387f4b · 1387f4b
1 parent 72b9cb7
commit 1387f4b
Show file tree

Hide file tree

Showing 27 changed files with 1,604 additions and 231 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -59,7 +59,10 @@ jobs:
       uses: docker/build-push-action@v3
       with:
         push: true
-        build-args: VERSION=${{ env.VERSION }},BUILD_TIMESTAMP=${{ env.BUILD_TIMESTAMP }},COMMIT_HASH=${{ env.VERSION }}
+        build-args: |
+          VERSION=${{ env.VERSION }}
+          BUILD_TIMESTAMP=${{ env.BUILD_TIMESTAMP }}
+          COMMIT_HASH=${{ env.VERSION }}
         tags: |
           ghcr.io/${{ github.repository }}:latest
           ghcr.io/${{ github.repository }}:${{ env.VERSION }}
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2022 Padok
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/README.md b/README.md
@@ -1,2 +1,121 @@
-# burrito
-Burrito is TACOS.
+# burrito <!-- omit in toc -->
+
+[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+<p align="center"><img src="./docs/assets/icon/burrito.png" width="200px" /></p>
+
+**Burrito** is a TACoS (**T**erraform **A**utomation **Co**llaboration **S**oftware) implemented as Kubernetes Operator.
+
+- [Why does this exists?](#why-does-this-exists)
+- [Demo](#demo)
+- [Installation](#installation)
+- [Getting started](#getting-started)
+  - [Connect to a private repository](#connect-to-a-private-repository)
+  - [Synchronize a terraform layer](#synchronize-a-terraform-layer)
+- [Advanced usage](#advanced-usage)
+- [How it works](#how-it-works)
+- [License](#license)
+
+## Why does this exists?
+
+[`terraform`](https://www.terraform.io/) is a tremendous tool to manage your infrastructure in IaC.
+But, it does not come up with an out-of the box solution for managing [state drift](https://developer.hashicorp.com/terraform/tutorials/state/resource-drift).
+
+Also, writing a CI/CD pipeline for terraform can be painful and depends on the tool you are using.
+
+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 (not implemented yet)
+- Showing your state's modifications in a simple Web UI (not implemented yet)
+
+## Demo 
+
+![demo](./docs/assets/demo/demo.gif)
+
+## Installation
+
+You can just run the following:
+
+```bash
+kubectl apply -f https://raw.githubusercontent.com/padok-team/burrito/main/manifests/install.yaml
+```
+
+## Getting started
+
+`burrito` uses two [CRDs](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/):
+- `TerraformRepository` which defines the way to connect to a public or private repository containing some `terraform` code
+- `TerraformLayer` which defines a `terraform` layer insidea given `TerraformRepository`
+
+### Connect to a private repository
+
+Create a Kubernetes `Secret` which looks like:
+
+```yaml
+kind: Secret
+metadata:
+  name: burrito-repo
+  namespace: burrito
+type: Opaque
+stringData:
+  username: <my-username>
+  password: <my-password | my-access-token>
+  sshPrivateKey: |
+    -----BEGIN OPENSSH PRIVATE KEY-----
+    ...
+    -----END OPENSSH PRIVATE KEY-----
+```
+
+Then, create a `TerraformRepository` Kubernetes resource:
+
+```yaml
+apiVersion: config.terraform.padok.cloud/v1alpha1
+kind: TerraformRepository
+metadata:
+  name: burrito
+  namespace: burrito
+spec:
+  repository:
+    url: <https_or_ssh_repository_url>
+    secretName: burrito-repo
+```
+
+> N.B. You can also connect to a public repository by omitting `spec.repository.secretName` in your `TerraformLayer` definition.
+
+### Synchronize a terraform layer
+
+First, you need to create a `TerraformRepository`.
+
+Then, create a `TerraformLayer` ressource which looks like:
+
+```yaml
+apiVersion: config.terraform.padok.cloud/v1alpha1
+kind: TerraformLayer
+metadata:
+  name: random-pets
+  namespace: burrito
+spec:
+  terraformVersion: "1.3.1"
+  path: "internal/e2e/testdata/random-pets"
+  branch: "main"
+  repository:
+    kind: TerraformRepository
+    name: burrito
+    namespace: burrito
+```
+
+## Advanced usage
+
+See [Usage](docs/contents/usage/README.md) for more advanced configuration options.
+
+## How it works
+
+See [Design](docs/contents/design/README.md) for details on how `burrito` works under the hood.
+
+## License
+
+© 2022 [Padok](https://www.padok.fr/).
+
+Licensed under the [Apache License](https://www.apache.org/licenses/LICENSE-2.0), Version 2.0 ([LICENSE](./LICENSE))
diff --git a/cmd/controllers/start.go b/cmd/controllers/start.go
@@ -4,6 +4,8 @@ Copyright © 2022 NAME HERE <EMAIL ADDRESS>
 package controllers
 
 import (
+	"time"
+
 	"github.com/padok-team/burrito/internal/burrito"
 	"github.com/spf13/cobra"
 )
@@ -21,15 +23,19 @@ func buildControllersStartCmd(app *burrito.App) *cobra.Command {
 		},
 	}
 
+	defaultDriftDetectionTimer, _ := time.ParseDuration("20m")
+	defaultOnErrorTimer, _ := time.ParseDuration("1m")
+	defaultWaitActionTimer, _ := time.ParseDuration("1m")
+
 	cmd.Flags().StringSliceVar(&app.Config.Controller.Types, "types", []string{"layer", "repository"}, "list of controllers to start")
 
-	cmd.Flags().StringVar(&app.Config.Controller.Timers.DriftDetection, "drift-detection-period", "20m", "period between two plans. Must end with s, m or h.")
-	cmd.Flags().StringVar(&app.Config.Controller.Timers.OnError, "on-error-period", "1m", "period between two runners launch when an error occured. Must end with s, m or h.")
-	cmd.Flags().StringVar(&app.Config.Controller.Timers.WaitAction, "wait-action-period", "1m", "period between two runners when a layer is locked. Must end with s, m or h.")
+	cmd.Flags().DurationVar(&app.Config.Controller.Timers.DriftDetection, "drift-detection-period", defaultDriftDetectionTimer, "period between two plans. Must end with s, m or h.")
+	cmd.Flags().DurationVar(&app.Config.Controller.Timers.OnError, "on-error-period", defaultOnErrorTimer, "period between two runners launch when an error occured. Must end with s, m or h.")
+	cmd.Flags().DurationVar(&app.Config.Controller.Timers.WaitAction, "wait-action-period", defaultWaitActionTimer, "period between two runners when a layer is locked. Must end with s, m or h.")
 	cmd.Flags().BoolVar(&app.Config.Controller.LeaderElection.Enabled, "leader-election", true, "whether leader election is enabled or not, default to true")
 	cmd.Flags().StringVar(&app.Config.Controller.LeaderElection.ID, "leader-election-id", "6d185457.terraform.padok.cloud", "lease id used for leader election")
-	cmd.Flags().StringVar(&app.Config.Controller.HealthProbeBindAddress, "metrics-bind-address", ":8080", "address to bind the metrics server embedded in the controllers")
-	cmd.Flags().StringVar(&app.Config.Controller.MetricsBindAddress, "health-probe-bind-address", ":8081", "address to bind the health probe server embedded in the controllers")
+	cmd.Flags().StringVar(&app.Config.Controller.HealthProbeBindAddress, "health-probe-bind-address", ":8081", "address to bind the metrics server embedded in the controllers")
+	cmd.Flags().StringVar(&app.Config.Controller.MetricsBindAddress, "metrics-bind-address", ":8080", "address to bind the health probe server embedded in the controllers")
 	cmd.Flags().IntVar(&app.Config.Controller.KubernetesWehbookPort, "kubernetes-webhook-port", 9443, "port used by the validating webhook server embedded in the controllers")
 	return cmd
 }
diff --git a/cmd/root.go b/cmd/root.go
@@ -25,6 +25,10 @@ func buildBurritoCmd(app *burrito.App) *cobra.Command {
 		},
 	}
 
+	cmd.Flags().StringVar(&app.Config.Redis.URL, "redis-url", "burrito-redis:6379", "the redis URL to connect to")
+	cmd.Flags().StringVar(&app.Config.Redis.Password, "redis-password", "", "the redis password")
+	cmd.Flags().IntVar(&app.Config.Redis.Database, "redis-database", 0, "the redis database")
+
 	cmd.AddCommand(controllers.BuildControllersCmd(app))
 	cmd.AddCommand(runner.BuildRunnerCmd(app))
 	cmd.AddCommand(server.BuildServerCmd(app))

diff --git a/cmd/server/start.go b/cmd/server/start.go
@@ -15,7 +15,7 @@ func buildServerStartCmd(app *burrito.App) *cobra.Command {
 		},
 	}
 
-	cmd.Flags().StringVar(&app.Config.Server.Port, "port", "8080", "port the server listens on")
+	cmd.Flags().StringVar(&app.Config.Server.Addr, "addr", ":8080", "addr the server listens on")
 
 	return cmd
 }
diff --git a/docs/assets/demo/demo.gif b/docs/assets/demo/demo.gif
diff --git a/docs/assets/design/architecture-overview.excalidraw.png b/docs/assets/design/architecture-overview.excalidraw.png
diff --git a/docs/assets/icon/burrito.png b/docs/assets/icon/burrito.png
diff --git a/docs/assets/icon/burrito.txt b/docs/assets/icon/burrito.txt
@@ -0,0 +1 @@
+The icon is taken from flaticon.com (https://www.flaticon.com/fr/icone-gratuite/burrito_5596710?term=burrito&page=1&position=5&origin=search&related_id=5596710)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		The icon is taken from flaticon.com (https://www.flaticon.com/fr/icone-gratuite/burrito_5596710?term=burrito&page=1&position=5&origin=search&related_id=5596710)