PKR-Lab

ALAMOS-Webhook-Relay (öffentlicher Proxy vor n8n)

Quelle: pkr-lab/pkr-lab-docs/capulus/capulus-core/3-apps-workloads/300i0-alamos-relay.md

ALAMOS-Webhook-Relay (öffentlicher Proxy vor n8n)

Cluster: TECH · Ordner argocd/apps/tech/alamos-relay/ · URL https://alamos-relay-prod.pke-lab.de (extern), alamos-relay.prod.homeserver (intern). kubectl-Befehle in diesem Doc gelten für den TECH-Cluster (Zugriff je Cluster).

Kleiner, einzweckiger Proxy: nimmt den ALAMOS-Einsatzalarm-Webhook
öffentlich unter einem geheimen Pfad entgegen und reicht ihn
Server-zu-Server an den internen n8n-Webhook weiter (siehe
300h0-alamos-einsatz-zammad.md). n8n
selbst bleibt dabei komplett unerreichbar aus dem Internet
— genau die
Entscheidung, die für n8n.prod.homeserver schon einmal bewusst getroffen
wurde (c0030: n8n ist aus dem Cloudflare-Tunnel entfernt).

Warum dieser Umweg nötig ist

Der direkte Weg — ALAMOS ruft n8n.prod.homeserver selbst auf — hat aus
zwei möglichen Gründen nicht funktioniert (siehe
300h0, Architektur):

  1. Private Network Access (PNA): Feuert der Webhook aus dem
    Kiosk-Chromium-Tab (AMweb-Seiteneinstellung-Variante), blockt der
    Browser standardmäßig JS-Requests von einer öffentlichen Origin
    (amweb.alamos.cloud) zu einer privaten Ziel-IP — und
    n8n.prod.homeserver löst intern auf eine private IP auf.
  2. "Allgemeine Webhooks" feuert serverseitig direkt von Alamos' Cloud —
    dann braucht es unabhängig von PNA ohnehin eine öffentlich erreichbare
    Ziel-URL.

Beide Fälle laufen auf dasselbe Ziel hinaus: eine öffentlich erreichbare
Adresse, hinter der nicht n8n selbst hängt. alamos-relay ist genau
diese Adresse — sie löst öffentlich auf einer Cloudflare-IP auf, PNA greift
also nicht mehr, unabhängig davon, welche der beiden Alamos-Webhook-Varianten
tatsächlich genutzt wird.

Architektur

ALAMOS AMweb (Cloud, Browser-Tab ODER Alamos-Server)
   │  Webhook GET/POST, an eine öffentliche, unlistbare URL
   ▼
https://alamos-relay-prod.pke-lab.de/relay/<TOKEN>
   │  Cloudflare Tunnel (Wildcard-Regel *.pke-lab.de → Traefik,
   │  siehe capulus-core/c-netzwerk-dns/c0040-domain-tiers.md)
   ▼
Pod im eigenen Namespace "alamos-relay"
   │  - Pfad muss exakt "/relay/<TOKEN>" sein (hmac.compare_digest,
   │    konstante Laufzeit) — jede andere Pfad/Methode-Kombination
   │    bekommt dieselbe 404-Antwort, keine Unterscheidbarkeit
   │  - NetworkPolicy erlaubt Egress NUR zu n8n:5678 (+ DNS) — selbst bei
   │    Kompromittierung kein Zugriff auf irgendwas anderes im Cluster
   ▼
http://n8n.n8n.svc.cluster.local/webhook/alamos-einsatz
   (Server-zu-Server-Call innerhalb des Clusters — kein Browser, kein PNA)
   ▼
bestehender n8n-Workflow alamos-einsatz-to-zammad.json
   (Webhook prüft den Header "Authorization: Bearer <n8nToken>", den der Relay mitsendet)

Die Antwort von n8n (Status + Body) wird 1:1 an ALAMOS zurückgegeben, damit
sich für Alamos nichts an der Rückmeldung ändert.

