move site to cleaner theme with separated alerts and rules

Author: paulfantom

.gitmodules

@@ -1,3 +1,3 @@
-[submodule "site/themes/cayman"]
-	path = site/themes/cayman
-	url = https://github.com/zwbetz-gh/cayman-hugo-theme.git
+[submodule "site/themes/ace-documentation"]
+	path = site/themes/ace-documentation
+	url = https://github.com/vantagedesign/ace-documentation.git

generate.sh

@@ -26,14 +26,12 @@ download_mixin() {
 	cd "$curdir"
 }
 
-# Prepare env
-rm -rf site/content/* $MANIFESTS $TMPDIR
+# remove generated manifests and temporary directory
+rm -rf $MANIFESTS $TMPDIR
+# remove generated site content
+find site/content/ ! -name '_index.md' -type f -exec rm -rf {} +
 mkdir -p $TMPDIR
 
-# Create top-level index.md header
-INDEXFILE="site/content/_index.md"
-cp site/templates/_index_header.md.tmpl "$INDEXFILE"
-
 # Generate manifests
 cat mixins.yaml | gojsontoyaml -yamltojson > $TMPDIR/mixins.json
 
@@ -48,7 +46,7 @@ for mixin in $(cat $TMPDIR/mixins.json | jq -r '.mixins[].name'); do
 	#set -u
 
 	mkdir -p "site/content/${mixin}"
-	file="site/content/${mixin}/index.md"
+	file="site/content/${mixin}/_index.md"
 	# Create header
 	if [ -n "$subdir" ]; then
 		location="$repo/tree/master/$subdir"
@@ -62,29 +60,52 @@ title: $mixin
 
 $text
 
-Mixin available at [${repo#*//}]($location)
+{{< panel style="primary" title="Jsonnet source" >}}
+Mixin jsonnet code is available at [${repo#*//}]($location)
+{{< /panel >}}
 
 EOF
-	echo -e "\n## $mixin\n" >> $INDEXFILE
-	
 	dir="$TOP/$MANIFESTS/$mixin"
+	# Alerts
 	if [ -s "$dir/alerts.yaml" ] && [ "$(stat -c%s "$dir/alerts.yaml")" -gt 20 ]; then
-		echo -e "# Alerts\n\n[embedmd]:# (../../../$MANIFESTS/$mixin/alerts.yaml yaml)\n" >> $file
-		echo "- [Alerts](/$mixin#alerts)" >> $INDEXFILE
+		echo -e "## Alerts\n" >> $file
+		echo -e '{{< panel style="info" >}}' >> $file
+		echo -e "Complete list of pregenerated alerts is available [here](https://github.com/cloudalchemy/mixins/blob/master/manifests/$mixin/alerts.yaml)." >> $file
+		echo -e '{{< /panel >}}\n' >> $file
+
+		for i in $(cat $dir/alerts.yaml | gojsontoyaml -yamltojson | jq -cr '[.groups[].rules] | flatten | .[] | @base64'); do
+			var=$(echo "$i" | base64 --decode | gojsontoyaml);
+			name=$(echo -e "$var" | grep 'alert' | awk -F ': ' '{print $2}')
+			echo -e "### ${name}\n" >> $file
+			echo -e '{{< code lang="yaml" >}}' >> $file
+			echo -e "$var" >> $file
+			echo -e '{{< /code >}}\n ' >> $file
+		done
 	fi
+
+	# Recording Rules
 	if [ -s "$dir/rules.yaml" ] && [ "$(stat -c%s "$dir/rules.yaml")" -gt 20 ]; then
-		echo -e "# Recording rules\n\n[embedmd]:# (../../../$MANIFESTS/$mixin/rules.yaml yaml)\n" >> $file
-		echo "- [Recording Rules](/$mixin#recording-rules)" >> $INDEXFILE
+		echo -e "## Recording rules\n" >> $file
+		echo -e '{{< panel style="info" >}}' >> $file
+		echo -e "Complete list of pregenerated recording rules is available [here](https://github.com/cloudalchemy/mixins/blob/master/manifests/$mixin/rules.yaml)." >> $file
+		echo -e '{{< /panel >}}\n' >> $file
+		
+		for i in $(cat $dir/rules.yaml | gojsontoyaml -yamltojson | jq -cr '[.groups[].rules] | flatten | .[] | @base64'); do
+			var=$(echo "$i" | base64 --decode | gojsontoyaml);
+			name=$(echo -e "$var" | grep 'record' | awk -F ': ' '{print $2}')
+			echo -e "### ${name}\n" >> $file
+			echo -e '{{< code lang="yaml" >}}' >> $file
+			echo -e "$var" >> $file
+			echo -e '{{< /code >}}\n ' >> $file
+		done
 	fi
+
+	# Dashboards
 	if [ "$(ls -A "$dir/dashboards")" ]; then
-		echo -e "# Dashboards\nFollowing dashboards are generated from mixins and hosted on github:\n\n" >> $file
+		echo -e "## Dashboards\nFollowing dashboards are generated from mixins and hosted on github:\n\n" >> $file
 		for dashboard in $dir/dashboards/*.json; do
 			d=$(basename $dashboard)
 			echo "- [${d%.*}](https://github.com/cloudalchemy/mixins/blob/master/manifests/$mixin/dashboards/$d)" >> $file
 		done
-		echo "- [Dashboards](/$mixin#dashboards)" >> $INDEXFILE
 	fi
 done
-
-# Embed alerts and rules into site files
-embedmd -w $(find site/content/ -name "*.md")

site/config.yaml

@@ -4,7 +4,7 @@ baseURL: ""
 languageCode: "en-us"
 title: "Monitoring Mixins"
 
-theme: 'cayman'
+theme: 'ace-documentation'
 
 # Google analytics
 # googleAnalytics: UA-123456789-1
@@ -17,12 +17,22 @@ params:
 
   project_tagline: Combination of alerts, recording rules, and dashboards for prometheus exporters
 
+  disableSearch: true
+  disableReadmoreNav: true
+
+markup:
+  highlight:
+    style: monokailight
+
 menu:
-  nav:
+  shortcuts:
     - name: Homepage
       url: /
       weight: 1
-    - name: About
+    - name: About mixins
       url: "https://github.com/monitoring-mixins/docs"
       weight: 2
+    - name: "<i class='fab fa-github'></i>"
+      url: "https://github.com/cloudalchemy/mixin"
+      weight: 3
 

site/content/_index.md

@@ -1,59 +1,153 @@
 ---
-title: Prometheus monitoring mixins
+title: Prometheus Monitoring Mixins
 ---
 
+A mixin is a set of Grafana dashboards and Prometheus rules and alerts, packaged together in a reuseable and extensible bundle.
+Mixins are written in [jsonnet](https://jsonnet.org/), and are typically installed and updated with [jsonnet-bundler](https://github.com/jsonnet-bundler/jsonnet-bundler).
 
-## prometheus
+For more information about mixins, see:
+* [Prometheus Monitoring Mixins Design Doc](https://docs.google.com/document/d/1A9xvzwqnFVSOZ5fD3blKODXfsat5fg6ZhnKu9LK3lB4/view). A [cached pdf](design.pdf) is included in monitoring mixins [documentation repository](https://github.com/monitoring-mixins/docs).
+* 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 2018.  The KLUMPs system demo'd became the basis for the kubernetes-mixin.
+* "[Prometheus Monitoring Mixins: Using Jsonnet to Package Together Dashboards, Alerts and Exporters](https://www.youtube.com/watch?v=b7-DtFfsL6E)" talk from CloudNativeCon Copenhagen 2018.
+* "[Prometheus Monitoring Mixins: Using Jsonnet to Package Together Dashboards, Alerts and Exporters](https://promcon.io/2018-munich/talks/prometheus-monitoring-mixins/)" talk from PromCon 2018 (slightly updated).
 
-- [Alerts](/prometheus#alerts)
-- [Dashboards](/prometheus#dashboards)
+## How to use mixins.
 
-## node-exporter
+Mixins are designed to be vendored into the repo with your infrastructure config.
+To do this, use [jsonnet-bundler](https://github.com/jsonnet-bundler/jsonnet-bundler):
 
-- [Alerts](/node-exporter#alerts)
-- [Recording Rules](/node-exporter#recording-rules)
-- [Dashboards](/node-exporter#dashboards)
+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 kube-prometheus to deploy this mixin.
 
-## kubernetes
+## Generate config files
 
-- [Alerts](/kubernetes#alerts)
-- [Recording Rules](/kubernetes#recording-rules)
-- [Dashboards](/kubernetes#dashboards)
+You can manually generate the alerts, dashboards and rules files, but first you
+must install some tools:
 
-## kube-state-metrics
+```bash
+$ go get github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb
 
-- [Alerts](/kube-state-metrics#alerts)
+# macOS
+$ brew install jsonnet
 
-## etcd
+# Archlinux AUR
+$ yay -S jsonnet
+```
 
-- [Alerts](/etcd#alerts)
-- [Dashboards](/etcd#dashboards)
+Then, grab the mixin and its dependencies:
 
-## ceph
+```bash
+$ git clone https://github.com/<mixin org>/<mixin repo>
+$ cd <mixin repo>
+$ jb install
+```
 
-- [Alerts](/ceph#alerts)
-- [Recording Rules](/ceph#recording-rules)
+Finally, build the mixin:
 
-## gluster
+```bash
+$ make prometheus_alerts.yaml
+$ make prometheus_rules.yaml
+$ make dashboards_out
+```
 
-- [Alerts](/gluster#alerts)
-- [Recording Rules](/gluster#recording-rules)
-- [Dashboards](/gluster#dashboards)
+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.
 
-## consul
+## Using with prometheus-ksonnet
 
-- [Alerts](/consul#alerts)
-- [Dashboards](/consul#dashboards)
+Alternatively you can also use the mixin with
+[prometheus-ksonnet](https://github.com/grafana/jsonnet-libs/tree/master/prometheus-ksonnet),
+a [ksonnet](https://github.com/ksonnet/ksonnet) module to deploy a fully-fledged
+Prometheus-based monitoring system for Kubernetes:
 
-## jaeger
+Make sure you have the ksonnet v0.8.0:
 
-- [Alerts](/jaeger#alerts)
+```bash
+$ brew install https://raw.githubusercontent.com/ksonnet/homebrew-tap/82ef24cb7b454d1857db40e38671426c18cd8820/ks.rb
+$ brew pin ks
+$ ks version
+ksonnet version: v0.8.0
+jsonnet version: v0.9.5
+client-go version: v1.6.8-beta.0+$Format:%h$
+```
 
-## memcached
+In your config repo, if you don't have a ksonnet application, make a new one (will copy credentials from current context):
 
-- [Dashboards](/memcached#dashboards)
+```bash
+$ ks init <application name>
+$ cd <application name>
+$ ks env add default
+```
 
-## sealed-secrets
+Grab the kubernetes-jsonnet module using and its dependencies, which include
+the kubernetes-mixin:
 
-- [Alerts](/sealed-secrets#alerts)
-- [Dashboards](/sealed-secrets#dashboards)
+```bash
+$ go get github.com/jsonnet-bundler/jsonnet-bundler/cmd/jb
+$ jb init
+$ jb install github.com/kausalco/public/prometheus-ksonnet
+
+```
+
+Assuming you want to run in the default namespace ('environment' in ksonnet parlance), add the follow to the file `environments/default/main.jsonnet`:
+
+{{< code lang="as3" >}}
+local prometheus = import "prometheus-ksonnet/prometheus-ksonnet.libsonnet";
+
+prometheus {
+  _config+:: {
+    namespace: "default",
+  },
+}
+{{< /code >}}
+
+Apply your config:
+
+```bash
+$ ks apply default
+```
+
+## Using kube-prometheus
+
+See the kube-prometheus docs for [instructions on how to use mixins with kube-prometheus](https://github.com/coreos/kube-prometheus#kube-prometheus).
+
+## Customising the mixin
+
+Mixins typically allows you to override the selectors used for various jobs,
+to match those used in your Prometheus set.
+
+This example uses the [kubernetes-mixin](https://github.com/kubernetes-monitoring/kubernetes-mixin).
+ In a new directory, add a file `mixin.libsonnet`:
+
+{{< code lang="as3" >}}
+local kubernetes = import "kubernetes-mixin/mixin.libsonnet";
+
+kubernetes {
+  _config+:: {
+    kubeStateMetricsSelector: 'job="kube-state-metrics"',
+    cadvisorSelector: 'job="kubernetes-cadvisor"',
+    nodeExporterSelector: 'job="kubernetes-node-exporter"',
+    kubeletSelector: 'job="kubernetes-kubelet"',
+  },
+}
+{{< /code >}}
+
+Then, install the kubernetes-mixin:
+
+```bash
+$ jb init
+$ jb install github.com/kubernetes-monitoring/kubernetes-mixin
+```
+
+Generate the alerts, rules and dashboards:
+
+```bash
+$ jsonnet -J vendor -S -e 'std.manifestYamlDoc((import "mixin.libsonnet").prometheusAlerts)' > alerts.yml
+$ jsonnet -J vendor -S -e 'std.manifestYamlDoc((import "mixin.libsonnet").prometheusRules)' >files/rules.yml
+$ jsonnet -J vendor -m files/dashboards -e '(import "mixin.libsonnet").grafanaDashboards'
+```

site/layouts/_default/baseof.html

@@ -0,0 +1,43 @@
+<!DOCTYPE html>
+<html>
+    {{- partial "head.html" . -}}
+    <body>
+
+        {{- partial "header.html" . -}}
+
+        <div class="container-fluid">
+            <div class="row">
+
+                <div class="docs-sidenav order-0 col-12 col-md-3 col-lg-2 col-xl-2 position-sticky border-right">
+                    {{- partial "menu.html" . -}}
+                </div>
+
+                {{- if and (ne .Site.Params.toc false) (ne .Params.toc false) }}
+                <div class="docs-toc large order-lg-2 order-md-0 order-xs-1 col-12 col-lg-3 col-xl-3 position-sticky border-left">
+                    {{- partial "tableofcontents.html" . -}}
+                </div>
+                <div class="main col-12 order-1 col-md-9 col-lg-9 col-xl-7 py-3">
+                {{else}}
+                <div class="main col-12 order-1 col-md-9 col-lg-10 col-xl-10 py-3">
+                {{end}}
+
+                    {{- block "main" . }}{{- end }}
+                    
+                    <div class="row">
+                        {{- if and (ne .Site.Params.disableReadmoreNav true) (ne .Params.disableReadmoreNav true) -}}
+                        <div class="position-relative mx-auto col-lg-9">
+                          {{ partial "next-prev-page.html" . }}
+                        </div>
+                        {{- end -}}
+                    </div> <!-- /end of row -->
+
+                </div>
+
+            </div> <!-- /end of row -->
+
+        </div> <!-- /end of container -->
+
+        {{- partial "footer.html" . -}}
+
+    </body>
+</html>