Use helm-docs to auto-generate documentation for our chart

.github/workflows/update-docs-helm.yml

@@ -0,0 +1,64 @@
+name: Update docs for helm
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "deployment/**"
+jobs:
+  update-docs-helm:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    env:
+      HELM_DOCS_VERSION: 1.11.3
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v4
+        with:
+          go-version-file: "go.mod"
+
+      - name: install helm-docs
+        run: |
+          cd /tmp
+          wget https://github.com/norwoodj/helm-docs/releases/download/v${{env.HELM_DOCS_VERSION}}/helm-docs_${{env.HELM_DOCS_VERSION}}_Linux_x86_64.tar.gz
+          tar -xvf helm-docs_${{env.HELM_DOCS_VERSION}}_Linux_x86_64.tar.gz
+          sudo mv helm-docs /usr/local/sbin
+
+      - name: run helm-docs
+        run: |
+          make helm-docs
+
+      - name: Extract Commit SHA and Details
+        id: extract_commit_details
+        run: |
+          COMMIT_SHA="${{ github.sha }}"
+          COMMIT_DATE=$(git show -s --format=%cd --date=format:'%Y-%m-%d %H:%M:%S' $commit_sha)
+          COMMIT_AUTHOR=$(git show -s --format='%an' $commit_sha)
+          echo "commit_sha=$COMMIT_SHA" >> $GITHUB_OUTPUT
+          echo "commit_date=$COMMIT_DATE" >> $GITHUB_OUTPUT
+          echo "commit_author=$COMMIT_AUTHOR" >> $GITHUB_OUTPUT
+
+      - name: Commit and push changes
+        uses: peter-evans/create-pull-request@v5
+        with:
+          commit-message: Update helm documentation
+          committer: GitHub <noreply@github.com>
+          author: ${{ github.actor }} <${{ github.actor }}@users.noreply.github.com>
+          signoff: false
+          branch-suffix: timestamp
+          delete-branch: true
+          title: "Auto-generated helm documentation update - ${{ steps.extract_commit_details.outputs.commit_date }}"
+          body: |
+            ** Source commit **
+              - Commit SHA: [${{ steps.extract_commit_details.outputs.commit_sha }}](${{ github.server_url }}/${{ github.repository }}/commit/${{ steps.extract_commit_details.outputs.commit_sha}})
+            - Date: ${{ steps.extract_commit_details.outputs.commit_date }}
+            - Author: ${{ steps.extract_commit_details.outputs.commit_author }}
+          labels: |
+            docs
+            automated pr
+          draft: false

.mk/develop.mk

@@ -64,7 +64,8 @@ bootstrap: ## install build deps
 		github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-openapiv2 \
 			google.golang.org/protobuf/cmd/protoc-gen-go google.golang.org/grpc/cmd/protoc-gen-go-grpc \
 			github.com/pseudomuto/protoc-gen-doc/cmd/protoc-gen-doc \
-			github.com/sqlc-dev/sqlc
+			github.com/sqlc-dev/sqlc \
+			github.com/norwoodj/helm-docs/cmd/helm-docs
 	# Create a config.yaml if it doesn't exist
 	# TODO: remove this when all config is handled in internal/config
 	cp -n config/config.yaml.example ./config.yaml || echo "config.yaml already exists, not overwriting"

.mk/helm.mk

@@ -28,3 +28,8 @@ helm-template: ## renders the helm templates which is useful for debugging
 	cd deployment/helm; \
 		helm dependency update && \
 		helm template .
+
+.PHONY: helm-docs
+helm-docs: ## generate the helm docs
+	cd deployment/helm; \
+		helm-docs -t README.md.gotmpl -o README.md

deployment/helm/README.md

@@ -1,6 +1,10 @@
 # Helm charts for Minder server
 
