Zum Inhalt springen
Trainingslager IT-Trainingslager

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.json

Erwartet:

Pods bereit
Anfragen pro Sekunde
Antwortzeit p95
Notizen pro Sekunde je Pod
  • jq liest die Datei. Ist sie kein gültiges JSON, meldet es den Fehler mit Zeile und Spalte – bevor Grafana stumm daran scheitert.
  • uid ist 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: prometheus drin – der feste Name aus Tag 5, Drill 2.
  • gridPos legt Lage und Größe fest: 24 Spalten Breite, h in Rasterzeilen.
  • Die Variable pod holt sich ihre Werte mit label_values(...) aus Prometheus. $pod im vierten Panel wird zu einem regulären Ausdruck wie notes-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 kubectl eingebaut (-k). configMapGenerator erzeugt 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: true hä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=1

Erwartet:

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-api

Erwartet:

{"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.json würde die Datei leeren, bevor jq sie liest. Darum der Umweg über neu.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 1

Erwartet: Nach einem Scrape zeigt das Panel 1 auf rotem Grund. Zurück:

kubectl -n app scale deploy/notes-api --replicas 2

Fortschritt 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 -l

Erwartet:

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.folderAnnotation in 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.