Tag 6: Dashboards als Code
Ziel: Ein Dashboard als JSON-Datei, per Kustomize als ConfigMap im Cluster und von Grafana automatisch geladen – mit Variable und ohne Klicken. · Dauer: ca. 60 min · Voraussetzung: Tag 5
Briefing
- Ein zusammengeklicktes Dashboard lebt in der Datenbank von Grafana. Niemand sieht, wer was geändert hat, und nach einer Neuinstallation ist es weg.
- Im Grafana-Pod läuft ein Sidecar, der ConfigMaps
mit dem Label
grafana_dashboard: "1"in allen Namespaces sucht. Findet er eine, legt er ihren Inhalt als Datei ab, und Grafana lädt das Dashboard. - So liegt das Dashboard neben der Anwendung in Git, geht durch Reviews und wird mit ihr ausgerollt. Die mitgelieferten Dashboards kommen auf demselben Weg.
- Variablen machen ein Dashboard wiederverwendbar: Eine Auswahlliste oben setzt einen Wert, den jede Abfrage nutzt.
dashboards/notes-api.json ─► kubectl apply -k ─► ConfigMap (Label grafana_dashboard)
│ Sidecar im Grafana-Pod
▼
Grafana lädt das Dashboard
Drill 1: Das Dashboard als Datei
mkdir -p ~/obs-lab/dashboards
cd ~/obs-lab/dashboards
cat > notes-api.json <<'EOF'
{
"uid": "notes-api-code",
"title": "notes-api Überblick",
"tags": ["notes-api"],
"time": {"from": "now-30m", "to": "now"},
"refresh": "30s",
"schemaVersion": 41,
"templating": {
"list": [
{
"name": "pod",
"label": "Pod",
"type": "query",
"datasource": {"type": "prometheus", "uid": "prometheus"},
"query": {"query": "label_values(up{job=\"notes-api\"}, pod)", "refId": "pod"},
"refresh": 2,
"multi": true,
"includeAll": true,
"current": {"text": "All", "value": "$__all"}
}
]
},
"panels": [
{
"id": 1, "type": "stat", "title": "Pods bereit",
"gridPos": {"x": 0, "y": 0, "w": 4, "h": 6},
"datasource": {"type": "prometheus", "uid": "prometheus"},
"targets": [{"refId": "A", "expr": "count(up{job=\"notes-api\"} == 1)"}]
},
{
"id": 2, "type": "timeseries", "title": "Anfragen pro Sekunde",
"gridPos": {"x": 4, "y": 0, "w": 10, "h": 6},
"datasource": {"type": "prometheus", "uid": "prometheus"},
"fieldConfig": {"defaults": {"unit": "reqps"}, "overrides": []},
"targets": [{"refId": "A", "legendFormat": "{{method}}",
"expr": "sum by (method) (job:notes_http_requests:rate5m)"}]
},
{
"id": 3, "type": "timeseries", "title": "Antwortzeit p95",
"gridPos": {"x": 14, "y": 0, "w": 10, "h": 6},
"datasource": {"type": "prometheus", "uid": "prometheus"},
"fieldConfig": {"defaults": {"unit": "s"}, "overrides": []},
"targets": [{"refId": "A", "legendFormat": "p95",
"expr": "job:notes_http_request_duration_seconds:p95_5m"}]
},
{
"id": 4, "type": "timeseries", "title": "Notizen pro Sekunde je Pod",
"gridPos": {"x": 0, "y": 6, "w": 24, "h": 7},
"datasource": {"type": "prometheus", "uid": "prometheus"},
"targets": [{"refId": "A", "legendFormat": "{{pod}}",
"expr": "sum by (pod) (rate(notes_created_total{pod=~\"$pod\"}[5m]))"}]
}
]
}
EOF
jq -r '.panels[].title' notes-api.jsonErwartet:
Pods bereit
Anfragen pro Sekunde
Antwortzeit p95
Notizen pro Sekunde je Pod
jqliest die Datei. Ist sie kein gültiges JSON, meldet es den Fehler mit Zeile und Spalte – bevor Grafana stumm daran scheitert.uidist der feste Name. Damit bleibt die Adresse des Dashboards gleich, egal wie oft du es neu lädst. Der Titel unterscheidet sich von dem aus Tag 5, denn zwei Dashboards mit gleichem Titel im selben Ordner lehnt Grafana ab.- Die Datenquelle steht als
uid: prometheusdrin – der feste Name aus Tag 5, Drill 2. gridPoslegt Lage und Größe fest: 24 Spalten Breite,hin Rasterzeilen.- Die Variable
podholt sich ihre Werte mitlabel_values(...)aus Prometheus.$podim vierten Panel wird zu einem regulären Ausdruck wienotes-api-57f4f47769-5x8dq|notes-api-57f4f47769-qj4nb. Darum=~.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Kustomize baut die ConfigMap
cat > kustomization.yaml <<'EOF'
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
namespace: app
configMapGenerator:
- name: notes-api-dashboard
files:
- notes-api.json
options:
labels:
grafana_dashboard: "1"
disableNameSuffixHash: true
EOF
kubectl apply -k .Erwartet:
configmap/notes-api-dashboard created
- Kustomize ist in
kubectleingebaut (-k).configMapGeneratorerzeugt aus der JSON-Datei eine ConfigMap. Du schreibst kein JSON in YAML hinein. - Das Label
grafana_dashboard: "1"ist das Signal für den Sidecar. disableNameSuffixHash: truehält den Namen fest. Sonst hängt Kustomize einen Hash des Inhalts an, und jede Änderung ergäbe eine neue ConfigMap.- Die ConfigMap liegt in
app, bei der Anwendung. Der Sidecar sucht in allen Namespaces.
Was im Cluster gelandet ist:
kubectl -n app get configmap -l grafana_dashboard=1Erwartet:
NAME DATA AGE
notes-api-dashboard 1 71s
Fortschritt speichern? Kostenlos registrieren
Drill 3: Grafana hat es geladen
Der Sidecar meldet sich im Log:
kubectl -n monitoring logs deploy/kps-grafana -c grafana-sc-dashboard | grep notes-apiErwartet:
{"time": "...", "level": "INFO", "msg": "Writing /tmp/dashboards/notes-api.json (as...
Der Sidecar schreibt die Datei und bittet Grafana danach, seine Dashboards neu einzulesen. Prüfe über die API:
curl -s -u admin:lab-grafana-pw-123 localhost:30300/api/dashboards/uid/notes-api-code \
| jq '{title: .dashboard.title, provisioned: .meta.provisioned}'Erwartet:
{
"title": "notes-api Überblick",
"provisioned": true
}
provisioned: true heißt: Das Dashboard gehört der Datei,
nicht der Datenbank. Öffne es im Browser unter
http://<VM-IP>:30300/d/notes-api-code. Änderst du
dort etwas und willst speichern, lehnt Grafana ab und bietet an, das
JSON zu kopieren. Die Wahrheit liegt in Git.
Oben steht die Auswahlliste Pod. Wähle einen
einzelnen Pod: Das untere Panel zeigt nur noch ihn. Die oberen Panels
bleiben gleich, denn ihre Abfragen nutzen $pod nicht.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Ändern und neu ausrollen
Das Panel „Pods bereit“ soll rot werden, wenn weniger als zwei Pods
bereit sind. Mit jq ergänzt du die Schwellwerte, ohne die
Datei von Hand zu bearbeiten:
jq '.panels[0].fieldConfig = {"defaults": {"thresholds": {"mode": "absolute",
"steps": [{"color": "red", "value": null}, {"color": "green", "value": 2}]}},
"overrides": []}' notes-api.json > neu.json
mv neu.json notes-api.json
kubectl apply -k .Erwartet:
configmap/notes-api-dashboard configured
- Der erste Schritt (
value: null) gilt ab minus unendlich: rot. Ab 2 wird es grün. > notes-api.jsonwürde die Datei leeren, bevorjqsie liest. Darum der Umweg überneu.json.
Nach etwa einer Minute:
curl -s -u admin:lab-grafana-pw-123 localhost:30300/api/dashboards/uid/notes-api-code \
| jq -c '.dashboard.panels[0].fieldConfig.defaults.thresholds.steps'Erwartet:
[{"color":"red","value":null},{"color":"green","value":2}]
Probiere es aus:
kubectl -n app scale deploy/notes-api --replicas 1Erwartet: Nach einem Scrape zeigt das Panel 1 auf rotem
Grund. Zurück:
kubectl -n app scale deploy/notes-api --replicas 2Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
curl -s -u admin:lab-grafana-pw-123 'localhost:30300/api/search?tag=notes-api' \
| jq -r '.[].title'Erwartet:
notes-api Überblick
tags aus der Datei werden zum Suchbegriff.
kubectl get configmap -A -l grafana_dashboard=1 --no-headers | wc -lErwartet:
26
25 aus dem Chart, eine von dir. Nur das zusammengeklickte Dashboard aus Tag 5 lebt allein in der Datenbank.
Challenge
Übernimm das Panel Fehlerquote aus Tag 5 in die
Datei: unten, volle Breite, Einheit percentunit.
Hinweis: Exportiere das Panel nicht – schreibe es
nach dem Muster der anderen. jq '.panels += [{...}]' hängt
ein Element an. Mit --arg q '…' reichst du die Abfrage als
Variable $q hinein und sparst dir das Maskieren der
Anführungszeichen.
Lösung
jq --arg q 'sum(job:notes_http_requests:rate5m{code=~"5.."})
/ sum(job:notes_http_requests:rate5m)' \
'.panels += [{"id": 5, "type": "timeseries", "title": "Fehlerquote",
"gridPos": {"x": 0, "y": 13, "w": 24, "h": 6},
"datasource": {"type": "prometheus", "uid": "prometheus"},
"fieldConfig": {"defaults": {"unit": "percentunit"}, "overrides": []},
"targets": [{"refId": "A", "expr": $q}]}]' notes-api.json > neu.json
mv neu.json notes-api.json
kubectl apply -k .Nach einer Minute:
curl -s -u admin:lab-grafana-pw-123 localhost:30300/api/dashboards/uid/notes-api-code \
| jq '.dashboard.panels | length'Erwartet:
5
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Dashboards programmieren: Bei vielen ähnlichen Dashboards wird JSON mühsam. Grafonnet (Jsonnet) und das Grafana Foundation SDK (Go, Python, TypeScript) erzeugen das JSON aus Code mit Schleifen und Funktionen.
- Ordner: Mit
grafana.sidecar.dashboards.folderAnnotationin den Werten des Charts bestimmt eine Annotation an der ConfigMap den Ordner. So bekommt jedes Team seinen. - Grafana Operator: Wer mehrere Grafana-Instanzen
betreibt, beschreibt Dashboards, Datenquellen und Ordner als eigene
Ressourcen (
GrafanaDashboard). Der Sidecar ist die schlanke Variante für eine Instanz.