PKR-Lab

30080 - Uptime Kuma — Status-Seite und Service-Alerting

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/30080-uptime-kuma.md

Uptime Kuma — Status-Seite und Service-Alerting

Cluster: TECH · Ordner argocd/apps/tech/uptime-kuma/ · URL https://uptime-kuma.prod.homeserver und https://status-prod.pke-lab.de. kubectl-Befehle in diesem Doc gelten für den TECH-Cluster (Zugriff je Cluster).

Uptime Kuma ist eine schlanke, selbst gehostete Status-Seite. Sie prüft
regelmäßig ob Dienste erreichbar sind und schickt Alerts bei Ausfällen —
via ntfy, E-Mail oder anderen Kanälen.


Architektur

uptime-kuma.prod.homeserver  →  Traefik  →  uptime-kuma (Port 3001)
                                            └── PVC: data (2 Gi, local-path)

Warum local-path statt nas: War testweise auf nas, ist aber nach
Umstellung des NAS auf all_squash (siehe capulus-core/2-betrieb-hardware/20000-nas-storage.md)
mit Permission-Fehlern abgestürzt und wurde zurück auf local-path
gestellt.


Erster Start

Nach dem Deploy unter https://uptime-kuma.prod.homeserver den Admin-Account
anlegen (erscheint beim ersten Besuch automatisch).


Monitore anlegen

  1. Neuer Monitor → Typ wählen:
    • HTTP(s) — für Web-Dienste (Grafana, ArgoCD, ...)
    • TCP Port — für Ports (k3s-API Port 6443)
    • Ping — für Hosts (homeserver, worker-0)
  2. URL / Host und Intervall eintragen
  3. Notification hinzufügen (z. B. ntfy)

Empfohlene Monitore für den Stack

Monitor URL Typ
Grafana https://grafana.tech.homeserver HTTP
ArgoCD https://argocd.tech.homeserver HTTPS (internes Zertifikat)
ntfy https://ntfy.tech.homeserver HTTP
Semaphore https://semaphore.tech.homeserver HTTP
Paperless https://paperless.prod.homeserver HTTP
n8n https://n8n.prod.homeserver HTTP
worker-0 (Ping) 192.168.178.95 Ping

Notifications einrichten

ntfy

  1. Uptime Kuma: Einstellungen → Benachrichtigung → ntfy
  2. Server: https://ntfy.tech.homeserver
  3. Topic: z. B. homelab-uptime
  4. Priorität: urgent für Ausfälle

Öffentliche Status-Page

argocd/apps/tech/uptime-kuma/values.yaml legt zusätzlich zum
internen Host einen externen Ingress-Host an (status-prod.pke-lab.de —
bewusst ohne "uptime-kuma" im Namen, damit die eingesetzte Software nicht
schon aus der URL erkennbar ist), erreichbar über die bestehende
*.pke-lab.de-Wildcard-Route von cloudflared — kein Änderung an
cloudflared nötig, siehe capulus-core/e-externe-erreichbarkeit/e0010-cloudflare-deploy.md.

Die eigentliche Status-Page ist ein manueller Einmal-Schritt in der
Kuma-UI (nicht Teil von Git/Helm):

  1. Settings → Status Pages → New Status Page
  2. Nur die Monitore hinzufügen, die öffentlich sichtbar sein sollen (keine
    internen IPs/Ports, keine Klarnamen sensibler interner Dienste)
  3. Slug vergeben, z. B. homelab → Page liegt dann unter
    https://status-prod.pke-lab.de/status/homelab
  4. Die "Updates"-Seite auf edv-kretzer.de fragt ausschließlich die
    Status-Page-JSON-API (/api/status-page/<slug> +
    /api/status-page/heartbeat/<slug>) per Hintergrund-Request ab und
    rendert die Daten im eigenen Design nach — es gibt dort weder einen
    Link noch ein iframe
    , das direkt auf status-prod.pke-lab.de zeigt.
    Nutzer sehen nur die Zusammenfassung, nicht den echten Hostnamen.

Stand 2026-10-19: Die Status-Page homelab existiert (Titel „Home-Lab“, Gruppe „Services“ mit n8n, Wiki, Immich). Prüfen: curl https://status-prod.pke-lab.de/api/status-page/homelab liefert JSON.

