Merge pull request #8 from zapier/feat/docs

Add documentation

Author: Matt Morrison

.env.example

@@ -1,3 +1,5 @@
 GITLAB_TOKEN=xyz
 KUBECHECKS_LOG_LEVEL=debug
 OPENAI_API_TOKEN=xyz
+GITHUB_TOKEN=xyz
+KUBECHECKS_WEBHOOK_SECRET=xyz

.github/helm-unittest.sh

@@ -6,12 +6,5 @@ echo " helm-unittest.sh ${DIR}"
 echo "#######################"
 
 ###############################################################################
-# NAME: Detect Helm Version
-if [[ `grep -R "apiVersion: v2" "$1/Chart.yaml" > /dev/null; echo $?` -eq 0 ]]
-then
-  HELM_VER="--helm3"
-else
-  HELM_VER=""
-fi
-
-helm unittest ${HELM_VER} "${1}"
+# We always use Helm 3 as Helm 2 is now deprecated
+helm unittest "${1}"

charts/kubechecks/values.yaml

@@ -50,6 +50,7 @@ deployment:
     # ARGOCD_EXEC_TIMEOUT: 600s
     # KUBECHECKS_OTEL_COLLECTOR_PORT: "4317"
     # KUBECHECKS_OTEL_ENABLED: "true"
+    # KUBECHECKS_VCS_TYPE: "github"
 
   startupProbe:
     failureThreshold: 30
@@ -76,7 +77,7 @@ secrets:
   # to the secret resource. These should be passed into the
   # deployment as arguments.
   env: {}
-  # GITLAB_TOKEN: <token>
+  # KUBECHECKS_VCS_TOKEN: <token>
 
 
 serviceAccount:

docs/architecture.md

@@ -0,0 +1,38 @@
+# Architecture
+
+`kubechecks` is driven by webhook events from remote VCS providers (Github, Gitlab, etc), describing new commits/sets of changes (in the form of Pull/Merge Requests). These events are parsed by VCS specific `Client`s and cloned to a local `Repo`, which has all
+the checks `kubechecks` runs made against it.
+
+## Overview
+
+![Overall flow of how Kubechecks works, showing the process from PR, to server, to repo creation, to checks running, to output being posted back to Kubechecks](./img/flow.png)
+
+Once `kubechecks` starts, it will listen on the configured webhook address for payload events. **You must register your remote repository (Github etc) to send PullRequest/MergeRequest events to this address**. Once this is configured, `kubechecks` will respond to new Pull/Merge (PR/MR) requests and begin generating various reports based on the requested changes to be merged into your main branch.
+
+As each application is checked, a comment left on your PR/MR dynamically updates with the latest information; letting you see as soon as possible if something isn't quite right with your new code. Take a look below!
+
+![Kubechecks in practice gif](./img/kubechecks.gif)
+
+## Components
+
+`kubechecks` at it's core is built upon three core ideas; a `Client`, representing the remote VCS provider (i.e. Github or Gitlab) which parses webhook events and interacts with remote Pull/Merge requests; a `CheckEvent`, representing a single run of `kubechecks` in it's entirety; and a `Repo`, representing a local git repository with the changes contained within the webhook event.
+
+### Client
+
+![Diagram of Client, showing the concrete VCS implementation and the Message type](./img/client.png){: style="height:350px;display:block;margin:0 auto;"}
+
+`Client`'s are the entrypoint for kickstarting the whole `kubechecks` process; a `Client` implements functions to enable communication to a remote VCS provider (through posting comments), validate webhooks and their payloads, and convert webhook payloads to the internal representation of a Git Repo. Currently, `kubechecks` has clients written and maintained for both Github and Gitlab; if you'd like to see a new platform supported, make a PR!
+
+### Repo
+
+![Check Event and Repo type diagrams](./img/repo.png){: style="height:350px;display:block;margin:0 auto;"}
+
+`Repo`'s are an internal representation of a Pull/Merge Request, containing information such as the `HEAD` of the PR/MR branch, the base/target branch attempting to be merged into, and git specific metadata such as username/email. This information is then used to locally clone the repository at the specified SHA.
+
+By abstracting the PR/MR in this way, `kubechecks` remains VCS provider agnostic, as the concrete `Client`'s are responsible for producing the `Repo` from their specific implementation. This design ensures that as long as a `Client` is configured to create a `Repo`, `kubechecks` will continue to work without concern.
+
+### CheckEvent
+
+![Check Event and Repo type diagrams](./img/checkevent.png){: style="height:350px;display:block;margin:0 auto;"}
+
+The final piece of the puzzle is the `CheckEvent`; an internal structure that takes a `Client` and a `Repo` and begins running all configured checks. A `CheckEvent` first determines what applications within the repository have been affected by the PR/MR, and begins concurrently running the check suite against each affected application to generate a report for that app. As each application updates its report, the `CheckEvent` compiles all reports together and instructs the `Client` to update the PR/MR with a comment detailing the current progress; resulting in one comment per run of `kubechecks` with the latest information about that particular run. Whenever a new run of `kubechecks` is initiated, all previous comments are deleted to reduce clutter.

docs/contributing.md

@@ -0,0 +1,117 @@
+# Contributing to kubechecks
+
+We're always looking for community contributions to `kubechecks`. The best way to get started is to create an issue. This can be for a bug, or for a new feature. This helps us gauge how many other users are impacted, or would benefit from a new feature.
+
+## Issues
+
+We use [Github Issues](https://github.com/zapier/kubechecks/issues) to track issues and features for this project.
+
+## Contributor Agreement
+
+We have decided to use [DCO](https://en.wikipedia.org/wiki/Developer_Certificate_of_Origin) to reduce the friction of contributing to `kubechecks`. To sign off on a commit you can use `-s` or `--signoff` when committing to append a [trailer](https://git-scm.com/docs/git-commit#Documentation/git-commit.txt--s).
+
+If you forget to sign off on your last commit you can amend it using `git commit --amend --signoff`, or if there are multiple commits that need to be amended `git rebase --signoff HEAD~2` can be used replacing `HEAD~2` with the number of commits to go back. More information can be found in this [Stack Overflow](https://stackoverflow.com/questions/13043357/git-sign-off-previous-commits) post.
+
+Other notable projects that use DCO:
+
+* [Linux Kernel](https://developercertificate.org/)
+* [Gitlab](https://about.gitlab.com/community/contribute/dco-cla/)
+* [GCC](https://gcc.gnu.org/dco.html)
+
+-------------
+
+## Pull Request Process
+
+1. You are welcome to submit a draft pull request for commentary or review before it is fully completed. Feel free to provide more information on the issue you're addressing or a link to a specific one to add more context.
+2. When time permits `kubechecks`'s core team members will look over your contribution and either merge, or provide comments. It may take some time for us to respond. We kindly ask that you do not target specific team members. We may also reject a PR at this time with comments around why, and if we would reconsider it.
+3. If we have requested changes, you can either make those changes or, if you disagree with the suggested changes, we can discuss it further in the pull request. This may be a multi-step process. It is the contributor's responsibility to address any changes requested. While reviewers are happy to give guidance, it is unsustainable for us to perform the coding work necessary to get a PR into a mergeable state.
+4. Once all outstanding comments and checklist items have been addressed, your contribution will be merged! The core team takes care of updating the change log as required. It may be a bit before we cut a new release so your changes may not be available immediately.
+
+### PR Checks
+
+The following checks run when a PR is opened:
+
+* Developer Certificate of Origin (DCO): This check is applied against every **commit**. If a single commit is not signed the check will fail. Please checkout our [Contributor Agreement](#contributor-agreement) for more details.
+* Tests / Build: unit tests, go vet and docker build are executed on each PR. These must all pass for a PR to be considered mergeable.
+
+-----------
+
+## Developer Environment
+
+### Tools / Accounts
+
+* [Go 1.19](https://go.dev/)
+* [Earthly](https://earthly.dev/)
+* [Ngrok](https://ngrok.com/)
+* [Tilt](https://tilt.dev/)
+* [Gitlab](https://gitlab.com) / [Github](https://github.com) token
+* [OpenAI](https://openai.com) token (Optional)
+* [Kubernetes](https://kubernetes.io/)
+  * [minikube](https://minikube.sigs.k8s.io/docs/)
+  * [kind](https://kind.sigs.k8s.io/)
+  * [Docker Desktop](https://docs.docker.com/desktop/kubernetes/)
+
+Some of the above tools are not necessary if you're developing against an externally accessible kubernetes cluster. We leverage Ngrok for local testing in order to accept webhooks from Gitlab/Github.
+
+### Tilt
+
+[Tilt.dev](https://tilt.dev) is used to power the local development environment.
+The `Tiltfile` defines all the resources required to build, run and test `kubechecks`.
+It creates:
+
+* Gitlab / Github repository with test files.
+* Deploys ArgoCD and some demo applications to your kubernetes cluster.
+* Deploys ngrok to provide an external accessible URL for Github/Gitlab to send webhooks to your local dev environment.
+* Builds, tests and runs (with watch and hot restart) the `kubechecks` server in the local Kubernetes cluster.
+* Delve live debugger is available for `kubechecks`.
+
+To get started do the following:
+
+* Copy the `.env.example` and set required values.
+
+    ```console
+    cp .env.example .env
+    ```
+
+* From the root directory of this repo:
+
+    ```console
+    tilt up
+    ```
+
+You should see output like:
+
+    ```
+    Tilt started on http://localhost:10350/
+    v0.30.13, built 2022-12-05
+
+    (space) to open the browser
+    (s) to stream logs (--stream=true)
+    (t) to open legacy terminal mode (--legacy=true)
+    (ctrl-c) to exit
+
+    ```
+
+In the background Tilt has started building and deploying resources.
+
+You should go ahead and press the space bar to open the Tilt web UI.
+
+There are currently some circular dependencies in the local dev resources, so all resources may not come up cleanly on the first launch.
+
+![tilt-1](img/tilt-1.png)
+
+Click the Detailed view button at the top, and click the refresh button next to the `Tiltfile` resource to run another cycle.
+
+![tilt-2](img/tilt-2.png)
+
+#### Minikube
+
+If you're using minikube with Tilt we recommend following this [guide](https://github.com/tilt-dev/minikube-local) to setup a local registry that Tilt can push to automatically. Without this Tilt will attempt to push up to Docker Hub by default.
+
+### Code Changes
+
+We use Earthly to simplify our CI/CD process with `kubechecks`. This also simplifies testing changes locally before pushing them up to ensure your PR will pass all required checks. The best command to run is `earthly +unit-test` this will pull all the required dependencies (including any new ones that you have added). It will then run [go vet](https://pkg.go.dev/cmd/vet), and if those pass it will run `go test` with race detection enabled. You can also always run these commands directly `go test -race ./...` will run all tests in the repo with race detection enabled. Please ensure that `earthly +unit-test` is passing before opening a PR.
+
+### Documentation Changes
+
+We use [mkdocs](https://www.mkdocs.org/) to build our docs locally. You can build these docs by running `mkdocs serve` from the root of the repository. It will also auto reload when any file is changed in that directory. By default you can view the docs under `http://localhost:8000`. Please confirm that any changes to documentation render correctly and that your changes display as expected.