Guardrail

Portée : namespaced · Modes : catalog (moteur intégré) · external (HTTP fourni par vous) · Sous licence : guardrail (Enterprise)

Un Guardrail définit un garde-fou dans le chemin de données — modération de contenu / traitement des PII exécuté dans le chemin de la requête d'un Gateway. Référencez-le depuis un Gateway via spec.guardrailRefs ; l'opérateur produit pour vous le câblage LiteLLMGuardrail en amont.

Les deux modes nécessitent la fonctionnalité sous licence guardrail, et les deux passent par un petit proxy de contrôle de licence que l'opérateur insère devant le garde-fou. Le proxy vérifie la licence signée et échoue en mode fermé (fail closed) : si la licence expire, est révoquée ou retirée, chaque requête reçoit un verdict de blocage du garde-fou au lieu d'être transmise — le garde-fou cesse d'apporter de la valeur dès que vous n'êtes plus sous licence. Sur un cluster non licencié, le Guardrail est Refused et rien n'est câblé.

Spec

Champ	Type	Description
mode	enum catalog | external (requis)	Moteur intégré vs. votre propre endpoint HTTP
catalog	string	Clé du moteur intégré (mode=catalog), p. ex. pseudonymizer
external	object	Votre garde-fou HTTP (mode=external)
guardrailName	string	Remplace le guardrail_name LiteLLM (par défaut : la clé du catalogue ou le nom du CR)
modes	[]enum pre_call | post_call | during_call | logging_only	Modes d'exécution ; un LiteLLMGuardrail est émis par mode. Par défaut : les modes du moteur (le pseudonymizer exécute pre_call+post_call) ou [pre_call] pour external
defaultOn	bool	S'exécute sur chaque requête même sans opt-in explicite d'une clé/équipe. Les moteurs de catalogue sont activés par défaut ; external est désactivé par défaut
params	object (JSON libre)	Paramètres du fournisseur transmis à LiteLLM sous additional_provider_specific_params (fusionnés par-dessus les valeurs par défaut du moteur)
logLevel	enum debug | info | warn | error	Verbosité du proxy de contrôle de licence. debug journalise un enregistrement par requête de garde-fou — voir Diagnostic. Une modification redémarre le pod du proxy
blockedReason	string	Message renvoyé par le proxy lorsqu'il bloque une requête faute de licence. Rendez-le distinctif pour reconnaître un blocage du contrôle de licence dans les logs du Gateway

external

Champ	Description
apiBase	Votre endpoint HTTP de garde-fou (LiteLLM generic_guardrail_api ; POST vers {apiBase}/beta/litellm_basic_guardrail_api)
apiKeySecretRef	Secret du même namespace dont la valeur est transmise par le proxy à votre endpoint via x-api-key
unreachableFallback	fail_closed (défaut) ou fail_open — comportement de LiteLLM si le garde-fou est injoignable

Modes

• catalog — l'opérateur déploie le moteur intégré comme une seule release partagée et comptée par référence pour le cluster (dans navique-guardrail-system) et place devant lui un proxy de contrôle de licence par Guardrail. Le premier moteur est pseudonymizer (pseudonymisation des PII : masque les noms de personnes/d'organisations avant que le modèle ne les voie et les restaure dans la réponse). Depuis la 0.4.0, il sert également le protocole de garde-fou Wäg sur un second endpoint, contre le même magasin de correspondances.
• external — l'opérateur déploie uniquement le proxy de contrôle de licence, pointé vers votre apiBase. Toujours sous licence et proxifié (contrairement aux serveurs MCP externes, les garde-fous que vous fournissez ne sont pas gratuits).

Câblage dans un Gateway

Ajoutez le Guardrail aux guardrailRefs d'un Gateway. Une fois le Guardrail Ready, le Gateway émet un LiteLLMGuardrail par mode dont l'apiBase est le proxy de contrôle de licence du Guardrail (status.endpoint) — jamais le moteur brut. Retirer la référence (ou supprimer le Guardrail) élague le câblage émis.