CORS: Uptime Kuma sendet keine Access-Control-Allow-Origin-Header, ein Browser auf edv-kretzer.de darf die Antwort ohne sie nicht lesen. Das Chart legt deshalb die Traefik-Middleware uptime-kuma-cors an (templates/middleware-cors.yaml) und hängt sie per Annotation an den öffentlichen Ingress. Erlaubt sind GET, HEAD und OPTIONS für die Ursprünge aus ingressPublic.corsOrigins (https://www.edv-kretzer.de, https://edv-kretzer.de), ohne Zugangsdaten. Prüfen:

curl -s -D - -o /dev/null -H "Origin: https://www.edv-kretzer.de" https://status-prod.pke-lab.de/api/status-page/homelab | grep -i access-control

Die Middleware gilt für den ganzen Host, also auch für /dashboard. Dort schützt weiter der Login, CORS ersetzt keine Anmeldung.

Das Haupt-Dashboard (/dashboard) bleibt hinter dem normalen
Admin-Login — nur die Status-Page-Route ist laut Kuma-Design
unauthentifiziert öffentlich erreichbar. Der generische Hostname ist ein
zusätzlicher Baustein, kein Ersatz für den Login-Schutz: Wer die
Netzwerk-Requests der Website mitliest, sieht die tatsächliche URL —
das lässt sich bei einem clientseitigen Fetch grundsätzlich nicht
verstecken, nur der beiläufige Ein-Klick-Zugriff wird verhindert.


Anmeldung

Der interne Host (uptime-kuma.prod.homeserver) steht nicht mehr hinter
Authentik-SSO (im Oktober 2026 entfernt), es gilt nur der eigene Login von
Uptime Kuma. Der externe Status-Host (status-prod.pke-lab.de) war nie
betroffen. Der frühere Bypass-Host https://uptime-kuma-native.prod.homeserver
zeigt weiterhin auf dieselbe App.


Konfiguration (values.yaml)

Key Bedeutung Default
persistence.size Datenspeicher (SQLite + Config) 2Gi
resources.limits.memory RAM-Limit 512Mi

Fehlersuche

kubectl -n uptime-kuma get pods,pvc,ingress
kubectl -n uptime-kuma logs deploy/uptime-kuma --tail=100
kubectl -n uptime-kuma get middleware uptime-kuma-cors -o yaml
curl -sI -H 'Origin: https://www.edv-kretzer.de' https://status-prod.pke-lab.de/api/status-page/homelab | grep -i access-control
Symptom Ursache Lösung
Pod Pending oder Neustart-Schleife PVC (2 GiB), Node-Zuordnung (kubernetes.io/hostname: homeserver) kubectl -n uptime-kuma describe pod,pvc
Oberfläche nicht erreichbar Ingress, DNS, VPN kubectl -n uptime-kuma get ingress, DNS
Status-Page der Website zeigt „Status gerade nicht abrufbar“ CORS-Header fehlen oder falsche Ursprünge, falscher Slug, Status-Page ohne Monitore Header per curl wie oben prüfen, ingressPublic.corsOrigins, Slug homelab, EDV-Kretzer: Status-Widget
ntfy-Benachrichtigungen kommen nicht Notification mit falscher URL/Token Abschnitt „Notifications einrichten“, ntfy
Monitor zeigt down, Dienst läuft Monitor erreicht den Dienst nicht (NetworkPolicy, falsche URL, Zertifikat) URL aus dem Pod testen, Internes TLS
carplay-api zeigt keine Monitore Status-Page homeserver/Slug stimmt nicht mit config.uptimeKuma.slug überein oder Monitore nicht auf der Page carplay-api: Fehlerbehebung
Anmeldung schlägt fehl Passwort vergessen Abschnitt „Anmeldung“
Datenverlust nach Pod-Neustart PVC fehlt (emptyDir) oder nicht gebunden kubectl -n uptime-kuma get pvc, Sicherungen: NAS-Backup
Native Variante (uptime-kuma-native…) nicht erreichbar zusätzlicher Ingress für Clients ohne Proxy ingressNative in values.yaml, Abschnitt „Konfiguration“
Die Konsole zeigt Cannot connect to socket server WebSocket wird durch Proxy blockiert Ingress/Middleware prüfen, direkt über ingressNative testen

Allgemeine Fehlersuche: zentrale Fehlersuche.