From 55890df6f12b22ea1249d6f3dbafa86d011556d0 Mon Sep 17 00:00:00 2001 From: Dean Sheather Date: Fri, 19 Aug 2022 02:41:23 +1000 Subject: [PATCH] feat: add helm README, install guide, linters (#3268) --- .github/workflows/coder.yaml | 47 +++++++++++-- docs/install.md | 125 +++++++++++++++++++++++++++++++++++ helm/.helmignore | 1 + helm/Makefile | 18 +++++ helm/README.md | 49 ++++++++++++++ helm/values.yaml | 7 +- 6 files changed, 234 insertions(+), 13 deletions(-) create mode 100644 helm/Makefile create mode 100644 helm/README.md diff --git a/.github/workflows/coder.yaml b/.github/workflows/coder.yaml index 733dd4d02c..56fac61ca0 100644 --- 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 - - 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: make gen + run: "make --output-sync -j -B gen" + + - 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 index d8318ceb23..f66a51e9d7 100644 --- 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 `. 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 index 0e8a0eb36f..c976b3b467 100644 --- a/helm/.helmignore +++ b/helm/.helmignore @@ -21,3 +21,4 @@ .idea/ *.tmproj .vscode/ +Makefile diff --git a/helm/Makefile b/helm/Makefile new file mode 100644 index 0000000000..2d88f4ff09 --- /dev/null +++ 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 new file mode 100644 index 0000000000..41732b5c67 --- /dev/null +++ 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 index 2090296dc4..b0a3468570 100644 --- 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: