Merge pull request #957 from rexagod/md

chore: add markdown linter and formatter
kubernetes-monitoring · Jul 18, 2024 · 8174ed9 · 8174ed9
2 parents 2640a3e + f9c8a99
commit 8174ed9
Show file tree

Hide file tree

Showing 10 changed files with 368 additions and 178 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -18,6 +18,10 @@ jobs:
             run: make --always-make dashboards-lint
           - name: Jsonnet formatter
             run: make --always-make fmt && git diff --exit-code
+          - name: Markdown formatter
+            run: make --always-make markdownfmt && git diff --exit-code
+          - name: Markdown linter
+            run: make --always-make vale && git diff --exit-code
           - name: Jsonnet linter
             run: make --always-make jsonnet-lint
           - name: Unit tests

diff --git a/.gitignore b/.gitignore
@@ -4,3 +4,4 @@ dashboards_out
 vendor
 jsonnetfile.lock.json
 tmp
+.vale
diff --git a/.vale.ini b/.vale.ini
@@ -0,0 +1,8 @@
+StylesPath = .vale/styles
+
+MinAlertLevel = error
+
+Packages = Readability, write-good, alex
+
+[*]
+BasedOnStyles = Readability, write-good, alex
diff --git a/DESIGN.md b/DESIGN.md
diff --git a/Makefile b/Makefile
@@ -6,8 +6,11 @@ JB_BIN=$(BIN_DIR)/jb
 JSONNET_BIN=$(BIN_DIR)/jsonnet
 JSONNETLINT_BIN=$(BIN_DIR)/jsonnet-lint
 JSONNETFMT_BIN=$(BIN_DIR)/jsonnetfmt
+MD_FILES = $(shell find . \( -type d -name '.vale' -o -type d -name 'vendor' \) -prune -o -type f -name "*.md" -print)
+MARKDOWNFMT_BIN=$(BIN_DIR)/markdownfmt
+VALE_BIN=$(BIN_DIR)/vale
 PROMTOOL_BIN=$(BIN_DIR)/promtool
-TOOLING=$(JB_BIN) $(JSONNETLINT_BIN) $(JSONNET_BIN) $(JSONNETFMT_BIN) $(PROMTOOL_BIN) $(GRAFANA_DASHBOARD_LINTER_BIN)
+TOOLING=$(JB_BIN) $(JSONNETLINT_BIN) $(JSONNET_BIN) $(JSONNETFMT_BIN) $(PROMTOOL_BIN) $(GRAFANA_DASHBOARD_LINTER_BIN) $(MARKDOWNFMT_BIN) $(VALE_BIN)
 JSONNETFMT_ARGS=-n 2 --max-blank-lines 2 --string-style s --comment-style s
 SRC_DIR ?=dashboards
 OUT_DIR ?=dashboards_out
@@ -22,10 +25,14 @@ $(JSONNET_VENDOR): $(JB_BIN) jsonnetfile.json
 	$(JB_BIN) install
 
 .PHONY: fmt
-fmt: $(JSONNETFMT_BIN)
-	find . -name 'vendor' -prune -o -name '*.libsonnet' -print -o -name '*.jsonnet' -print | \
+fmt: $(JSONNETFMT_BIN) markdownfmt
+	@find . -name 'vendor' -prune -o -name '*.libsonnet' -print -o -name '*.jsonnet' -print | \
 		xargs -n 1 -- $(JSONNETFMT_BIN) $(JSONNETFMT_ARGS) -i
 
