feat(helm-charts-docs) Automatic readme generation for chart (bp #1209)…

… (#1274)

* feat(kuma-cp) automatic readme generation for chart (#1209)

Co-authored-by: Tharun Rajendran <[email protected]>
Co-authored-by: Nikolay Nikolaev <[email protected]>

deployments/charts/kuma/.helmdocsignore

@@ -0,0 +1 @@
+# Charts to ignore from helm-docs

deployments/charts/kuma/README.md.gotmpl

@@ -0,0 +1,40 @@
+[![][kuma-logo]][kuma-url]
+
+{{ template "chart.description" . }}
+
+{{ template "chart.typeBadge" . }}{{ template "chart.versionBadge" . }}{{ template "chart.appVersionBadge" . }}
+
+{{ template "chart.homepageLine" . }}
+
+{{ template "chart.valuesSection" . }}
+
+## Custom Resource Definitions
+
+All Kuma CRDs are loaded via the [`crds`](crds) directory. For more detailed information on CRDs and Helm,
+please refer to [the Helm documentation][helm-crd].
+
+## Deleting
+
+As part of [Helm's limitations][helm-crd-limitations], CRDs will not be deleted when the `kuma` chart is deleted and
+must be deleted manually. When a CRD is deleted Kubernetes deletes all resources of that kind as well, so this should
+be done carefully.
+
+To do this with `kubectl` on *nix platforms, run:
+
+```shell
+kubectl get crds | grep kuma.io | tr -s " " | cut -d " " -f1 | xargs kubectl delete crd
+
+# or with jq
+kubectl get crds -o json | jq '.items[].metadata.name | select(.|test(".*kuma\\.io"))' | xargs kubectl delete crd
+```
+
+## Note to Chart developers
+
+The charts are used internally in `kumactl install`, therefore the following rules apply when developing new chat features:
+ * use `make generate/kumactl/install/k8s/control-plane` to sync the Helm Chart and `kumactl install` templates
+ * all templates that start with `pre-` and `post-` are omitted when processing in `kumactl install`
+
+[kuma-url]: https://kuma.io/
+[kuma-logo]: https://kuma-public-assets.s3.amazonaws.com/kuma-logo-v2.png
+[helm-crd]: https://helm.sh/docs/chart_best_practices/custom_resource_definitions/
+[helm-crd-limitations]: https://helm.sh/docs/topics/charts/#limitations-on-crds

deployments/charts/kuma/values.yaml

@@ -1,40 +1,47 @@
-# The default registry and tag to use for all Kuma images
 global:
   image:
+    # -- Default registry for all Kuma Images
     registry: "kong-docker-kuma-docker.bintray.io"
     # Defaults to .Chart.AppVersion
     # tag: ""
 
-# Whether or not to patch the target namespace with the system label
+# -- Whether or not to patch the target namespace with the system label
 patchSystemNamespace: true
 
 controlPlane:
+  # -- Kuma CP log level: one of off,info,debug
   logLevel: "info"
+  # -- Kuma CP modes: one of standalone,remote,global
   mode: "standalone"
   # zone: ""
 
   kdsGlobalAddress: ""
-
+  # -- Number of replicas of the Kuma CP
   replicas: 1
-
+  # -- Node selector for the Kuma Control Plane pods
   nodeSelector:
     kubernetes.io/os: linux
     kubernetes.io/arch: amd64
-
+  # -- Failure policy of the mutating webhook implemented by the Kuma Injector component
   injectorFailurePolicy: Ignore
 
   service:
-    # name: ""
-    type: ClusterIP
+    # -- Service type of the Kuma Control Plane
+    type:
+      ClusterIP
+      # -- Additional annotations to put on the Kuma Control Plane
     annotations: {}
-
+  # -- URL of Global Kuma CP
   globalRemoteSyncService:
-    # name: ""
+    # -- Service type of the Global-Remote sync
     type: LoadBalancer
+    # -- Additional annotations to put on the Global Remote Sync Service
     annotations: {}
+    # -- Port on which Global Remote Sync Service is exposed
     port: 5685
 
   defaults:
+    # -- Whether or not to skip creating the default Mesh
     skipMeshCreation: false
 
   #  resources:
@@ -45,61 +52,83 @@ controlPlane:
   # TLS for various servers
   tls:
     general:
+      # -- Secret that contains tls.crt, key.crt and ca.crt for protecting Kuma in-cluster communication
       secretName: ""
+      # -- Base64 encoded CA certificate (the same as in controlPlane.tls.general.secret#ca.crt)
       caBundle: ""
     apiServer:
+      # -- Secret that contains tls.crt, key.crt for protecting Kuma API on HTTPS
       secretName: ""
+      # -- Secret that contains list of .pem certificates that can access admin endpoints of Kuma API on HTTPS
       clientCertsSecretName: ""
     kdsGlobalServer:
+      # -- Secret that contains tls.crt, key.crt for protecting cross cluster communication
       secretName: ""
     kdsRemoteClient:
+      # -- Secret that contains ca.crt which was used to sign KDS Global server. Used for CP verification
       secretName: ""
 
   image:
+    # -- Kuma CP ImagePullPolicy
     pullPolicy: IfNotPresent
+    # -- Kuma CP image repository
     repository: "kuma-cp"
   # secrets: {}
 
+  # -- Additional environment variables that will be passed to the control plane
   envVars: {}
 
-#  config: |
-#    xdsServer:
-#      dataplaneConfigurationRefreshInterval: 2s
-
 cni:
+  # -- Install Kuma with CNI instead of proxy init container
   enabled: false
+  # -- Install CNI in chained mode
   chained: false
+  # -- Set the CNI install directory
   netDir: /etc/cni/multus/net.d
+  # -- Set the CNI bin directory
   binDir: /var/lib/cni/bin
+  # -- Set the CNI configuration name
   confName: kuma-cni.conf
+  # -- CNI log level: one of off,info,debug
   logLevel: info
-
+  # -- Node Selector for the CNI pods
   nodeSelector:
     kubernetes.io/os: linux
     kubernetes.io/arch: amd64
 
   image:
-    registry: "docker.io"
+    # -- CNI image registry
+    registry:
+      "docker.io"
+      # -- CNI image repository
     repository: "lobkovilya/install-cni"
+    # -- CNI image tag
     tag: "0.0.2"
 
-# Configuration for the kuma dataplane sidecar
 dataPlane:
   image:
+    # -- The Kuma DP image repository
     repository: "kuma-dp"
+    # -- Kuma DP ImagePullPolicy
     pullPolicy: IfNotPresent
 
-  # Configuration for the kuma init phase in the sidecar
   initImage:
+    # -- The Kuma DP init image repository
     repository: "kuma-init"
 
 ingress:
+  # -- If true, it deploys Ingress for cross cluster communication
   enabled: false
+  # -- Mesh to which Dataplane Ingress belongs to
   mesh: default
+  # -- Time for which old listener will still be active as draining
   drainTime: 30s
+  # -- Number of replicas of the Ingress
   replicas: 1
   service:
-    # name: ""
+    # -- Service type of the Ingress
     type: LoadBalancer
+    # -- Additional annotations to put on the Ingress service
     annotations: {}
+    # -- Port on which Ingress is exposed
     port: 10001

mk/check.mk

@@ -45,7 +45,11 @@ helm-lint:
 imports: ## Dev: Runs goimports in order to organize imports
 	goimports -w -local github.com/kumahq/kuma -d `find . -type f -name '*.go' -not -name '*.pb.go' -not -path './vendored/*'`
 
+.PHONY: helm-docs
+helm-docs: ## Dev: Runs helm-docs generator
+	$(HELM_DOCS_PATH) -s="file" --chart-search-root=./deployments/charts
+
 .PHONY: check
-check: generate fmt vet docs helm-lint golangci-lint imports tidy ## Dev: Run code checks (go fmt, go vet, ...)
+check: generate fmt vet docs helm-lint golangci-lint imports tidy helm-docs ## Dev: Run code checks (go fmt, go vet, ...)
 	$(MAKE) generate manifests -C pkg/plugins/resources/k8s/native
 	git diff --quiet || test $$(git diff --name-only | grep -v -e 'go.mod$$' -e 'go.sum$$' | wc -l) -eq 0 || ( echo "The following changes (result of code generators and code checks) have been detected:" && git --no-pager diff && false ) # fail if Git working tree is dirty

mk/dev.mk

@@ -3,6 +3,7 @@ PROTOC_PGV_VERSION := v0.3.0-java.0.20200311152155-ab56c3dd1cf9
 GOLANG_PROTOBUF_VERSION := v1.3.2
 GOLANGCI_LINT_VERSION := v1.31.0
 GINKGO_VERSION := v1.12.0
+HELM_DOCS_VERSION := 1.4.0
 
 CI_KUBEBUILDER_VERSION ?= 2.3.1
 CI_MINIKUBE_VERSION ?= v1.13.1
@@ -24,13 +25,15 @@ KUBECTL_PATH := $(CI_TOOLS_DIR)/kubectl
 KUBE_APISERVER_PATH := $(CI_TOOLS_DIR)/kube-apiserver
 ETCD_PATH := $(CI_TOOLS_DIR)/etcd
 GOLANGCI_LINT_DIR := $(CI_TOOLS_DIR)
+HELM_DOCS_PATH := $(CI_TOOLS_DIR)/helm-docs
 
 TOOLS_DIR ?= $(shell pwd)/tools
 
 PROTOC_OS=unknown
 PROTOC_ARCH=$(shell uname -m)
 
 UNAME_S := $(shell uname -s)
+UNAME_ARCH := $(shell uname -m)
 ifeq ($(UNAME_S), Linux)
 	PROTOC_OS=linux
 else
@@ -50,7 +53,8 @@ dev/tools/all: dev/install/protoc dev/install/protobuf-wellknown-types \
 	dev/install/kubectl dev/install/kind dev/install/minikube \
 	dev/install/golangci-lint \
 	dev/install/goimports \
-	dev/install/helm3
+	dev/install/helm3 \
+	dev/install/helm-docs
 
 .PHONY: dev/install/protoc
 dev/install/protoc: ## Bootstrap: Install Protoc (protobuf compiler)
@@ -182,6 +186,21 @@ dev/install/goimports: ## Bootstrap: Install goimports
 dev/install/helm3: ## Bootstrap: Install Helm 3
 	curl https://raw.githubusercontent.com/helm/helm/master/scripts/get-helm-3 | bash
 
+.PHONY: dev/install/helm-docs
+dev/install/helm-docs: ## Bootstrap: Install helm-docs
+	@if [ -e $(HELM_DOCS_PATH) ]; then echo "Helm Docs $$( $(HELM_DOCS_PATH) --version ) is already installed at $(HELM_DOCS_PATH)" ; fi
+	@if [ ! -e $(HELM_DOCS_PATH) ]; then \
+		echo "Installing helm-docs ...." \
+		&& set -x \
+		&& curl -Lo helm-docs_$(HELM_DOCS_VERSION)_$(UNAME_S)_$(UNAME_ARCH).tar.gz https://github.com/norwoodj/helm-docs/releases/download/v$(HELM_DOCS_VERSION)/helm-docs_$(HELM_DOCS_VERSION)_$(UNAME_S)_$(UNAME_ARCH).tar.gz \
+		&& tar -xf helm-docs_$(HELM_DOCS_VERSION)_$(UNAME_S)_$(UNAME_ARCH).tar.gz helm-docs \
+		&& rm helm-docs_$(HELM_DOCS_VERSION)_$(UNAME_S)_$(UNAME_ARCH).tar.gz \
+		&& chmod +x helm-docs \
+		&& mkdir -p $(CI_TOOLS_DIR) \
+		&& mv helm-docs $(HELM_DOCS_PATH) \
+		&& set +x \
+		&& echo "helm-docs $(HELM_DOCS_VERSION) has been installed at $(HELM_DOCS_PATH)" ; fi
+
 GEN_CHANGELOG_START_TAG ?= 1.0.0
 GEN_CHANGELOG_BRANCH ?= release-1.0
 GEN_CHANGELOG_MD ?= changelog.generated.md