Add automatic readme generation for charts (#5316)

* Add automatic readme generation for charts

The current readmes for each chart is generated
manually and doesn't contain all the information available.

Utilize helm-docs to automatically fill out readme.mds
for the helm charts by pulling metadata from values.yml.

Fixes #4156

Co-authored-by: GMarkfjard <gabma047@student.liu.se>

.github/workflows/static_checks.yml

@@ -83,3 +83,12 @@ jobs:
       uses: actions/checkout@722adc6
     - name: Markdown lint
       run: bin/markdownlint-all
+  chart_docs_diff:
+    name: Chart readme diff check
+    runs-on: ubuntu-18.04
+    steps:
+    - name: Checkout code
+      # actions/checkout@v2
+      uses: actions/checkout@722adc6
+    - name: Check docs for diff
+      run: bin/helm-docs-diff

.helmdocsignore

@@ -0,0 +1 @@
+# Add potential chart ignores here

BUILD.md

@@ -296,6 +296,46 @@ automatically regenerated with the command:
 go test ./cli/cmd/... --update
 ```
 
+#### Generating helm charts docs
+
+Whenever a new chart is created, or updated a readme should be generated from
+the chart's values.yml. This can be done by utilizing the bundled
+[helm-docs](https://github.com/norwoodj/helm-docs) binary. For adding additional
+information, such as specific installation instructions a readme template is
+required to be created. Check existing charts for example.
+
+##### Annotating values.yml
+
+To allow helm-docs to properly document the values in values.yml a descriptive
+comment is required. This can be done in two ways.
+Either comment the value directly above with
+`# -- This is a really nice value` where the double dashes automatically
+annotates the value. Another explicit usage is to type out the value name.
+`# global.MyNiceValue -- I really like this value`
+
+##### Using helm-docs
+
+Example usage:
+
+```sh
+bin/helm-docs
+bin/helm-docs --dry-run #Prints to cli instead
+bin/helm-docs --chart-search-root=./charts #Sets search root for charts
+bin/helm-docs --template-files=README.md.gotmpl #Sets the template file used
+```
+
+Note:
+The tool searches through the current directory and sub-directories by default.
+For additional information checkout their repo above.
+
+##### Markdown templates
+
+In order to accommodate for extra data that might not have a proper place in the
+´values.yaml´ file the corresponding ´README.md.gotmpl´ can be modified for each
+chart. This template allows the standard markdown syntax as well as the go
+templating functions. Checkout
+[helm-docs](https://github.com/norwoodj/helm-docs) for more info.
+
 ##### Pretty-printed diffs for templated text
 
 When running `go test`, mismatched text is usually displayed as a compact diff.

bin/helm-docs

@@ -0,0 +1,57 @@
+#!/usr/bin/env sh
+
+set -eu
+
+helmdocsv=1.4.0
+bindir=$( cd "${0%/*}" && pwd ) # Change to script dir and set bin dir to this
+targetbin=$( cd "$bindir"/.. && pwd )/target/bin
+helmdocsbin=$targetbin/helm-docs-$helmdocsv
+os=""
+arch=""
+
+if [ ! -f "$helmdocsbin" ]; then
+    case $(uname | tr '[:upper:]' '[:lower:]') in
+        darwin*)
+            os=darwin
+            arch=x86_64
+            ;;
+        linux*)
+            os=linux
+            case $(uname -m) in
+                x86_64) arch=x86_64 ;;
+                amd64) arch=amd64 ;;
+                arm)
+                    tmp=$(dpkg --print-architecture)
+                    if echo "$tmp" | grep -q arm64; then
+                        arch=arm64
+                    elif echo "$tmp" | grep -q armv7; then
+                        arch=armv7 
+                    elif echo "$tmp" | grep -q armv6; then
+                        arch=armv6
+                    fi
+                ;;
+            esac
+            ;;
+        msys*)
+            os=windows
+            arch=x86_64
+            ;;
+    esac
+
+    if [ -z "$os" ]; then
+        echo "Couldn't find a matching binary"
+        exit 126
+    fi
+    helmdocscurl="https://github.com/norwoodj/helm-docs/releases/download/v$helmdocsv/helm-docs_${helmdocsv}_${os}_${arch}.tar.gz"
+    tmp=$(mktemp -d -t helm-docs.XXX)
+    mkdir -p "$targetbin"
+    (
+        cd "$tmp"
+        curl -Lsf -o "./helm-docs.tar.gz" "$helmdocscurl"
+        tar zf "./helm-docs.tar.gz" -x "helm-docs"
+        chmod +x "helm-docs"
+    )
+    mv "$tmp/helm-docs" "$helmdocsbin"
+fi
+
+"$helmdocsbin" "$@"

bin/helm-docs-diff

@@ -0,0 +1,15 @@
+#!/usr/bin/env sh
+
+set -eu
+
+bin/helm-docs
+
+dir_dirty=$(git diff HEAD)
+if [ -z "$dir_dirty" ]; then
+  echo "Helm-docs generated readmes match chart readmes."
+  exit 0
+else
+  echo "Helm-docs generated readmes diverge from current chart readmes:"
+  echo "$(git status)"
+  exit 64
+fi

charts/add-ons/grafana/README.md

@@ -0,0 +1,28 @@
+# grafana
+
+A Helm chart for the grafana add-on in Linkerd
+
+![Version: 0.1.0](https://img.shields.io/badge/Version-0.1.0-informational?style=flat-square)
+
+![AppVersion: 1.0](https://img.shields.io/badge/AppVersion-1.0-informational?style=flat-square)
+
+## Requirements
+
+| Repository | Name | Version |
+|------------|------|---------|
+| file://../../partials | partials | 0.1.0 |
+
+## Values
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| image.name | string | `"ghcr.io/linkerd/grafana"` | Docker image name for the grafana instance |
+| image.tag | string | `nil` | Docker image tag for the grafana instance |
+| proxy.resources | string | `nil` | Structure analog to the resources fields above, but overriding the resources of the linkerd proxy injected into the grafana pod. |
+| resources.cpu.limit | string | `nil` | Maximum amount of CPU units that the grafana container can use |
+| resources.cpu.request | string | `nil` | Amount of CPU units that the grafana container requests |
+| resources.memory.limit | string | `nil` | Maximum amount of memory that grafana container can use |
+| resources.memory.request | string | `nil` | Amount of memory that the grafana container requests |
+
+----------------------------------------------
+Autogenerated from chart metadata using [helm-docs v1.4.0](https://github.com/norwoodj/helm-docs/releases/v1.4.0)

charts/add-ons/grafana/README.md.gotmpl

@@ -0,0 +1,14 @@
+{{ template "chart.header" . }}
+{{ template "chart.description" . }}
+
+{{ template "chart.versionBadge" . }}
+{{ template "chart.typeBadge" . }}
+{{ template "chart.appVersionBadge" . }}
+
+{{ template "chart.homepageLine" . }}
+
+{{ template "chart.requirementsSection" . }}
+
+{{ template "chart.valuesSection" . }}
+
+{{ template "helm-docs.versionFooter" . }}

charts/add-ons/grafana/values.yaml

@@ -1,2 +1,21 @@
 image:
+  # -- Docker image name for the grafana instance
   name: ghcr.io/linkerd/grafana
+  # -- Docker image tag for the grafana instance
+  tag:
+
+resources:
+  cpu:
+    # -- Maximum amount of CPU units that the grafana container can use
+    limit:
+    # -- Amount of CPU units that the grafana container requests
+    request:
+  memory:
+    # -- Maximum amount of memory that grafana container can use
+    limit:
+    # -- Amount of memory that the grafana container requests
+    request:
+proxy:
+  # -- Structure analog to the resources fields above, but overriding the
+  # resources of the linkerd proxy injected into the grafana pod.
+  resources:

charts/add-ons/prometheus/README.md

@@ -0,0 +1,35 @@
+# prometheus
+
+A Helm chart for the prometheus add-on in Linkerd
+
+![Version: 0.1.0](https://img.shields.io/badge/Version-0.1.0-informational?style=flat-square)
+
+![AppVersion: 1.0](https://img.shields.io/badge/AppVersion-1.0-informational?style=flat-square)
+
+## Requirements
+
+| Repository | Name | Version |
+|------------|------|---------|
+| file://../../partials | partials | 0.1.0 |
+
+## Values
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| alertManagers | string | `nil` | Alertmanager instances the Prometheus server sends alerts to configured via the static_configs parameter. |
+| alertRelabelConfigs | string | `nil` | Alert relabeling is applied to alerts before they are sent to the Alertmanager. |
+| args | object | `{"config.file":"/etc/prometheus/prometheus.yml","log.level":"info","storage.tsdb.path":"/data","storage.tsdb.retention.time":"6h"}` | Command line options for Prometheus binary |
+| globalConfig | object | `{"evaluation_interval":"10s","scrape_interval":"10s","scrape_timeout":"10s"}` | The global configuration specifies parameters that are valid in all other configuration contexts. |
+| image | string | `"prom/prometheus:v2.19.3"` | Docker image for the prometheus instance |
+| proxy.resources | string | `nil` | CPU and Memory resources required by proxy injected into prometheus pod (see global.proxy.resources for sub-fields) |
+| remoteWrite | string | `nil` | Allows transparently sending samples to an endpoint. Mostly used for long term storage. |
+| resources.cpu.limit | string | `nil` | Maximum amount of CPU units that the prometheus container can use |
+| resources.cpu.request | string | `nil` | Amount of CPU units that the prometheus container requests |
+| resources.memory.limit | string | `nil` | Maximum amount of memory that prometheus container can use |
+| resources.memory.request | string | `nil` | Amount of memory that the prometheus container requests |
+| ruleConfigMapMounts | string | `nil` | Alerting/recording rule ConfigMap mounts (sub-path names must end in ´_rules.yml´ or ´_rules.yaml´) |
+| scrapeConfigs | string | `nil` | A scrapeConfigs section specifies a set of targets and parameters describing how to scrape them. |
+| sideCarContainers | string | `nil` | A sidecarContainers section specifies a list of secondary containers to run in the prometheus pod e.g. to export data to non-prometheus systems |
+
+----------------------------------------------
+Autogenerated from chart metadata using [helm-docs v1.4.0](https://github.com/norwoodj/helm-docs/releases/v1.4.0)

charts/add-ons/prometheus/README.md.gotmpl

@@ -0,0 +1,14 @@
+{{ template "chart.header" . }}
+{{ template "chart.description" . }}
+
+{{ template "chart.versionBadge" . }}
+{{ template "chart.typeBadge" . }}
+{{ template "chart.appVersionBadge" . }}
+
+{{ template "chart.homepageLine" . }}
+
+{{ template "chart.requirementsSection" . }}
+
+{{ template "chart.valuesSection" . }}
+
+{{ template "helm-docs.versionFooter" . }}

charts/add-ons/prometheus/values.yaml

@@ -3,13 +3,121 @@
 # when installing with the parent linkerd2 chart
 # Do not override them in this file!
 # If installing/upgrading with linkerd's CLI, use the `--config` flag.
+
+# -- Docker image for the prometheus instance
 image: prom/prometheus:v2.19.3
+# -- Command line options for Prometheus binary
 args:
   storage.tsdb.path: /data
   storage.tsdb.retention.time: 6h
   config.file: /etc/prometheus/prometheus.yml
   log.level: info
+# -- The global configuration specifies parameters that are valid in all other
+# configuration contexts.
 globalConfig:
   scrape_interval: 10s
   scrape_timeout: 10s
   evaluation_interval: 10s
+
+# -- Alert relabeling is applied to alerts before they are sent to the
+# Alertmanager.
+alertRelabelConfigs:
+# Ex:
+# - action: labeldrop
+#   regex: prometheus_replica
+
+# -- Alertmanager instances the Prometheus server sends alerts to configured via
+# the static_configs parameter.
+alertManagers:
+# Ex:
+# - scheme: http
+#   static_configs:
+#   - targets:
+#     - "alertmanager.linkerd.svc:9093"
+
+# -- Allows transparently sending samples to an endpoint. Mostly used for long
+# term storage.
+remoteWrite:
+
+# -- Alerting/recording rule ConfigMap mounts (sub-path names must end in
+# ´_rules.yml´ or ´_rules.yaml´)
+ruleConfigMapMounts:
+# Ex:
+# - name: alerting-rules
+#   subPath: alerting_rules.yml
+#   configMap: linkerd-prometheus-rules
+# - name: recording-rules
+#   subPath: recording_rules.yml
+#   configMap: linkerd-prometheus-rules
+
+# -- A scrapeConfigs section specifies a set of targets and parameters
+# describing how to scrape them.
+scrapeConfigs:
+# Ex:
+# - job_name: 'kubernetes-nodes'
+#   scheme: https
+#   tls_config:
+#     ca_file: /var/run/secrets/kubernetes.io/serviceaccount/ca.crt
+#   bearer_token_file: /var/run/secrets/kubernetes.io/serviceaccount/token
+#   kubernetes_sd_configs:
+#   - role: node
+#   relabel_configs:
+#   - action: labelmap
+#     regex: __meta_kubernetes_node_label_(.+)
+
+# -- A sidecarContainers section specifies a list of secondary containers to run
+# in the prometheus pod e.g. to export data to non-prometheus systems
+sideCarContainers:
+# Ex:
+# - name: sidecar
+#   image: gcr.io/myproject/stackdriver-prometheus-sidecar
+#   imagePullPolicy: Always
+#   command:
+#   - /bin/sh
+#   - -c
+#   - |
+#     exec /bin/stackdriver-prometheus-sidecar \
+#       --stackdriver.project-id=myproject \
+#       --stackdriver.kubernetes.location=us-central1 \
+#       --stackdriver.kubernetes.cluster-name=mycluster \
+#       --prometheus.wal-directory=/data/wal \
+#       --log.level=info
+#   volumeMounts:
+#   - mountPath: /data
+#     name: data
+#   ports:
+#   - name: foo
+#     containerPort: 9091
+#     protocol: TCP
+
+
+proxy:
+  # -- CPU and Memory resources required by proxy injected into prometheus pod
+  # (see global.proxy.resources for sub-fields)
+  resources:
+
+### WARNING: persistence is experimental and has not been tested/vetted by the Linkerd team.
+### As such, please refer to https://linkerd.io/2/tasks/exporting-metrics/ for the recommended approach to metrics data retention.
+# if enabled, creates a persistent volume claim for prometheus data
+# https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims
+#persistence:
+# -- Storage class used to create prometheus data PV.
+#  storageClass:
+# -- PVC access mode.
+#  accessMode:
+# -- Prometheus data volume size.
+#  size:
+
+
+resources:
+  cpu:
+    # -- Maximum amount of CPU units that the prometheus container can use
+    limit:
+    # -- Amount of CPU units that the prometheus container requests
+    request:
+  memory:
+    # -- Maximum amount of memory that prometheus container can use
+    limit:
+    # -- Amount of memory that the prometheus container requests
+    request:
+