feat: add helm README, install guide, linters (#3268)

deansheather · web-flow · commit 55890df6f12b · 2022-08-19T02:41:23.000+10:00
diff --git a/.github/workflows/coder.yaml b/.github/workflows/coder.yaml
@@ -52,6 +52,7 @@ jobs:
       docs-only: ${{ steps.filter.outputs.docs_count == steps.filter.outputs.all_count }}
       sh: ${{ steps.filter.outputs.sh }}
       ts: ${{ steps.filter.outputs.ts }}
+      k8s: ${{ steps.filter.outputs.k8s }}
     steps:
       - uses: actions/checkout@v3
       # For pull requests it's not necessary to checkout the code
@@ -69,6 +70,10 @@ jobs:
               - "**.sh"
             ts:
               - 'site/**'
+            k8s:
+              - 'helm/**'
+              - Dockerfile
+              - scripts/helm.sh
       - id: debug
         run: |
           echo "${{ toJSON(steps.filter )}}"
@@ -136,6 +141,26 @@ jobs:
         run: yarn lint
         working-directory: site
 
+  style-lint-k8s:
+    name: "style/lint/k8s"
+    timeout-minutes: 5
+    needs: changes
+    if: needs.changes.outputs.k8s == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Install helm
+        uses: azure/setup-helm@v3
+        with:
+          version: v3.9.2
+
+      - name: cd helm && make lint
+        run: |
+          cd helm
+          make lint
+
   gen:
     name: "style/gen"
     timeout-minutes: 8
@@ -185,14 +210,21 @@ jobs:
           path: ${{ steps.go-cache-paths.outputs.go-mod }}
           key: ${{ github.job }}-go-mod-${{ hashFiles('**/go.sum') }}
 
-      - run: |
+      - name: Install sqlc
+        run: |
           curl -sSL https://github.com/kyleconroy/sqlc/releases/download/v1.13.0/sqlc_1.13.0_linux_amd64.tar.gz | sudo tar -C /usr/bin -xz sqlc
+      - name: Install protoc-gen-go
+        run: go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.26
+      - name: Install protoc-gen-go-drpc
+        run: go install storj.io/drpc/cmd/protoc-gen-go-drpc@v0.0.26
+      - name: Install goimports
+        run: go install golang.org/x/tools/cmd/goimports@latest
+
+      - name: make gen
+        run: "make --output-sync -j -B gen"
 
-      - run: go install google.golang.org/protobuf/cmd/protoc-gen-go@v1.26
-      - run: go install storj.io/drpc/cmd/protoc-gen-go-drpc@v0.0.26
-      - run: go install golang.org/x/tools/cmd/goimports@latest
-      - run: "make --output-sync -j -B gen"
-      - run: ./scripts/check_unstaged.sh
+      - name: Check for unstaged files
+        run: ./scripts/check_unstaged.sh
 
   style-fmt:
     name: "style/fmt"
@@ -222,7 +254,8 @@ jobs:
       - name: Install shfmt
         run: go install mvdan.cc/sh/v3/cmd/shfmt@v3.5.0
 
-      - run: |
+      - name: make fmt
+        run: |
           export PATH=${PATH}:$(go env GOPATH)/bin
           make --output-sync -j -B fmt
 
diff --git a/docs/install.md b/docs/install.md
@@ -103,6 +103,131 @@ grep /etc/group -e "docker"
 sudo systemctl restart coder.service
 ```
 
+## Kubernetes via Helm
+
+Before proceeding, please ensure that you have both Helm 3.5+ and the
+[latest version of Coder](https://github.com/coder/coder/releases) installed.
+You will also need to have a Kubernetes cluster running K8s 1.19+.
+
+> See our [Helm README](https://github.com/coder/coder/blob/main/helm#readme)
+> file for additional information. Check the
+> [values.yaml](https://github.com/coder/coder/blob/main/helm/values.yaml) file
+> for a list of supported Helm values and their defaults.
+
+> ⚠️ **Warning**: Helm support is new and not yet complete. There may be changes
+> to the Helm chart between releases which require manual values updates. Please
+> file an issue if you run into any issues.
+>
+> Additionally, the Helm chart does not currently automatically configure a
+> Service Account and workspace template for use in Coder. See
+> [#3265](https://github.com/coder/coder/issues/3265).
+
+1. Create a namespace for Coder, such as `coder`:
+
+    ```console
+    $ kubectl create namespace coder
+    ```
+
+1. Create a PostgreSQL deployment. Coder does not manage a database server for
+   you.
+
+    - If you're in a public cloud such as
+      [Google Cloud](https://cloud.google.com/sql/docs/postgres/),
+      [AWS](https://aws.amazon.com/rds/postgresql/),
+      [Azure](https://docs.microsoft.com/en-us/azure/postgresql/), or
+      [DigitalOcean](https://www.digitalocean.com/products/managed-databases-postgresql),
+      you can use the managed PostgreSQL offerings they provide. Make sure that
+      the PostgreSQL service is running and accessible from your cluster. It
+      should be in the same network, same project, etc.
+
+    - You can install Postgres manually on your cluster using the
+      [Bitnami PostgreSQL Helm chart](https://github.com/bitnami/charts/tree/master/bitnami/postgresql#readme). There are some
+      [helpful guides](https://phoenixnap.com/kb/postgresql-kubernetes) on the
+      internet that explain sensible configurations for this chart. Example:
+
+      ```console
+      $ helm repo add bitnami https://charts.bitnami.com/bitnami
+      $ helm install postgres bitnami/postgresql \
+          --namespace coder \
+          --set auth.username=coder \
+          --set auth.password=coder \
+          --set auth.database=coder \
+          --set persistence.size=10Gi
+      ```
+
+      The cluster-internal DB URL for the above database is:
+      ```
+      postgres://coder:coder@postgres-postgresql.coder.svc.cluster.local:5432/coder?sslmode=disable
+      ```
+
+      > Ensure you set up periodic backups so you don't lose data.
+
+    - You can use
+      [Postgres operator](https://github.com/zalando/postgres-operator) to
+      manage PostgreSQL deployments on your Kubernetes cluster.
+
+1. Download the latest `coder_helm` package from
+   [GitHub releases](https://github.com/coder/coder/releases).
+
+1. Create a `values.yaml` with the configuration settings you'd like for your
+   deployment. For example:
+
+    ```yaml
+    coder:
+      # You can specify any environment variables you'd like to pass to Coder
+      # here. Coder consumes environment variables listed in
+      # `coder server --help`, and these environment variables are also passed
+      # to the workspace provisioner (so you can consume them in your Terraform
+      # templates for auth keys etc.).
+      #
+      # Please keep in mind that you should not set `CODER_ADDRESS`,
+      # `CODER_TLS_ENABLE`, `CODER_TLS_CERT_FILE` or `CODER_TLS_KEY_FILE` as
+      # they are already set by the Helm chart and will cause conflicts.
+      env:
+        - name: CODER_ACCESS_URL
+          value: "https://coder.example.com"
+        - name: CODER_PG_CONNECTION_URL
+          valueFrom:
+            secretKeyRef:
+              # You'll need to create a secret called coder-db-url with your
+              # Postgres connection URL like:
+              # postgres://coder:password@postgres:5432/coder?sslmode=disable
+              name: coder-db-url
+              key: url
+
+      tls:
+        secretName: my-tls-secret-name
+    ```
+
+    > You can view our
+    > [Helm README](https://github.com/coder/coder/blob/main/helm#readme) for
+    > details on the values that are available, or you can view the
+    > [values.yaml](https://github.com/coder/coder/blob/main/helm/values.yaml)
+    > file directly.
+
+1. Run the following commands to install the chart in your cluster.
+
+    ```console
+    $ helm install coder ./coder_helm_x.y.z.tgz \
+        --namespace coder \
+        --values values.yaml
+    ```
+
+You can watch Coder start up by running `kubectl get pods`. Once Coder has
+started, the `coder-*` pods should enter the `Running` state.
+
+You can view Coder's logs by getting the pod name from `kubectl get pods` and
+then running `kubectl logs <pod name>`. You can also view these logs in your
+Cloud's log management system if you are using managed Kubernetes.
+
+To upgrade Coder in the future, you can run the following command with a new `coder_helm_x.y.z.tgz` file from GitHub releases:
+
+```console
+$ helm upgrade coder ./coder_helm_x.y.z.tgz \
+    --namespace coder \
+    -f values.yaml
+```
+
 ## Manual
 
 We publish self-contained .zip and .tar.gz archives in [GitHub releases](https://github.com/coder/coder/releases). The archives bundle `coder` binary.
diff --git a/helm/.helmignore b/helm/.helmignore
@@ -21,3 +21,4 @@
 .idea/
 *.tmproj
 .vscode/
+Makefile
diff --git a/helm/Makefile b/helm/Makefile
@@ -0,0 +1,18 @@
+# Use a single bash shell for each job, and immediately exit on failure
+SHELL := bash
+.SHELLFLAGS = -ceu
+.ONESHELL:
+
+# This doesn't work on directories.
+# See https://stackoverflow.com/questions/25752543/make-delete-on-error-for-directory-targets
+.DELETE_ON_ERROR:
+
+all: lint
+.PHONY: all
+
+lint: lint/helm
+.PHONY: lint
+
+lint/helm:
+	helm lint --strict .
+.PHONY: lint/helm
diff --git a/helm/README.md b/helm/README.md
@@ -0,0 +1,49 @@
+# Coder Helm Chart
+
+This directory contains the Helm chart used to deploy Coder onto a Kubernetes
+cluster. It contains the minimum required components to run Coder on Kubernetes,
+and notably (compared to Coder Classic) does not include a database server.
+
+## Getting Started
+
+> ⚠️ **Warning**: The main branch in this repository does not represent the
+> latest release of Coder. Please reference our installation docs for
+> instructions on a tagged release.
+
+View
+[our docs](https://coder.com/docs/coder-oss/latest/install#kubernetes-via-helm)
+for detailed installation instructions.
+
+## Values
+
+Please refer to [values.yaml](values.yaml) for available Helm values and their
+defaults.
+
+A good starting point for your values file is:
+
+```yaml
+coder:
+  # You can specify any environment variables you'd like to pass to Coder
+  # here. Coder consumes environment variables listed in
+  # `coder server --help`, and these environment variables are also passed
+  # to the workspace provisioner (so you can consume them in your Terraform
+  # templates for auth keys etc.).
+  #
+  # Please keep in mind that you should not set `CODER_ADDRESS`,
+  # `CODER_TLS_ENABLE`, `CODER_TLS_CERT_FILE` or `CODER_TLS_KEY_FILE` as
+  # they are already set by the Helm chart and will cause conflicts.
+  env:
+    - name: CODER_ACCESS_URL
+      value: "https://coder.example.com"
+    - name: CODER_PG_CONNECTION_URL
+      valueFrom:
+        secretKeyRef:
+          # You'll need to create a secret called coder-db-url with your
+          # Postgres connection URL like:
+          # postgres://coder:password@postgres:5432/coder?sslmode=disable
+          name: coder-db-url
+          key: url
+
+  tls:
+    secretName: my-tls-secret-name
+```
diff --git a/helm/values.yaml b/helm/values.yaml
@@ -19,18 +19,13 @@ coder:
   # coder.env -- The environment variables to set for Coder. These can be used
   # to configure all aspects of `coder server`. Please see `coder server --help`
   # for information about what environment variables can be set.
-  #
   # Note: The following environment variables are set by default and cannot be
   # overridden:
   # - CODER_ADDRESS: set to 0.0.0.0:80 and cannot be changed.
   # - CODER_TLS_ENABLE: set if tls.secretName is not empty.
   # - CODER_TLS_CERT_FILE: set if tls.secretName is not empty.
   # - CODER_TLS_KEY_FILE: set if tls.secretName is not empty.
-  env:
-    - name: CODER_ACCESS_URL
-      value: "https://coder.example.com"
-    #- name: CODER_PG_CONNECTION_URL
-    #  value: "postgres://coder:password@postgres:5432/coder?sslmode=disable"
+  env: []
 
   # coder.tls -- The TLS configuration for Coder.
   tls:
