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/· URLhttps://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
- Übersicht & Architektur
- power-agent
- Abweichungen vom ursprünglichen Konzept
- Ersteinrichtung
- Uptime-Kuma Status-Page anlegen
- Image bauen & pushen
- Absicherung
- Konfiguration (values.yaml)
- 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:
- die Bildschirmhelligkeit über
/sys/class/backlight/intel_backlight/
liest/schreibt (HP ProBook 450 G9, siehecapulus-ansible/a-betriebssystem/a0010-overview.md), wakeonlanfür worker-1 auslöst,- worker-1 über denselben SSH-Key wie
cluster_power_manager
herunterfährt (forced command, nursudo poweroffmöglich — siehe
capulus-ansible/2-betrieb-hardware/20020-cluster-power-manager.md), und - den Homeserver selbst herunterfährt — kein harter
poweroff, sondern
dieselbe geordnete Sequenz wie bei worker-0/worker-1:kubectl cordonkubectl drain(jeder Pod bekommt seineterminationGracePeriodzum
sauberen Beenden/Flushen, statt beim Stoppen vonk3s.service
gemeinsam gekillt zu werden), danachsystemctl stop k3s, erst dann
poweroff(lokal, da der Agent als root läuft). Läuft asynchron in
einem Background-Thread, damit die HTTP-Antwort an carplay-api noch
rausgeht, bevor dessen eigener Pod durchs Drain evictet wird. Jeder
Schritt ist Best-Effort mit Timeout (_run_best_effort()) — ein
hängendeskubectlblockiert den Poweroff nicht, da es für den
Homeserver keinen Wake-on-LAN-Weg zurück gibt.
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:
- Uptime-Kuma-API: Es gibt kein
Authorization: Bearer-geschütztes
/api/status_page/monitors. Uptime-Kumas einzige stabile Lese-API ist die
öffentliche Status-Page (/api/status-page/{slug}+
/api/status-page/heartbeat/{slug}), bewusst ohne Auth — das ist ihr
ganzer Zweck.carplay-apiliest genau diese. Folge: eine Status-Page mit
Slug muss in der Kuma-UI existieren, siehe unten. - Paketierung: Helm-Chart (
Chart.yaml/values.yaml/templates/) wie
jede andere App unterargocd/apps/, kein rohes Kustomize/kubectl-YAML —
sonst hätte die App nicht automatisch über die ArgoCD-ApplicationSet
(siehe capulus-core/b-kubernetes-gitops/b0010-argocd.md) ausgerollt werden können. - Namespace:
carplay-api, nichthomeserver-app— die
ApplicationSetleitet den Namespace aus dem Verzeichnisnamen ab. - mTLS: nicht umgesetzt. Traefik terminiert in diesem Cluster kein
Client-Zertifikat-TLS — ein "Certificate Pinning" hätte nichts geprüft,
außer einer vorgetäuschten Sicherheit. Die reale Grenze ist Bearer-Token +
optionale IP-Allowlist auf das Tailscale-Netz (siehe
Absicherung).
Ersteinrichtung
-
kubeseal-Zertifikat besorgen (einmalig, überspringen falls
~/homelab-certs/sealed-secrets.pemschon 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.pemAlternative ohne CLI/SSH-Zugriff: https://kubeseal-webgui.tech.homeserver
verschlüsselt einzelne Werte über eine Weboberfläche (Namespace
carplay-api, Secret-Namecarplay-api-token, Keytoken) — liefert
denselben Base64-Blob wie unten, ohne Schritt 1. -
API-Token erzeugen und versiegeln (Pflicht — ohne dieses Secret
bleibt der Pod inCreateContainerConfigErrorhä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/stdinDas Ergebnis in
argocd/apps/tech/carplay-api/values.yamlunter
secrets.apiToken.encryptedDataeintragen.$TOKENselbst geht in die
iOS-App (Keychain, siehecapulus-ios/README.md) — nie ins Git. -
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/stdinErgebnis in
values.yamluntersecrets.powerAgentToken.encryptedData,
dazusecrets.powerAgentToken.enabled: true. -
Shutdown-Bestätigungscode versiegeln (Pflicht für den
Homeserver-Shutdown aus der App — ohne dieses Secret bleibt
target: "homeserver"mit503blockiert, 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/stdinErgebnis in
values.yamlunter
secrets.shutdownConfirmationCode.encryptedData, dazu
secrets.shutdownConfirmationCode.enabled: true. -
Status-Page in Uptime-Kuma anlegen (siehe nächster Abschnitt) und den
Slug invalues.yamlunterconfig.uptimeKuma.slugeintragen. -
config.hostsprüfen/anpassen — ein Eintrag pro Host-Karte auf der
App-Startseite,instancemuss exakt das VictoriaMetrics-Label des
jeweiligen node-exporter-Targets treffen (Default deckt
Homeserver/worker-0/worker-1/NAS ab, siehe 60080). -
Image bauen/pushen (siehe unten) und
image.repository/image.tagsetzen. -
Committen & pushen — ArgoCD rollt automatisch aus.
Uptime-Kuma Status-Page anlegen
- https://uptime-kuma.prod.homeserver → Status-Pages → New Status Page.
- Slug vergeben (Default in
values.yaml:homeserver) — muss exakt mit
config.uptimeKuma.slugübereinstimmen. - 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). - Speichern — die Seite muss nicht öffentlich beworben werden, sie muss
nur existieren;carplay-apiliest 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):
- 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 inCrashLoopBackOff).
Nur/healthbleibt offen, die Probes des kubelet brauchen es. - IP-Allowlist (
config.ipAllowlist, default deaktiviert) —
beschränkt/api/*auf CIDR-Bereiche (Default-Vorschlag: Tailscale-CGNAT
100.64.0.0/10+ LAN192.168.178.0/24). Brauchtconfig.trustedProxies
korrekt gesetzt (steht auf dem Pod-CIDR10.42.0.0/16), sonst sieht die App Traefiks
Pod-IP statt der echten Client-IP und sperrt alles aus — deshalb vor dem
Aktivieren einmalkubectl -n carplay-api logs deploy/carplay-apiprüfen,
obclient_ipin den Request-Logs die erwartete Adresse zeigt. - Rate-Limiting (100 req/min/IP, konfigurierbar) — Backstop gegen eine
verunglückte App-Instanz, die im 30s-Intervall-Bug feststeckt. - Bestätigungscode (
SHUTDOWN_CONFIRMATION_CODE) — zusätzlich zum
Bearer-Token für genau eine Aktion:POST /api/power/shutdownmit
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) |