Guardrail

Geltungsbereich: namespaced · Modi: catalog (gebündelte Engine) · external (eigener HTTP-Endpunkt) · Lizenziert: guardrail (Enterprise)

Ein Guardrail definiert eine Datenpfad-Schutzmaßnahme — Inhaltsmoderation / PII-Behandlung, die im Anfragepfad eines Gateways läuft. Referenziere sie aus einem Gateway über spec.guardrailRefs; der Operator erzeugt die vorgelagerte LiteLLMGuardrail-Verdrahtung für dich.

Beide Modi erfordern das lizenzierte guardrail-Feature, und beide werden durch einen kleinen Lizenz-Gate-Proxy geleitet, den der Operator vor die Schutzmaßnahme schaltet. Der Proxy prüft die signierte Lizenz und schließt im Fehlerfall (fail closed): Läuft die Lizenz aus, wird sie widerrufen oder entfernt, erhält jede Anfrage ein Guardrail-Block-Verdikt, statt weitergeleitet zu werden — die Schutzmaßnahme bringt keinen Nutzen mehr, sobald du nicht mehr lizenziert bist. Ohne Lizenz wird das Guardrail abgelehnt (Refused) und nichts verdrahtet.

Spec

Feld	Typ	Beschreibung
mode	enum catalog | external (erforderlich)	Gebündelte Engine vs. eigener HTTP-Endpunkt
catalog	string	Schlüssel der gebündelten Engine (mode=catalog), z. B. pseudonymizer
external	object	Dein HTTP-Guardrail (mode=external)
guardrailName	string	Überschreibt den LiteLLM-guardrail_name (Standard: Katalogschlüssel oder CR-Name)
modes	[]enum pre_call | post_call | during_call | logging_only	Ausführungsmodi; pro Modus wird ein LiteLLMGuardrail erzeugt. Standard: die Modi der Engine (der Pseudonymizer läuft pre_call+post_call) oder [pre_call] für external
defaultOn	bool	Bei jeder Anfrage aktiv, auch ohne explizites Key-/Team-Opt-in. Katalog-Engines sind standardmäßig an, external standardmäßig aus
params	object (beliebiges JSON)	Provider-Parameter, an LiteLLM unter additional_provider_specific_params weitergereicht (über die Engine-Standardwerte gemischt)
logLevel	enum debug | info | warn | error	Log-Ausführlichkeit des Lizenz-Gate-Proxys. debug protokolliert einen Datensatz pro Guardrail-Anfrage — siehe Fehlersuche. Eine Änderung startet den Proxy-Pod neu
blockedReason	string	Meldung, die der Proxy zurückgibt, wenn er eine Anfrage mangels Lizenz blockt. Wähle sie unterscheidbar, um eine Lizenz-Gate-Blockade in den Gateway-Logs zu erkennen

external

Feld	Beschreibung
apiBase	Dein Guardrail-HTTP-Endpunkt (LiteLLM generic_guardrail_api; POST an {apiBase}/beta/litellm_basic_guardrail_api)
apiKeySecretRef	Secret im selben Namespace, dessen Wert der Proxy als x-api-key an deinen Endpunkt weiterleitet
unreachableFallback	fail_closed (Standard) oder fail_open — LiteLLMs Verhalten, wenn der Guardrail nicht erreichbar ist

Modi

• catalog — der Operator stellt die gebündelte Engine als ein gemeinsames, referenzgezähltes Release für den Cluster bereit (in navique-guardrail-system) und schaltet pro Guardrail einen Lizenz-Gate-Proxy davor. Die erste Engine ist pseudonymizer (PII-Pseudonymisierung: maskiert Personen-/Organisationsnamen, bevor das Modell sie sieht, und stellt sie in der Antwort wieder her). Seit 0.4.0 bedient sie zusätzlich das Wäg-Guardrail-Protokoll auf einem zweiten Endpunkt — gegen denselben Mapping-Store.
• external — der Operator stellt nur den Lizenz-Gate-Proxy bereit, gerichtet auf deinen apiBase. Weiterhin lizenziert und proxied (anders als externe MCP-Server sind eigene Guardrails nicht kostenlos).

Verdrahtung in ein Gateway

Füge das Guardrail zu guardrailRefs eines Gateways hinzu. Sobald das Guardrail Ready ist, erzeugt das Gateway pro Modus ein LiteLLMGuardrail, dessen apiBase der Lizenz-Gate-Proxy des Guardrails ist (status.endpoint) — niemals die reine Engine. Entfernen der Referenz (oder Löschen des Guardrails) räumt die erzeugte Verdrahtung ab.

Beispiel — gebündelter PII-Pseudonymizer

apiVersion: core.navique.com/v1alpha1
kind: Guardrail
metadata:
  name: pii-pseudonymizer
  namespace: forge
spec:
  mode: catalog
  catalog: pseudonymizer
---
apiVersion: core.navique.com/v1alpha1
kind: Gateway
metadata:
  name: forge-gw
  namespace: forge
spec:
  # … database/instance/secrets …
  guardrailRefs:
    - { name: pii-pseudonymizer }

Beispiel — eigener HTTP-Guardrail