Exemple — pseudonymizer PII intégré

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 }

Exemple — votre propre garde-fou HTTP

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 }

Diagnostic d'un appel de garde-fou en échec

Un blocage par garde-fou est volontairement indiscernable pour l'appelant, ce qui laisse trois scénarios d'échec identiques vus depuis le Gateway :

1. le Gateway n'a jamais appelé le garde-fou et a échoué pour une autre raison,
2. le proxy de contrôle de licence a bloqué (non licencié / expiré / révoqué),
3. le moteur a bloqué, ou était injoignable.

Le proxy est le seul composant à voir les trois ; il les rapporte de deux façons.

Compteurs (toujours actifs)

Chaque proxy expose des compteurs Prometheus sur le port 9090, distinct du port de données (8080) afin de ne pas masquer une route de votre moteur :

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

Métrique	Répond à
navique_guardrail_proxy_requests_total{decision="forwarded"}	le Gateway a-t-il seulement appelé le garde-fou ? Un compteur figé signifie que non
…{decision="blocked_unlicensed"}	est-ce le contrôle de licence qui a bloqué ?
…{decision="upstream_error"}	le moteur était-il injoignable ?
navique_guardrail_proxy_upstream_verdicts_total{action="…"}	qu'a décidé le moteur — NONE, GUARDRAIL_INTERVENED ou BLOCKED ?
navique_guardrail_proxy_upstream_duration_seconds_{sum,count}	quelle est la lenteur des appels au moteur ?
navique_guardrail_proxy_license_valid	la licence montée satisfait-elle actuellement guardrail ?

Journalisation par requête

Définissez spec.logLevel: debug sur le Guardrail (cela redémarre le pod du proxy) pour obtenir un enregistrement structuré par requête :

{"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 est ce qu'a fait le proxy ; upstream_action est le verdict du moteur lui-même, relu dans la réponse sans la modifier. L'en-tête X-Request-Id est repris de l'appelant s'il est présent, sinon généré, transmis au moteur et renvoyé dans la réponse — un seul identifiant relie ainsi les logs du Gateway, du proxy et du moteur.

WARNING

upstream_blocked_reason est le message du moteur et peut citer le contenu qui a déclenché la détection. Augmentez logLevel le temps de l'investigation, puis abaissez-le de nouveau.

Deux choses que le proxy ne masque délibérément pas

• Un moteur injoignable renvoie HTTP 502, pas un blocage. « Le moteur est hors service » n'est pas « le moteur vous a bloqué » : LiteLLM applique l'unreachableFallback (fail_closed / fail_open) à une panne de transport, et simuler un blocage écraserait silencieusement un choix fail_open. Ces échecs sont journalisés au niveau error, quel que soit logLevel.
• Les blocages du contrôle de licence sont journalisés au basculement. Le proxy écrit un avertissement dès que la licence ne satisfait plus guardrail (et une ligne d'info au retour) : une expiration reste donc visible sans journalisation debug. À noter : /healthz et /readyz restent à 200 en mode fail-closed — le pod est sain, l'application se fait par requête. Ne déduisez donc pas l'état de la licence de la readiness du pod ; utilisez navique_guardrail_proxy_license_valid.

Remarques

• Un opérateur déterminé pourrait rédiger à la main un LiteLLMGuardrail brut en amont pour contourner le contrôle de licence ; la plateforme évite les webhooks d'admission, donc le contrôle in-core est « best effort » — seul le chemin géré et pris en charge est verrouillé.
• Le proxy de contrôle de licence est une image séparée, à source fermée (ghcr.io/scigility/navique-guardrail-proxy) ; remplaçable via --guardrail-proxy-image ou le miroir de registre de la PlatformConfig.

Statut

{ phase, endpoint (l'URL du proxy que le Gateway câble), guardrailNames, unreachableFallback, conditions, observedGeneration }. Nom court gr.