PKR-Lab

300d0 - carplay-api — Homeserver-Dashboard-API

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/300d0-carplay-api.md

carplay-api — Homeserver-Dashboard-API

Cluster: TECH · Ordner argocd/apps/tech/carplay-api/ · URL https://carplay-api.prod.homeserver. kubectl-Befehle in diesem Doc gelten für den TECH-Cluster (Zugriff je Cluster).

Kleine Go/Gin-API, die VictoriaMetrics (Systemmetriken pro Host), ntfy
(Alerts) und Uptime-Kuma (Service-Status) zu einem einzigen JSON-Payload
zusammenfasst, 30s gecacht, plus Bildschirmhelligkeit und
Wake-on-LAN/Shutdown für die Flotte. Einziger Konsument: die iOS-App
Homeserver Dashboard — eine reine iPhone-App, keine CarPlay-Komponente
(siehe capulus-ios/README.md im selben Repo für die App selbst; dieses Dokument
ist nur der Backend-Teil, der Verzeichnisname carplay-api blieb aus
diesem früheren CarPlay-Zuschnitt erhalten).

Inhaltsverzeichnis

  1. Übersicht & Architektur
  2. power-agent
  3. Abweichungen vom ursprünglichen Konzept
  4. Ersteinrichtung
  5. Uptime-Kuma Status-Page anlegen
  6. Image bauen & pushen
  7. Absicherung
  8. Konfiguration (values.yaml)
  9. Fehlerbehebung

Übersicht & Architektur

Homeserver Dashboard (iOS)
        │  GET  /api/dashboard              (Bearer-Token, alle 30s)
        │  GET  /api/brightness
        │  PUT  /api/brightness
        │  POST /api/power/wake
        │  POST /api/power/shutdown
        ▼
carplay-api.prod.homeserver ──▶ Traefik ──▶ carplay-api Pod (Namespace carplay-api)
                                          ├─ VictoriaMetrics  (CPU/RAM/Disk/Temp/Uptime, PRO Host)
                                          ├─ ntfy             (Alerts, Topic "alerts")
                                          ├─ Uptime-Kuma       (Service-Status, Status-Page)
                                          └─ power-agent       (Bearer-Token, siehe unten)
                                          30s In-Memory-Cache (nur /api/dashboard), 5s Gesamt-Timeout

Die Alerts-, Metrik- und Status-Abfragen laufen parallel und mit eigenem
kurzen Timeout (VictoriaMetrics 3s, ntfy/Kuma je 2s). Fällt eine Quelle
aus, liefert /api/dashboard trotzdem 200 mit den übrigen Spalten
gefüllt und der ausgefallenen Spalte leer/auf 0 — siehe 60080. Metriken
kommen pro Host (hosts[] im Payload, siehe config.hosts in
values.yaml), nicht mehr als ein einziger Flotten-Durchschnitt — ein
Host, der gerade aus ist, taucht mit online: false auf, alle
Zahlenfelder auf 0.

power-agent