+.PHONY: markdownfmt
+markdownfmt: $(MARKDOWNFMT_BIN)
+	@for file in $(MD_FILES); do $(MARKDOWNFMT_BIN) -w -gofmt $$file; done
+
 prometheus_alerts.yaml: $(JSONNET_BIN) mixin.libsonnet lib/alerts.jsonnet alerts/*.libsonnet
 	@$(JSONNET_BIN) -J vendor -S lib/alerts.jsonnet > $@
 
@@ -37,14 +44,13 @@ $(OUT_DIR): $(JSONNET_BIN) $(JSONNET_VENDOR) mixin.libsonnet lib/dashboards.json
 	@$(JSONNET_BIN) -J vendor -m $(OUT_DIR) lib/dashboards.jsonnet
 
 .PHONY: lint
-lint: jsonnet-lint alerts-lint dashboards-lint
+lint: jsonnet-lint alerts-lint dashboards-lint vale
 
 .PHONY: jsonnet-lint
 jsonnet-lint: $(JSONNETLINT_BIN) $(JSONNET_VENDOR)
 	@find . -name 'vendor' -prune -o -name '*.libsonnet' -print -o -name '*.jsonnet' -print | \
 		xargs -n 1 -- $(JSONNETLINT_BIN) -J vendor
 
-
 .PHONY: alerts-lint
 alerts-lint: $(PROMTOOL_BIN) prometheus_alerts.yaml prometheus_rules.yaml
 	@$(PROMTOOL_BIN) check rules prometheus_rules.yaml
@@ -59,6 +65,11 @@ dashboards-lint: $(GRAFANA_DASHBOARD_LINTER_BIN) $(OUT_DIR)/.lint
 	@sed -i -e 's/$$interval:$$resolution/$$__rate_interval/g' $(OUT_DIR)/*.json
 	@find $(OUT_DIR) -name '*.json' -print0 | xargs -n 1 -0 $(GRAFANA_DASHBOARD_LINTER_BIN) lint --strict
 
+.PHONY: vale
+vale: $(VALE_BIN)
+	@echo $(MD_FILES)
+	@$(VALE_BIN) sync && \
+		$(VALE_BIN) $(MD_FILES)
 
 .PHONY: clean
 clean:

diff --git a/README.md b/README.md
@@ -1,4 +1,5 @@
 # Prometheus Monitoring Mixin for Kubernetes
+
 [![ci](https://github.com/kubernetes-monitoring/kubernetes-mixin/actions/workflows/ci.yaml/badge.svg)](https://github.com/kubernetes-monitoring/kubernetes-mixin/actions/workflows/ci.yaml)
 
 > NOTE: This project is *pre-release* stage. Flags, configuration, behaviour and design may change significantly in following releases.
@@ -7,24 +8,23 @@ A set of Grafana dashboards and Prometheus alerts for Kubernetes.
 
 ## Releases
 
-| Release branch | Kubernetes Compatibility   | Prometheus Compatibility | Kube-state-metrics Compatibility |
-| -------------- | -------------------------- | ------------------------ | -------------------------------- |
-| release-0.1  | v1.13 and before   |           |       |
-| release-0.2  | v1.14.1 and before | v2.11.0+  |       |
-| release-0.3  | v1.17 and before   | v2.11.0+  |       |
-| release-0.4  | v1.18              | v2.11.0+  |       |
-| release-0.5  | v1.19              | v2.11.0+  |       |
-| release-0.6  | v1.19+             | v2.11.0+  |       |
-| release-0.7  | v1.19+             | v2.11.0+  | v1.x  |
-| release-0.8  | v1.20+             | v2.11.0+  | v2.0+ |
-| release-0.9  | v1.20+             | v2.11.0+  | v2.0+ |
-| release-0.10 | v1.20+             | v2.11.0+  | v2.0+ |
-| release-0.11 | v1.23+             | v2.11.0+  | v2.0+ |
-| release-0.12 | v1.23+             | v2.11.0+  | v2.0+ |
-| master       | v1.26+             | v2.11.0+  | v2.0+ |
-
-In Kubernetes 1.14 there was a major [metrics overhaul](https://github.com/kubernetes/enhancements/issues/1206) implemented.
-Therefore v0.1.x of this repository is the last release to support Kubernetes 1.13 and previous version on a best effort basis.
+| Release branch | Kubernetes Compatibility | Prometheus Compatibility | Kube-state-metrics Compatibility |
+|----------------|--------------------------|--------------------------|----------------------------------|
+| release-0.1    | v1.13 and before         |                          |                                  |
+| release-0.2    | v1.14.1 and before       | v2.11.0+                 |                                  |
+| release-0.3    | v1.17 and before         | v2.11.0+                 |                                  |
+| release-0.4    | v1.18                    | v2.11.0+                 |                                  |
+| release-0.5    | v1.19                    | v2.11.0+                 |                                  |
+| release-0.6    | v1.19+                   | v2.11.0+                 |                                  |
+| release-0.7    | v1.19+                   | v2.11.0+                 | v1.x                             |
+| release-0.8    | v1.20+                   | v2.11.0+                 | v2.0+                            |
+| release-0.9    | v1.20+                   | v2.11.0+                 | v2.0+                            |
+| release-0.10   | v1.20+                   | v2.11.0+                 | v2.0+                            |
+| release-0.11   | v1.23+                   | v2.11.0+                 | v2.0+                            |
+| release-0.12   | v1.23+                   | v2.11.0+                 | v2.0+                            |
+| master         | v1.26+                   | v2.11.0+                 | v2.0+                            |
+
+In Kubernetes 1.14 there was a major [metrics overhaul](https://github.com/kubernetes/enhancements/issues/1206) implemented. Therefore v0.1.x of this repository is the last release to support Kubernetes 1.13 and previous version on a best effort basis.
 
 Some alerts now use Prometheus filters made available in Prometheus 2.11.0, which makes this version of Prometheus a dependency.
 
@@ -34,18 +34,16 @@ Warning: By default the expressions will generate *grafana 7.2+* compatible rule
 
 ## How to use
 
-This mixin is designed to be vendored into the repo with your infrastructure config.
-To do this, use [jsonnet-bundler](https://github.com/jsonnet-bundler/jsonnet-bundler):
+This mixin is designed to be vendored into the repo with your infrastructure config. To do this, use [jsonnet-bundler](https://github.com/jsonnet-bundler/jsonnet-bundler):
 
 You then have three options for deploying your dashboards
 1. Generate the config files and deploy them yourself
-1. Use ksonnet to deploy this mixin along with Prometheus and Grafana
-1. Use prometheus-operator to deploy this mixin (TODO)
+2. Use ksonnet to deploy this mixin along with Prometheus and Grafana
+3. Use prometheus-operator to deploy this mixin (TODO)
 
 ## Generate config files
 
-You can manually generate the alerts, dashboards and rules files, but first you
-must install some tools:
+You can manually generate the alerts, dashboards and rules files, but first you must install some tools:
 
 ```
 $ go install github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb@latest
@@ -68,13 +66,11 @@ $ make prometheus_rules.yaml
 $ make dashboards_out
 ```
 
-The `prometheus_alerts.yaml` and `prometheus_rules.yaml` file then need to passed
-to your Prometheus server, and the files in `dashboards_out` need to be imported
-into you Grafana server.  The exact details will depending on how you deploy your
-monitoring stack to Kubernetes.
+The `prometheus_alerts.yaml` and `prometheus_rules.yaml` file then need to passed to your Prometheus server, and the files in `dashboards_out` need to be imported into you Grafana server. The exact details will depending on how you deploy your monitoring stack to Kubernetes.
 
 ### Dashboards for Windows Nodes
-There are separate dashboards for windows resources.
+
+There exist separate dashboards for windows resources.
 1) Compute Resources / Cluster(Windows)
 2) Compute Resources / Namespace(Windows)
 3) Compute Resources / Pod(Windows)
@@ -91,10 +87,7 @@ make test
 
 ## Using with prometheus-ksonnet
 
-Alternatively you can also use the mixin with
-[prometheus-ksonnet](https://github.com/kausalco/public/tree/master/prometheus-ksonnet),
-a [ksonnet](https://github.com/ksonnet/ksonnet) module to deploy a fully-fledged
-Prometheus-based monitoring system for Kubernetes:
+Alternatively you can also use the mixin with [prometheus-ksonnet](https://github.com/kausalco/public/tree/master/prometheus-ksonnet), a [ksonnet](https://github.com/ksonnet/ksonnet) module to deploy a fully-fledged Prometheus-based monitoring system for Kubernetes:
 
 Make sure you have the ksonnet v0.8.0:
 
@@ -115,8 +108,7 @@ $ cd <application name>
 $ ks env add default
 ```
 
-Grab the kubernetes-jsonnet module using and its dependencies, which include
-the kubernetes-mixin:
+Grab the kubernetes-jsonnet module using and its dependencies, which include the kubernetes-mixin:
 
 ```
 $ go get github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb
@@ -158,9 +150,7 @@ Kubernetes-mixin can support dashboards across multiple clusters. You need eithe
 
 ## Customising the mixin
 
-Kubernetes-mixin allows you to override the selectors used for various jobs,
-to match those used in your Prometheus set. You can also customize the dashboard
-names and add grafana tags.
+Kubernetes-mixin allows you to override the selectors used for various jobs, to match those used in your Prometheus set. You can also customize the dashboard names and add grafana tags.
 
 In a new directory, add a file `mixin.libsonnet`:
 
@@ -225,32 +215,32 @@ local utils = import 'lib/utils.libsonnet';
   }
 )
 ```
+
 Create new file: `lib/kubernetes_customised_alerts.jsonnet` with the following:
 
 ```jsonnet
 std.manifestYamlDoc((import '../kubernetes_mixin_override.libsonnet').prometheusAlerts)
 ```
+
 Running `jsonnet -S lib/kubernetes_customised_alerts.jsonnet` will build the alerts with your customisations.
 
 Same result can be achieved by modyfying the existing `config.libsonnet` with the content of `kubernetes_mixin_override.libsonnet`.
 
 ## Background
 
 ### Alert Severities
+
 While the community has not yet fully agreed on alert severities and their to be used, this repository assumes the following paradigms when setting the severities:
 
 * Critical: An issue, that needs to page a person to take instant action
 * Warning: An issue, that needs to be worked on but in the regular work queue or for during office hours rather than paging the oncall
 * Info: Is meant to support a trouble shooting process by informing about a non-normal situation for one or more systems but not worth a page or ticket on its own.
 
-
 ### Architecture and Technical Decisions
 
-* For more motivation, see
-"[The RED Method: How to instrument your services](https://kccncna17.sched.com/event/CU8K/the-red-method-how-to-instrument-your-services-b-tom-wilkie-kausal?iframe=no&w=100%&sidebar=yes&bg=no)" talk from CloudNativeCon Austin.
+* For more motivation, see "[The RED Method: How to instrument your services](https://kccncna17.sched.com/event/CU8K/the-red-method-how-to-instrument-your-services-b-tom-wilkie-kausal?iframe=no&w=100%&sidebar=yes&bg=no)" talk from CloudNativeCon Austin.
 * For more information about monitoring mixins, see this [design doc](DESIGN.md).
 
 ## Note
 
-You can use the external tool call [prom-metrics-check](https://github.com/ContainerSolutions/prom-metrics-check) to validate the created dashboards. This tool allows you to check if the metrics installed and used in Grafana dashboards exist in the Prometheus instance.
-Please have a look at https://github.com/ContainerSolutions/prom-metrics-check.
+You can use the external tool call [prom-metrics-check](https://github.com/ContainerSolutions/prom-metrics-check) to validate the created dashboards. This tool allows you to check if the metrics installed and used in Grafana dashboards exist in the Prometheus instance. Please have a look at https://github.com/ContainerSolutions/prom-metrics-check.
-Original file line number
+Diff line change
@@ Expand Up / @@ -4,3 +4,4 @@ dashboards_out @@
     vendor
     jsonnetfile.lock.json
     tmp
+    .vale