-(These are a work in progress)
+![Version: 0.1.0](https://img.shields.io/badge/Version-0.1.0-informational?style=for-the-badge)
+![Type: application](https://img.shields.io/badge/Type-application-informational?style=for-the-badge)
+![AppVersion: 2023-07-31](https://img.shields.io/badge/AppVersion-2023--07--31-informational?style=for-the-badge)
+
+Deploy Minder on Kubernetes
 
 Stacklok runs Minder on Kubernetes, using these helm charts. In order to use
 these helm charts, you will need the following:
@@ -42,3 +46,46 @@ helm install minder config/helm/minder-0.1.0.tgz
 
 Note that the helm chart does not specify a namespace, so Minder will be
 installed in the namespace specified by your current Kubernetes context.
+
+## Values
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| aws.accountID | string | `"123456789012"` |  |
+| aws.migrate.iamRole | string | `"minder_migrate_role"` |  |
+| aws.server.iamRole | string | `"minder_server_role"` |  |
+| db.host | string | `"postgres.postgres"` |  |
+| deploymentSettings.extraVolumeMounts | string | `nil` |  |
+| deploymentSettings.extraVolumes | string | `nil` |  |
+| deploymentSettings.image | string | `"ko://github.com/stacklok/minder/cmd/server"` |  |
+| deploymentSettings.imagePullPolicy | string | `"IfNotPresent"` |  |
+| deploymentSettings.resources.limits.cpu | int | `4` |  |
+| deploymentSettings.resources.limits.memory | string | `"1.5Gi"` |  |
+| deploymentSettings.resources.requests.cpu | int | `1` |  |
+| deploymentSettings.resources.requests.memory | string | `"1Gi"` |  |
+| deploymentSettings.secrets.appSecretName | string | `"minder-github-secrets"` |  |
+| deploymentSettings.secrets.authSecretName | string | `"minder-auth-secrets"` |  |
+| deploymentSettings.secrets.identitySecretName | string | `"minder-identity-secrets"` |  |
+| deploymentSettings.sidecarContainers | string | `nil` |  |
+| extra_config | string | `"# Add content here\n"` |  |
+| extra_config_migrate | string | `"# Add even more content here\n"` |  |
+| hostname | string | `"minder.example.com"` |  |
+| hpaSettings.maxReplicas | int | `1` |  |
+| hpaSettings.metrics.cpu.targetAverageUtilization | int | `60` |  |
+| hpaSettings.minReplicas | int | `1` |  |
+| ingress.annotations | object | `{}` |  |
+| migrationSettings.extraVolumeMounts | string | `nil` |  |
+| migrationSettings.extraVolumes | string | `nil` |  |
+| migrationSettings.image | string | `"ko://github.com/stacklok/minder/cmd/server"` |  |
+| migrationSettings.imagePullPolicy | string | `"IfNotPresent"` |  |
+| migrationSettings.resources.limits.cpu | int | `1` |  |
+| migrationSettings.resources.limits.memory | string | `"300Mi"` |  |
+| migrationSettings.resources.requests.cpu | string | `"200m"` |  |
+| migrationSettings.resources.requests.memory | string | `"200Mi"` |  |
+| migrationSettings.sidecarContainers | string | `nil` |  |
+| service.grpcPort | int | `8090` |  |
+| service.httpPort | int | `8080` |  |
+| service.metricPort | int | `9090` |  |
+| serviceAccounts.migrate | string | `""` |  |
+| serviceAccounts.server | string | `""` |  |
+| trusty.endpoint | string | `"http://pi.pi:8000"` |  |

deployment/helm/README.md.gotmpl

@@ -0,0 +1,44 @@
+# Helm charts for Minder server
+
+![Version: {{ .Version }}](https://img.shields.io/badge/Version-{{ .Version | replace "-" "--" }}-informational?style=for-the-badge)
+{{ if .Type }}![Type: {{ .Type }}](https://img.shields.io/badge/Type-{{ .Type }}-informational?style=for-the-badge) {{ end }}
+{{ if .AppVersion }}![AppVersion: {{ .AppVersion }}](https://img.shields.io/badge/AppVersion-{{ .AppVersion | replace "-" "--" }}-informational?style=for-the-badge) {{ end }}
+
+{{ template "chart.description" . }}
+
+Stacklok runs Minder on Kubernetes, using these helm charts. In order to use
+these helm charts, you will need the following:
+
+- Postgres running in your cluster. In particular, you need a `postgres` Service
+  in the `postgres` Namespace. The [`k8s-dev-setup`](../k8s-dev-setup/)
+  directory has a sample postgres for local development and testing purposes.
+  Note that the Postgres in that setup is **NOT** durable.
+
+- The following Kubernetes secrets:
+
+  - `minder-github-secrets`: Needs to contain API credentials for a GitHub
+    app. In particular, the following keys are required:
+    - `client_id`: The GitHub client ID to be used by Minder
+    - `client_secret`: The GitHub client secret to be used by Minder
+
+  - `minder-identity-secrets`: Needs to contain the OAuth 2 client secret for Minder
+    server when authenticating with Keycloak. In particular, the following keys are required:
+    - `identity_client_secret`: The Keycloak client secret to be used by Minder server
+
+- In addition, if you are using Minder images which require authentication,
+  you will want to create a `docker-registry` type credential with the name
+  `minder-pull-secret`
+
+## Building and running
+
+You can build a (local) helm chart with `make helm` at the top-level of the
+Minder repository. You can then run it with:
+
+```helm
+helm install minder config/helm/minder-0.1.0.tgz
+```
+
+Note that the helm chart does not specify a namespace, so Minder will be
+installed in the namespace specified by your current Kubernetes context.
+
+{{ template "chart.valuesSection" . }}

tools/go.mod

@@ -11,6 +11,7 @@ require (
 	github.com/golangci/golangci-lint v1.55.2
 	github.com/gotesttools/gotestfmt/v2 v2.5.0
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.18.1
+	github.com/norwoodj/helm-docs v1.11.3
 	github.com/pseudomuto/protoc-gen-doc v1.5.1
 	github.com/sqlc-dev/sqlc v1.23.0
 	golang.org/x/lint v0.0.0-20210508222113-6edffad5e616
@@ -36,8 +37,11 @@ require (
 	github.com/BurntSushi/toml v1.3.2 // indirect
 	github.com/Djarvur/go-err113 v0.0.0-20210108212216-aea10b59be24 // indirect
 	github.com/GaijinEntertainment/go-exhaustruct/v3 v3.1.0 // indirect
+	github.com/Masterminds/goutils v1.1.1 // indirect
 	github.com/Masterminds/semver v1.5.0 // indirect
+	github.com/Masterminds/semver/v3 v3.1.1 // indirect
 	github.com/Masterminds/sprig v2.15.0+incompatible // indirect
+	github.com/Masterminds/sprig/v3 v3.2.2 // indirect
 	github.com/Microsoft/go-winio v0.6.1 // indirect
 	github.com/OpenPeeDeeP/depguard/v2 v2.1.0 // indirect
 	github.com/alecthomas/go-check-sumtype v0.1.3 // indirect
@@ -87,7 +91,7 @@ require (
 	github.com/fatih/structtag v1.2.0 // indirect
 	github.com/felixge/fgprof v0.9.3 // indirect
 	github.com/firefart/nonamedreturns v1.0.4 // indirect
-	github.com/fsnotify/fsnotify v1.5.4 // indirect
+	github.com/fsnotify/fsnotify v1.6.0 // indirect
 	github.com/fzipp/gocyclo v0.6.0 // indirect
 	github.com/ghostiam/protogetter v0.2.3 // indirect
 	github.com/go-chi/chi/v5 v5.0.10 // indirect
@@ -132,8 +136,8 @@ require (
 	github.com/hashicorp/go-version v1.6.0 // indirect
 	github.com/hashicorp/hcl v1.0.0 // indirect
 	github.com/hexops/gotextdiff v1.0.3 // indirect
-	github.com/huandu/xstrings v1.0.0 // indirect
-	github.com/imdario/mergo v0.3.4 // indirect
+	github.com/huandu/xstrings v1.3.1 // indirect
+	github.com/imdario/mergo v0.3.11 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20221227161230-091c0ba34f0a // indirect
@@ -158,7 +162,7 @@ require (
 	github.com/leonklingele/grouper v1.1.1 // indirect
 	github.com/lufeee/execinquery v1.2.1 // indirect
 	github.com/macabu/inamedparam v0.1.2 // indirect
-	github.com/magiconair/properties v1.8.6 // indirect
+	github.com/magiconair/properties v1.8.7 // indirect
 	github.com/maratori/testableexamples v1.0.0 // indirect
 	github.com/maratori/testpackage v1.1.1 // indirect
 	github.com/matoous/godox v0.0.0-20230222163458-006bad1f9d26 // indirect
@@ -169,8 +173,10 @@ require (
 	github.com/matttproud/golang_protobuf_extensions v1.0.1 // indirect
 	github.com/mbilski/exhaustivestruct v1.2.0 // indirect
 	github.com/mgechev/revive v1.3.4 // indirect
+	github.com/mitchellh/copystructure v1.0.0 // indirect
 	github.com/mitchellh/go-homedir v1.1.0 // indirect
 	github.com/mitchellh/mapstructure v1.5.0 // indirect
+	github.com/mitchellh/reflectwalk v1.0.0 // indirect
 	github.com/moby/term v0.5.0 // indirect
 	github.com/moricho/tparallel v0.3.1 // indirect
 	github.com/morikuni/aec v1.0.0 // indirect
@@ -182,8 +188,7 @@ require (
 	github.com/olekukonko/tablewriter v0.0.5 // indirect
 	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/opencontainers/image-spec v1.1.0-rc5 // indirect
-	github.com/pelletier/go-toml v1.9.5 // indirect
-	github.com/pelletier/go-toml/v2 v2.0.5 // indirect
+	github.com/pelletier/go-toml/v2 v2.0.8 // indirect
 	github.com/pganalyze/pg_query_go/v4 v4.2.3 // indirect
 	github.com/pingcap/errors v0.11.5-0.20210425183316-da1aaba5fb63 // indirect
 	github.com/pingcap/failpoint v0.0.0-20220801062533-2eaa32854a6c // indirect
@@ -195,7 +200,7 @@ require (
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/polyfloyd/go-errorlint v1.4.5 // indirect
 	github.com/prometheus/client_golang v1.12.1 // indirect
-	github.com/prometheus/client_model v0.2.0 // indirect
+	github.com/prometheus/client_model v0.3.0 // indirect
 	github.com/prometheus/common v0.32.1 // indirect
 	github.com/prometheus/procfs v0.7.3 // indirect
 	github.com/pseudomuto/protokit v0.2.0 // indirect
@@ -214,24 +219,25 @@ require (
 	github.com/sashamelentyev/usestdlibvars v1.24.0 // indirect
 	github.com/securego/gosec/v2 v2.18.2 // indirect
 	github.com/shazow/go-diff v0.0.0-20160112020656-b6b7b6733b8c // indirect
+	github.com/shopspring/decimal v1.2.0 // indirect
 	github.com/sirupsen/logrus v1.9.3 // indirect
 	github.com/sivchari/containedctx v1.0.3 // indirect
 	github.com/sivchari/nosnakecase v1.7.0 // indirect
 	github.com/sivchari/tenv v1.7.1 // indirect
 	github.com/sonatard/noctx v0.0.2 // indirect
 	github.com/sourcegraph/go-diff v0.7.0 // indirect
-	github.com/spf13/afero v1.8.2 // indirect
-	github.com/spf13/cast v1.5.0 // indirect
+	github.com/spf13/afero v1.9.5 // indirect
+	github.com/spf13/cast v1.5.1 // indirect
 	github.com/spf13/cobra v1.8.0 // indirect
 	github.com/spf13/jwalterweatherman v1.1.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
-	github.com/spf13/viper v1.12.0 // indirect
+	github.com/spf13/viper v1.16.0 // indirect
 	github.com/ssgreg/nlreturn/v2 v2.2.1 // indirect
 	github.com/stbenjam/no-sprintf-host-port v0.1.1 // indirect
 	github.com/stoewer/go-strcase v1.3.0 // indirect
 	github.com/stretchr/objx v0.5.0 // indirect
 	github.com/stretchr/testify v1.8.4 // indirect
-	github.com/subosito/gotenv v1.4.1 // indirect
+	github.com/subosito/gotenv v1.4.2 // indirect
 	github.com/t-yuki/gocover-cobertura v0.0.0-20180217150009-aaee18c8195c // indirect
 	github.com/tdakkota/asciicheck v0.2.0 // indirect
 	github.com/tetafro/godot v1.4.15 // indirect
@@ -276,6 +282,7 @@ require (
 	gopkg.in/yaml.v2 v2.4.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 	honnef.co/go/tools v0.4.6 // indirect
+	k8s.io/helm v2.14.3+incompatible // indirect
 	mvdan.cc/interfacer v0.0.0-20180901003855-c20040233aed // indirect
 	mvdan.cc/lint v0.0.0-20170908181259-adc824a0674b // indirect
 	mvdan.cc/unparam v0.0.0-20221223090309-7455f1af531d // indirect