Merge pull request #5 from zapier/update-docs

Add detail to docs.

README.md

@@ -1,34 +1,37 @@
-# TF Buddy
+# TFBuddy
 
 TFBuddy allows Terraform Cloud users to get apply-before-merge workflows in their Pull Requests.
 
 ## Terraform Cloud API Driven Runs
 
 Terraform Cloud (TFC) has a native VCS integration that can trigger plans and applies based for repositories, however it
-requires a merge after apply workflow that is not desirable in many cases. This tool has been developed to enable a 
+requires a merge after apply workflow that may not be desirable in some cases. This tool has been developed to enable a 
 apply-before-merge workflow. 
 
-### How
+### How it works
+
+This tool provides a server function that processes webhooks from Gitlab/Github, triggers a Run in TFC for Merge/Pull Requests
+and then passes status updates of those Runs back to the Merge/Pull Request in the form of comments.
 
-This tool provides a server function that processes webhooks from Gitlab/Github, triggers a Run in TFC for the Merge Request 
-and then passes status updates of those back to the Merge/Pull Request in the form of comments.
 
 ### Architecture
 
 TFBuddy consists of the webhook handler and a NATS cluster.
 
 ![](./docs/img/overview.png)
 
-### Building
 
-```
-git clone ssh://[email protected]/zapier/tfbuddy.git
-cd tfbuddy
-go mod download
-go test -v ./...
-go build -v
-```
+## Installation
+
+### Helm
+
+See [Installation Docs](https://tfbuddy.readthedocs.io/en/stable/usage/)
+
 
 ## Documentation
 
-To learn more about TF Buddy [go to the complete documentation](https://tfbuddy.readthedocs.io/).
+To learn more about TF Buddy [go to the complete documentation](https://tfbuddy.readthedocs.io/).
+
+---
+
+Made by SRE Team @ ![zapier](https://zapier-media.s3.amazonaws.com/zapier/images/logo60orange.png)

charts/tfbuddy/values.yaml

@@ -6,7 +6,7 @@ resources:
     cpu: 250m
     memory: 128Mi
 
-replicaCount: 1
+replicaCount: 3
 
 pdb:
   maxUnavailable: 1
@@ -23,12 +23,31 @@ containerPort: 8080
 
 env:
   TFBUDDY_LOG_LEVEL: info
+
+  ## The connection URL for NATS. Override if using your own NATS installation.
   TFBUDDY_NATS_SERVICE_URL: nats://tfbuddy-nats:4222
+
+  ## The Gitlab projects for which TFBuddy is allowed to process webhooks
+  ## This value is applied as a prefix match, so a value of
+  ## `companyx/` would match all projects in the `companyx` group
   # TFBUDDY_PROJECT_ALLOW_LIST:
+
+  ## Comma seperated list of the Terraform Cloud workspaces that TFBuddy is allowed to manage.
+  ## If not set, all workspaces are allowed, if set, only workspaces in this list are allowed.
+  ## The environment variable TFBUDDY_WORKSPACE_DENY_LIST can also be used to deny specific workspaces.
   # TFBUDDY_WORKSPACE_ALLOW_LIST:
+
+  ## The default Terraform Cloud organization. If a repo's `.tfbuddy.yaml` does not
+  ## provide the organization, this value will be used.
   # TFBUDDY_DEFAULT_TFC_ORGANIZATION:
+
+  ## The Webhook secret TFBuddy expects in hooks from Gitlab
   # TFBUDDY_GITLAB_HOOK_SECRET_KEY:
 
+
+  ## The Webhook secret TFBuddy expects in hooks from Github
+  # TFBUDDY_GITHUB_HOOK_SECRET_KEY:
+
 envFrom:
   - secretRef:
       name: tfbuddy

docs/contributing.md

@@ -35,7 +35,7 @@ The following checks run when a PR is opened:
 ## Developer Environment
 
 ### Tools / Accounts
-* [Go 1.18](https://go.dev/)
+* [Go 1.19](https://go.dev/)
 * [Earthly](https://earthly.dev/)
 * [Ngrok](https://ngrok.com/)
 * [Tilt](https://tilt.dev/)
@@ -51,6 +51,55 @@ Some of the above tools are not necessary if you're developing against an extern
 
 ### 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 TFBuddy.
+It creates:
+* Gitlab / Github repository with test files.
+* Deploys nats into a local kubernetes cluster (kind, minikube, docker-desktop etc).
+* Deploys ngrok to provide an external accessible URL for Github/Gitlab/TFC to send webhooks to your local dev environment.
+* Builds, tests and runs (with watch and hot restart) the TFBuddy server in the local Kubernetes cluster.
+* Delve live debugger is available for TFBuddy.
+
+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.

docs/index.md

@@ -1,12 +1,13 @@
-# TF Buddy - Apply before Merge
+# TFBuddy - Terraform Cloud workflow engine
 
 ## What is TF Buddy
-TF Buddy is an application meant to simplify executing terraform in your pull requests. It works with Github, and Gitlab and only supports Terraform Cloud Workspaces currently. TF Buddy has been in use at Zapier in production for the past 9 months, and is still under active development.
+TF Buddy is an application meant to simplify executing terraform in your pull requests. It supports Github, and Gitlab and Terraform Cloud Workspaces currently. TF Buddy has been in use at Zapier, in production for the past 9 months, and is still under active development.
 
 ## Why TF Buddy?
 
 1. Apply before merging your pull requests
 1. Cleaner breakdown of what's going to change in your pull request
+1. Keep your TFC workspaces in API-drive / CLI-drive mode so you can still use the `terraform` CLI for maintenance actions not easily achieved via GitOps.
 
 ## Documentation
 

docs/usage.md

@@ -2,26 +2,49 @@
 
 How to deploy TF Buddy onto your infrastructure. We provide a helm chart to simplify deployment. 
 
-## Dependencies
-1. [NATS](https://nats.io/)
-1. Gitlab / Github
-1. Terraform Cloud Workspace
 
-## Helm Chart
+## Installation
+
+### Dependencies
+1. Kubernetes Cluster
+1. Gitlab / Github token
+1. Terraform Cloud token
+1. [NATS](https://nats.io/) (installed by TFBuddy helm chart)
+
+### Helm
+
+```console
+helm repo add tfbuddy https://zapier.github.io/tfbuddy/
+```
+
+**For use with Github**
+
+```console
+export TFC_TOKEN="" \
+       GITHUB_TOKEN=""
+
+helm install tfbuddy charts/tfbuddy \
+  --set secrets.env.TFC_TOKEN="${TFC_TOKEN}" \
+  --set secrets.env.GITHUB_TOKEN="${GITHUB_TOKEN}" \
+  --dependency-update
+```
+
+**For use with Gitlab**
 
 ```console
 export TFC_TOKEN="" \
        GITLAB_TOKEN="" \
        GITLAB_TOKEN_USER=""
 
-helm repo add tfbuddy https://zapier.github.io/tfbuddy/
-
 helm install tfbuddy charts/tfbuddy \
   --set secrets.env.TFC_TOKEN="${TFC_TOKEN}" \
   --set secrets.env.GITLAB_TOKEN="${GITLAB_TOKEN}" \
-  --set secrets.env.GITLAB_TOKEN_USER="${GITLAB_TOKEN_USER}"
+  --set secrets.env.GITLAB_TOKEN_USER="${GITLAB_TOKEN_USER}" \
+  --dependency-update
 ```
 
+The default helm values can be found [here](https://github.com/zapier/tfbuddy/blob/main/charts/tfbuddy/values.yaml).
+
 ### Configuration
 
 Set the necessary environment variables for your setup.