apiVersion: core.navique.com/v1alpha1
kind: Guardrail
metadata:
  name: my-moderation
  namespace: forge
spec:
  mode: external
  modes: [pre_call]
  external:
    apiBase: https://guardrail.example.com
    unreachableFallback: fail_closed
    apiKeySecretRef: { name: my-guardrail-key, key: apiKey }

Fehlersuche bei einem fehlgeschlagenen Guardrail-Aufruf

Eine Guardrail-Blockade ist für den Aufrufer bewusst nicht von anderen Fehlern zu unterscheiden. Damit bleiben drei Fehlerbilder, die vom Gateway aus identisch aussehen:

1. Das Gateway hat den Guardrail nie aufgerufen und die Anfrage aus einem anderen Grund abgebrochen,
2. der Lizenz-Gate-Proxy hat geblockt (nicht lizenziert / abgelaufen / widerrufen),
3. die Engine hat geblockt oder war nicht erreichbar.

Nur der Proxy sieht alle drei Fälle — er meldet sie auf zwei Wegen.

Zähler (immer aktiv)

Jeder Proxy liefert Prometheus-Zähler auf Port 9090 aus, getrennt vom Datenport (8080), damit sie keinen Pfad deiner Guardrail-Engine verdecken:

kubectl port-forward -n forge svc/pii-pseudonymizer-guardrail-proxy 9090:9090
curl -s localhost:9090/metrics

Metrik	Beantwortet
navique_guardrail_proxy_requests_total{decision="forwarded"}	Hat das Gateway den Guardrail überhaupt aufgerufen? Ein unveränderter Zähler heißt: nein
…{decision="blocked_unlicensed"}	Hat das Lizenz-Gate geblockt?
…{decision="upstream_error"}	War die Engine nicht erreichbar?
navique_guardrail_proxy_upstream_verdicts_total{action="…"}	Wie hat die Engine entschieden — NONE, GUARDRAIL_INTERVENED oder BLOCKED?
navique_guardrail_proxy_upstream_duration_seconds_{sum,count}	Wie langsam sind die Engine-Aufrufe?
navique_guardrail_proxy_license_valid	Erfüllt die eingehängte Lizenz derzeit guardrail?

Protokollierung pro Anfrage

Setze spec.logLevel: debug am Guardrail (das startet den Proxy-Pod neu), um pro Anfrage einen strukturierten Datensatz zu erhalten:

{"level":"DEBUG","msg":"guardrail request","request_id":"9f2c…","method":"POST",
 "path":"/beta/litellm_basic_guardrail_api","decision":"forwarded","status":200,
 "duration_ms":37,"upstream_action":"BLOCKED","upstream_blocked_reason":"…"}

decision ist das, was der Proxy getan hat; upstream_action ist das Urteil der Engine selbst, aus der Antwort gelesen, ohne sie zu verändern. Der Header X-Request-Id wird vom Aufrufer übernommen, andernfalls erzeugt, an die Engine weitergereicht und in der Antwort zurückgegeben — eine einzige ID verbindet so die Logs von Gateway, Proxy und Engine.

WARNING

upstream_blocked_reason ist die Meldung der Engine und kann den Inhalt zitieren, auf den sie angesprungen ist. Erhöhe logLevel zur Untersuchung und senke ihn danach wieder.

Zwei Dinge, die der Proxy bewusst nicht verschleiert

• Eine nicht erreichbare Engine liefert HTTP 502, keine Blockade. „Die Engine ist down" ist nicht „die Engine hat dich geblockt": LiteLLM wendet auf einen Transportfehler den unreachableFallback (fail_closed / fail_open) an, und eine vorgetäuschte Blockade würde ein fail_open stillschweigend aushebeln. Solche Fehler werden unabhängig von logLevel auf error-Ebene protokolliert.
• Lizenz-Gate-Blockaden werden beim Umschalten protokolliert. Der Proxy schreibt eine Warnung, sobald die Lizenz guardrail nicht mehr erfüllt (und eine Info-Zeile, sobald wieder), ein Ablauf ist also auch ohne Debug-Logging sichtbar. Beachte: /healthz und /readyz bleiben im Fail-closed-Zustand bei 200 — der Pod ist gesund, die Durchsetzung erfolgt pro Anfrage. Schließe also nicht von der Pod-Readiness auf den Lizenzstatus, nimm dafür navique_guardrail_proxy_license_valid.

Hinweise

• Ein versierter Betreiber könnte ein rohes vorgelagertes LiteLLMGuardrail selbst anlegen, um das Lizenz-Gate zu umgehen; die Plattform vermeidet Admission-Webhooks, daher ist das In-Core-Gate „best effort" — nur der unterstützte, verwaltete Pfad ist abgesichert.
• Der Lizenz-Gate-Proxy ist ein separates, Closed-Source-Image (ghcr.io/scigility/navique-guardrail-proxy); überschreibbar mit --guardrail-proxy-image oder dem Registry-Host-Mirror der PlatformConfig.

Status

{ phase, endpoint (die Proxy-URL, die das Gateway verdrahtet), guardrailNames, unreachableFallback, conditions, observedGeneration }. Kurzname gr.