Brightness- und Power-Endpunkte werden NICHT vom carplay-api-Pod selbst
ausgeführt — der Pod läuft absichtlich unprivilegiert
(podSecurityContext/securityContext in values.yaml, readOnlyRootFilesystem,
kein Host-Zugriff). Stattdessen proxied carplay-api jede
Helligkeits-/Wake-/Shutdown-Anfrage an power-agent
(capulus-ansible/roles/power_agent), einen kleinen privilegierten HTTP-Daemon,
der direkt auf dem nackten Homeserver-Host läuft (systemd-Service, NICHT
im Cluster), ist aus Pods über die Adresse der Bridge cni0 des homeservers
(POWER_AGENT_URL=http://10.42.2.1:9101) erreichbar und:

Manuelle Wake-/Shutdown-Aktionen aus der App schreiben/löschen dieselben
STATE_DIR/<name>.woke_at-Dateien wie der automatische
Last-Watchdog (cluster-power-manager.service) — ein Tap in der App und
die automatische Skalierung widersprechen sich dadurch nicht.

Der Homeserver selbst hat keinen Wake-Pfad (kein WoL-Empfänger, da
Dauerläufer) — POST /api/power/wake mit target: "homeserver" liefert
400.

Setup: power_agent läuft in site.yml direkt nach
cluster_power_manager (make power-agent für einen gezielten
Re-Deploy). Beim ersten Rollout erzeugt die Rolle ein Bearer-Token unter
/etc/power-agent/token auf dem Homeserver — dieser Wert muss danach
manuell in argocd/apps/tech/carplay-api/values.yaml unter
secrets.powerAgentToken versiegelt werden (kubeseal), siehe 60080. Ohne passendes Secret bekommt die App dauerhaft 502 auf
Helligkeit/Wake/Shutdown, der Rest des Dashboards bleibt aber nutzbar.

Abweichungen vom ursprünglichen Konzept

Das ursprüngliche Anforderungsdokument beschrieb drei Dinge, die entweder
nicht existieren oder nicht zu diesem Cluster passen. Statt sie 1:1
umzusetzen (und damit etwas zu bauen, das gegen die echten Dienste nie
funktioniert hätte), wurde angepasst:

Ersteinrichtung

  1. kubeseal-Zertifikat besorgen (einmalig, überspringen falls
    ~/homelab-certs/sealed-secrets.pem schon existiert):

    mkdir -p ~/homelab-certs
    ssh -i ~/.ssh/id_ed25519 [email protected] \
      'sudo kubectl -n sealed-secrets get secret \
       -l sealedsecrets.bitnami.com/sealed-secrets-key=active \
       -o jsonpath="{.items[0].data.tls\.crt}" | base64 -d' \
      > ~/homelab-certs/sealed-secrets.pem
    

    Alternative ohne CLI/SSH-Zugriff: https://kubeseal-webgui.tech.homeserver
    verschlüsselt einzelne Werte über eine Weboberfläche (Namespace
    carplay-api, Secret-Name carplay-api-token, Key token) — liefert
    denselben Base64-Blob wie unten, ohne Schritt 1.

  2. API-Token erzeugen und versiegeln (Pflicht — ohne dieses Secret
    bleibt der Pod in CreateContainerConfigError hängen, siehe 60080):

    TOKEN=$(openssl rand -hex 32)
    echo -n "$TOKEN" | kubeseal --raw \
      --namespace carplay-api --name carplay-api-token \
      --cert ~/homelab-certs/sealed-secrets.pem --from-file=/dev/stdin
    

    Das Ergebnis in argocd/apps/tech/carplay-api/values.yaml unter
    secrets.apiToken.encryptedData eintragen. $TOKEN selbst geht in die
    iOS-App (Keychain, siehe capulus-ios/README.md) — nie ins Git.

  3. power-agent ausrollen und Token versiegeln (Pflicht für
    Helligkeit/Wake/Shutdown, der Rest der App funktioniert auch ohne —
    siehe power-agent):

    make power-agent   # oder: einmal make install / ansible-playbook site.yml
    ssh -i ~/.ssh/id_ed25519 [email protected] 'sudo cat /etc/power-agent/token'
    

    Den ausgegebenen Wert genauso versiegeln wie den API-Token oben, nur
    mit anderem Namespace-Secret-Namen:

    echo -n "<power-agent-token>" | kubeseal --raw \
      --namespace carplay-api --name carplay-api-power-agent-token \
      --cert ~/homelab-certs/sealed-secrets.pem --from-file=/dev/stdin
    

    Ergebnis in values.yaml unter secrets.powerAgentToken.encryptedData,
    dazu secrets.powerAgentToken.enabled: true.

  4. Shutdown-Bestätigungscode versiegeln (Pflicht für den
    Homeserver-Shutdown aus der App — ohne dieses Secret bleibt
    target: "homeserver" mit 503 blockiert, worker-0/worker-1 sind
    davon nicht betroffen). Denselben Wert wie das aktuelle
    ArgoCD-Admin-Passwort verwenden (siehe
    capulus-core/b-kubernetes-gitops/b0010-argocd.md) und bei jeder Passwort-Rotation hier
    mit erneuern:

    echo -n "<argocd-admin-passwort>" | kubeseal --raw \
      --namespace carplay-api --name carplay-api-shutdown-code \
      --cert ~/homelab-certs/sealed-secrets.pem --from-file=/dev/stdin
    

    Ergebnis in values.yaml unter
    secrets.shutdownConfirmationCode.encryptedData, dazu
    secrets.shutdownConfirmationCode.enabled: true.

  5. Status-Page in Uptime-Kuma anlegen (siehe nächster Abschnitt) und den
    Slug in values.yaml unter config.uptimeKuma.slug eintragen.

  6. config.hosts prüfen/anpassen — ein Eintrag pro Host-Karte auf der
    App-Startseite, instance muss exakt das VictoriaMetrics-Label des
    jeweiligen node-exporter-Targets treffen (Default deckt
    Homeserver/worker-0/worker-1/NAS ab, siehe 60080).

  7. Image bauen/pushen (siehe unten) und
    image.repository/image.tag setzen.

  8. Committen & pushen — ArgoCD rollt automatisch aus.

Uptime-Kuma Status-Page anlegen

  1. https://uptime-kuma.prod.homeserver → Status-Pages → New Status Page.
  2. Slug vergeben (Default in values.yaml: homeserver) — muss exakt mit
    config.uptimeKuma.slug übereinstimmen.
  3. Alle Monitore hinzufügen, die im Dashboard erscheinen sollen (siehe
    capulus-core/3-apps-workloads/30080-uptime-kuma.md für die vorhandene
    Monitor-Liste).
  4. Speichern — die Seite muss nicht öffentlich beworben werden, sie muss
    nur existieren; carplay-api liest sie serverseitig.

Image bauen & pushen

Automatisiert über .github/workflows/build-images.yml: baut/pusht bei
jeder Änderung an Dockerfile/src/** automatisch nach
ghcr.io/pkr-lab/carplay-api. Details/Tag-Schema/manueller Rebuild:
capulus-core/f-cicd-automatisierung/f0060-build-images.md.

Der Workflow setzt values.yaml nicht selbst — den im Job-Summary
gemeldeten Tag manuell in image.tag eintragen und committen. Ist das
GHCR-Package privat, zusätzlich ein imagePullSecrets-Secret anlegen (siehe 60040).

Absicherung

Vier unabhängige Schichten, keine davon mTLS (siehe oben):

  1. Bearer-Token (CARPLAY_API_TOKEN) — Pflicht, prüft jeder Request an
    /api/* und /metrics. Ohne gesetztes Token startet der Server nicht
    (CARPLAY_API_TOKEN is not set, der Pod steht dann in CrashLoopBackOff).
    Nur /health bleibt offen, die Probes des kubelet brauchen es.
  2. IP-Allowlist (config.ipAllowlist, default deaktiviert) —
    beschränkt /api/* auf CIDR-Bereiche (Default-Vorschlag: Tailscale-CGNAT
    100.64.0.0/10 + LAN 192.168.178.0/24). Braucht config.trustedProxies
    korrekt gesetzt (steht auf dem Pod-CIDR 10.42.0.0/16), sonst sieht die App Traefiks
    Pod-IP statt der echten Client-IP und sperrt alles aus — deshalb vor dem
    Aktivieren einmal kubectl -n carplay-api logs deploy/carplay-api prüfen,
    ob client_ip in den Request-Logs die erwartete Adresse zeigt.
  3. Rate-Limiting (100 req/min/IP, konfigurierbar) — Backstop gegen eine
    verunglückte App-Instanz, die im 30s-Intervall-Bug feststeckt.
  4. Bestätigungscode (SHUTDOWN_CONFIRMATION_CODE) — zusätzlich zum
    Bearer-Token für genau eine Aktion: POST /api/power/shutdown mit
    target: "homeserver". worker-0/worker-1 brauchen ihn nicht (nur eine
    simple Bestätigung in der App), da ein versehentliches
    Herunterfahren dort folgenlos per Wake-on-LAN rückgängig zu machen ist —
    beim Homeserver nicht.

Konfiguration (values.yaml)

Vollständige Liste + Defaults: argocd/apps/tech/carplay-api/values.yaml
(kommentiert) und capulus-core/komponenten/carplay-api.md (Env-Var-Tabelle).
Die wichtigsten:

Key Bedeutung
config.hosts Liste {id, name, instance} — ein Eintrag pro Host-Karte auf der App-Startseite, instance muss exakt das VictoriaMetrics-instance-Label treffen (Default deckt Homeserver/worker-0/worker-1/NAS ab)
config.ntfy.topic ntfy-Topic, das als Alerts angezeigt wird
config.uptimeKuma.slug Status-Page-Slug, siehe oben
config.powerAgent.url Basis-URL von power-agent auf dem Homeserver-Host, siehe power-agent
secrets.apiToken.enabled Default true — siehe Ersteinrichtung
secrets.powerAgentToken.enabled Muss true sein, sonst 502 auf Helligkeit/Wake/Shutdown — siehe power-agent
secrets.shutdownConfirmationCode.enabled Muss true sein, sonst 503 auf Homeserver-Shutdown — siehe Ersteinrichtung Schritt 4
ingress.host carplay-api.prod.homeserver

Fehlerbehebung

Symptom Check
Pod hängt in CreateContainerConfigError secrets.apiToken.encryptedData noch Platzhalter? Siehe Ersteinrichtung Schritt 2
/api/dashboard liefert status: [] Status-Page-Slug falsch oder Monitore nicht auf die Page gelegt — siehe Uptime-Kuma-Abschnitt
/api/dashboard liefert alerts: [], obwohl ntfy Nachrichten hat config.ntfy.topic prüfen; NTFY_SINCE (Default 12h) evtl. zu kurz für ältere Test-Nachrichten
hosts[] zeigt einen bekanntermaßen laufenden Host als online: false instance in config.hosts gegen die echten VictoriaMetrics-Labels prüfen: curl vmsingle-....svc.cluster.local:8428/api/v1/targets
hosts zeigt überall 0 / online: false kubectl -n carplay-api logs deploy/carplay-api — PromQL-Query-Fehler landen dort mit Klartext-Fehlermeldung von VictoriaMetrics
App meldet Verbindungsfehler, curl --cacert pki/homeserver-root-ca.pem https://carplay-api.prod.homeserver/health liefert aber 200 Die App spricht nur HTTPS (keine ATS-Ausnahme). Root-CA auf dem iPhone installiert und unter Einstellungen → Allgemein → Info → Zertifikatsvertrauenseinstellungen aktiviert? Test: https://carplay-api.prod.homeserver/health in Safari ohne Zertifikatswarnung, siehe 60080
App bekommt 401 auf /api/dashboard Token in der App (Keychain) ≠ secrets.apiToken-Klartext beim Erzeugen des SealedSecret
App bekommt 401 beim Homeserver-Shutdown Eingegebener Code ≠ secrets.shutdownConfirmationCode-Klartext — meist nach einer ArgoCD-Passwort-Rotation, die hier noch nicht nachgezogen wurde
App bekommt 502 auf Helligkeit/Wake/Shutdown secrets.powerAgentToken stimmt nicht mit /etc/power-agent/token auf dem Homeserver überein, oder power-agent läuft nicht (systemctl status power-agent auf dem Homeserver) — siehe power-agent
App meldet Erfolg beim Homeserver-Shutdown, aber der Host läuft noch minutenlang weiter Erwartet — kubectl drain läuft im Hintergrund (bis zu 180s Timeout) bevor k3s gestoppt und poweroff ausgeführt wird, siehe power-agent. journalctl -u power-agent -f auf dem Homeserver zeigt den Fortschritt
kubectl cordon/drain in den power-agent-Logs schlägt sofort fehl NODE_NAME in /etc/power-agent/config.env ≠ tatsächlicher k3s-Node-Name (kubectl get nodes) — Poweroff läuft trotzdem weiter (Best-Effort), nur ohne sauberes Draining
App bekommt 403 nach Aktivieren der IP-Allowlist config.trustedProxies fehlt/falsch — App sieht Traefik-Pod-IP statt Tailscale-IP, siehe Absicherung
carplay-api.prod.homeserver löst nicht auf Wildcard-DNS prüfen: nslookup carplay-api.prod.homeserver (siehe capulus-core/c-netzwerk-dns/c0000-dns-architecture.md)