Warum ein eigener Namespace statt eines Pfads direkt an n8n

Cloudflare Tunnel könnte theoretisch auch einen Pfad direkt zu n8n
durchreichen, ohne einen eigenen Proxy zu bauen. Bewusst nicht so
gelöst: n8n läuft im selben Prozess wie alle anderen Workflows (Zammad-
Tickets, GitHub-Release-Watcher, xibosignage) — ein Flood/Exploit gegen
einen öffentlich erreichbaren Pfad könnte potenziell den ganzen n8n-Prozess
treffen, nicht nur diesen einen Workflow. alamos-relay kennt dagegen
keine Credentials, keine Zammad-Tokens, keine Workflows — es gibt dort
nichts zu stehlen, und die NetworkPolicy verhindert jede Seitwärtsbewegung
selbst im Worst Case.

Cluster-Komponente: Helm Chart alamos-relay

Liegt unter argocd/apps/tech/alamos-relay/, wird wie jede andere App
automatisch von ArgoCD erkannt und ausgerollt (siehe
capulus-core/b-kubernetes-gitops/b0010-argocd.md) — keine manuelle
Registrierung im ArgoCD-Sinn nötig. Aber: die NetworkPolicy-Verfeinerung
(Egress-Deny + n8n-Ausnahme) läuft über Ansible, nicht über den Chart
selbst — siehe Rollout unten.

Wichtigste values.yaml-Knobs:

Key Bedeutung
n8nTargetUrl Internes n8n-Webhook-Ziel, an das weitergereicht wird (Default: http://n8n.n8n.svc.cluster.local/webhook/alamos-einsatz)
n8nNamespace / n8nTargetPort Für die NetworkPolicy-Egress-Ausnahme — muss zu n8ns tatsächlichem Namespace/targetPort passen
secrets.encryptedToken SealedSecret mit dem geheimen Pfad-Token (Key token)
secrets.encryptedN8nToken Selber SealedSecret, Key n8nToken: Bearer-Token, das der Relay als Authorization-Header an den n8n-Webhook sendet (Credential Webhook alamos-einsatz in n8n, siehe 30070)
ingress.hosts Interner Host (alamos-relay.prod.homeserver) + externer Host (alamos-relay-prod.pke-lab.de, per Cloudflare-Tunnel-Wildcard erreichbar)

Tech-Stack identisch zu alamos-apager: reines
Python-Stdlib (http.server), kein externer Build, python:3.14-alpine
als Base-Image.

Token erzeugen/rotieren

openssl rand -hex 24 | tr -d '\n' | kubeseal --raw \
  --namespace alamos-relay \
  --name alamos-relay-secrets \
  --controller-namespace sealed-secrets \
  --controller-name sealed-secrets-controller \
  --from-file=/dev/stdin

Ausgabe in argocd/apps/tech/alamos-relay/values.yaml unter
secrets.encryptedToken eintragen, committen, pushen. Das Klartext-Token
selbst nicht committen — es steht ausschließlich in der Alamos-
Webhook-Konfiguration (siehe Einrichtung unten) und lokal
beim Erzeugen.

Rotation: einfach den Befehl erneut ausführen (neues Token), den neuen
Wert committen/pushen und die neue vollständige URL in der
Alamos-Webhook-Konfiguration nachtragen — bis dahin bekommt Alamos vom
Relay nur noch 404 (siehe Fehlerbehebung).

Rollout (nach dem ersten Push)

  1. git add/commit/push — ArgoCD legt den Namespace alamos-relay
    an und rollt den Chart aus (Pod, Service, Ingress, SealedSecret, eigene
    Egress-NetworkPolicies).
  2. Zusätzlich nötig, weil neue Namespaces/Cross-Namespace-Ausnahmen nicht
    rein über ArgoCD laufen
    (siehe
    capulus-core/d-sicherheit/d0030-network-policies.md):
    make argocd
    
    Das setzt das security-tier-Label auf dem neuen Namespace, wendet die
    ansible-verwaltete tier-default-ingress-Policy darauf an (erlaubt
    Traefik/kube-system + cloudflared, damit der Pod überhaupt erreichbar
    ist) und ergänzt in n8ns eigener Policy die Ausnahme für Ingress aus
    alamos-relay (argocd_network_policy_extra_ingress →
    n8n: [alamos-relay]). Ohne diesen Schritt bleibt der Forward an n8n
    von der eigenen networkpolicy-allow-egress-n8n-Regel des Relays zwar
    erlaubt, aber n8n selbst weist die eingehende Verbindung weiterhin ab

    (verfeinerte Policy lässt nur den eigenen Namespace + kube-system +
    monitoring + cloudflared rein).
  3. Validieren:
    kubectl -n alamos-relay get pods
    kubectl get networkpolicy -n alamos-relay
    curl -s -o /dev/null -w "%{http_code}\n" https://alamos-relay-prod.pke-lab.de/relay/falsches-token   # erwartet: 404
    

Einrichtung

  1. Token erzeugen, Chart ausrollen, siehe oben.
  2. Öffentliche Ziel-URL zusammensetzen:
    https://alamos-relay-prod.pke-lab.de/relay/<TOKEN>.
  3. Diese URL in der AMweb-Seiteneinstellung-Webhook-Konfiguration im
    Alamos-Account eintragen (nicht "Allgemeine Webhooks" — Begründung dazu
    unverändert in 300h0, Architektur).
    Der n8n-seitige Workflow (alamos-einsatz-to-zammad.json) braucht dafür
    keine Änderung am Pfad — er lauscht weiterhin auf
    http://n8n.prod.homeserver/webhook/alamos-einsatz, nur der Aufrufer
    hat sich geändert (Relay statt Alamos direkt).
  4. Testauslösung wie in
    300h0, Einrichtung Schritt 7.

Fehlerbehebung

Symptom Check
Relay antwortet mit 404 auf die volle URL inkl. Token Token in values.yaml/Alamos-Konfiguration identisch? Nach Rotation beide Stellen aktualisiert? Wurde beim Versiegeln ein Zeilenumbruch mitversiegelt? Der Pfadvergleich ist exakt, ein mitversiegeltes \n macht den Pfad dauerhaft unmatchbar (Befehl oben mit tr -d '\n', siehe 60030)
Relay antwortet nicht mehr, obwohl der Pod läuft Früher blockierte eine einzelne offene Verbindung den ganzen Dienst, jetzt bedient er mehrere Verbindungen und trennt untätige nach 10 Sekunden. Bleibt es trotzdem hängen: kubectl -n alamos-relay logs deploy/alamos-relay (Zugriffszeilen zeigen das Token als ***)
Relay antwortet 502 upstream unavailable kubectl -n alamos-relay logs deploy/alamos-relay — meist NetworkPolicy-Problem (Schritt 2 aus Rollout vergessen) oder n8n-Workflow nicht aktiv
alamos-relay-prod.pke-lab.de löst nicht auf / liefert 404 von Cloudflare Cloudflare-Tunnel-Wildcard-DNS prüfen (siehe e0000-cloudflare-tunnel.md) — dig +short alamos-relay-prod.pke-lab.de
Forward kommt bei n8n nie an, Relay selbst loggt aber 200-Antworten von n8n nicht kubectl -n n8n logs deploy/n8n — Workflow überhaupt aktiv? Gleiche Checks wie in 300h0, Fehlerbehebung
Relay-Pod crasht mit "RELAY_TOKEN und N8N_TARGET_URL muessen gesetzt sein" SealedSecret nicht entschlüsselt/nicht gefunden — kubectl -n alamos-relay get secret alamos-relay-secrets