ChatUI

Geltungsbereich: namespaced · Workload: LibreChat über das offizielle Chart

Die LibreChat-Weboberfläche, verdrahtet mit einem Gateway. Sie benötigt MongoDB und nutzt optional Meilisearch für die Suche; beide sind erstklassige Datenspeicher-Ressourcen, die ChatUI lediglich referenziert.

Spec

Feld	Typ	Beschreibung
secretsRef	LocalRef (optional)	SecretsManagement im selben Namespace, auf die gewartet wird. Weglassen, um selbst verwaltete, gewöhnliche Kubernetes-Secrets zu verwenden — siehe secretsRef
gatewayRef	ObjectRef	Ein Gateway (automatisch verdrahtet, sofern lizenziert)
gateway	object	Manueller Endpunkt-Fallback: { url, apiKeySecretRef: { name, key } }. key darf ein beliebiger Eintrag des Secrets sein (Standard LITELLM_API_KEY); nur dieser Wert erreicht LibreChat, nicht der Rest des Secrets
models[]	list	Client-seitige Modellliste. Das erste Modell ist die Voreinstellung und benennt neue Chats. Leer = alle Modelle des Gateways (Chats werden dann mit dem verwendeten Modell benannt): Die Modellnamen des referenzierten Gateways werden aufgeführt, später hinzugefügte Modelle erscheinen weiterhin. Pflicht, wenn das Gateway per gateway.url angegeben ist — dessen Modelle lassen sich nicht ermitteln
agents	bool	Agents-Endpunkt von LibreChat. Standardmäßig deaktiviert (interface.agents: false); auf true setzen, um ihn zu aktivieren
host	string	Hostname der UI
ingress	object	className, Basic-Auth, TLS
mongo	DatastoreRef (erforderlich)	MongoDB-Speicher von LibreChat
meilisearch	MeilisearchRef	Such-Backend (optional)
subcharts	object	Subchart-Schalter von LibreChat (nur redis/ragApi)
values	object	Frei wählbares Helm-Werte-Overlay für das librechat-Chart (siehe Eigene Chart-Werte)
imageVolume	object	PVC für hochgeladene Bilder
sso	object	OIDC/SSO-Login für LibreChat (siehe SSO)
mcpRefs[]	Liste von ObjectRef	MCPServer-CRs zum Einbinden (namespaceübergreifend erlaubt). Referenzieren aktiviert Agents automatisch (siehe MCP-Server)

mongo (erforderlich)

Modus	Beschreibung
ref	Ein MongoCluster + databaseName (Standard LibreChat, der in den databases[] des Clusters deklariert sein muss)
external	Ein connectionSecretRef, das MONGO_URI enthält

MongoDB ist erforderliche Infrastruktur und daher nicht lizenzgebunden.

meilisearch (optional)

Modus	Beschreibung
ref (Standard)	Eine MeilisearchInstance
external	host + masterKeySecretRef
disabled	Suche deaktiviert

Die mitgelieferten LibreChat-Subcharts für MongoDB und Meilisearch sind immer deaktiviert — diese Datenspeicher werden durch ihre eigenen Ressourcen verwaltet.

Was es installiert

Der Controller installiert das librechat-Chart als eigenständiges Release im ChatUI-Namespace, zuzüglich der Forge-Gateway-Konfigurations-ConfigMap. Er übersetzt die Ressource in Chart-Werte (Gateway-Basis-URL, Modellliste, Ingress-Host + Basic-Auth, ESO-Secret-Namen, aufgelöste MONGO_URI / MEILI_HOST, Subchart-Schalter).

Für Meilisearch kopiert der Controller den aufgelösten Master-Key in ein eigenes Secret <ui>-meili-key im selben Namespace und injiziert MEILI_MASTER_KEY über global.librechat.env — so funktioniert auch eine MeilisearchInstance in einem anderen Namespace.

Agents-Endpunkt

LibreChat liefert seinen Agents-Endpunkt aktiviert aus. Der Operator schaltet ihn standardmäßig ab — er rendert interface.agents: false in die librechat.yaml —, sodass eine frische ChatUI keinen Agent-Builder bereitstellt. Wieder einschalten lässt er sich mit:

spec:
  agents: true

Das Referenzieren eines MCP-Servers aktiviert Agents ebenfalls, da LibreChat MCP-Werkzeuge über sie bereitstellt. In diesem Fall gewährt der Operator nur das, was die Werkzeuge benötigen:

Wie Agents aktiviert wurden	use (Agents ausführen)	create (Agent-Builder in der UI)
spec.agents: true (ausdrücklich)	✅	✅
implizit, durch Einbinden eines MCP-Servers	✅	❌

Das ist wichtig, weil das Erstellen von Agents in LibreChat nicht auf Admins beschränkt ist: Die Berechtigungen werden als Objekt statt als einfaches true ausgegeben — Letzteres würde LibreChats Standardwert create: true übernehmen und den Agent-Builder allen Benutzern zeigen. share/public bleiben in beiden Fällen deaktiviert.

Eigene Chart-Werte

Nicht jede librechat-Chart-Option ist als CRD-Feld modelliert. spec.values ist ein frei wählbares Objekt, das in die Chart-Werte eingemischt wird, sodass Sie alles setzen können, was das Chart unterstützt (Replikat-Anzahl, Pod-Ressourcen, zusätzliche Annotationen, …), ohne auf ein neues CRD-Feld warten zu müssen:

spec:
  values:
    replicaCount: 2
    librechat:
      resources:
        limits: { cpu: "2", memory: 2Gi }

Vom Operator verwaltete Schlüssel gewinnen. Ihre Werte bilden die Basis; die vom Operator berechneten Werte (Datenspeicher-Verdrahtung, Secret-Referenzen, die enabled-Schalter der mitgelieferten Subcharts sowie die injizierten Tracing-/SSO-Env) werden darüber gelegt, sodass spec.values die Verdrahtung, auf die der Operator angewiesen ist, nicht zerstören kann. Verwenden Sie die dedizierten Felder (mongo, meilisearch, subcharts, agents, sso, …) für alles, was der Operator modelliert; reservieren Sie spec.values für den langen Rest.

Gateway-Verdrahtung

• Mit dem Feature auto-wiring und einem gatewayRef erzeugt der Controller einen LiteLLMVirtualKey auf dem referenzierten Gateway, speichert ihn in einem eigenen Secret und injiziert baseURL = http://<gw-svc>.<gw-ns>.svc.cluster.local:4000/v1 zuzüglich des Keys.
• Ohne dieses Feature geben Sie gateway.{ url, apiKeySecretRef } manuell an. Siehe Auto-Wiring.

SSO / OIDC login

spec.sso aktiviert den OpenID-Connect-Provider von LibreChat — es schaltet ALLOW_SOCIAL_LOGIN ein und injiziert die OPENID_*-Umgebungsvariablen. Die OAuth-Client-Anmeldedaten stammen aus einem Secret im selben Namespace (über SecretsManagement); der Operator erzeugt das OPENID_SESSION_SECRET selbst und verdrahtet DOMAIN_SERVER/DOMAIN_CLIENT mit der öffentlichen URL der UI, damit Callbacks aufgelöst werden.

Feld	Beschreibung
issuerURL	OIDC-Issuer-/Discovery-Basis-URL
clientSecretRef.name	Secret mit dem OAuth-Client (Schlüssel standardmäßig client-id / client-secret)
scopes	Angeforderte Scopes (Standard openid, profile, email)
providerName	Beschriftung der Login-Schaltfläche

Die Felder provider, tenantID und die Felder für explizite Endpunkte des gemeinsamen SSO-Typs sind ausschließlich für das Gateway und werden hier ignoriert (LibreChat leitet die Endpunkte aus issuerURL ab).

spec:
  sso:
    issuerURL: https://idp.example.com
    providerName: "Acme SSO"
    clientSecretRef: { name: chatui-oidc }

MCP-Server

spec.mcpRefs bindet MCPServer-CRs (gebündelter Katalog oder extern) in den Agents-Endpunkt von LibreChat ein. Das Referenzieren eines beliebigen Servers aktiviert Agents automatisch; der Operator rendert die mcpServers-Konfiguration und — für clusterinterne Ziele — die SSRF-Allowlist mcpSettings automatisch.

spec:
  mcpRefs:
    - { name: websearch }             # ein MCPServer in diesem Namespace
    - { name: docs, namespace: team } # namespaceübergreifend erlaubt

Gehärtete Standardwerte & Admin-Modell

Der Operator rendert immer eine gehärtete LibreChat-Oberfläche, unabhängig von der MCP-Nutzung:

• Native Websuche und Code-Interpreter sind AUS (interface.webSearch: false, interface.runCode: false). MCP web_search ist der unterstützte Websuche-Pfad.
• Benutzer können MCP-Server nicht hinzufügen oder deaktivieren — auch Administratoren nicht (die interface.mcpServers-Berechtigung ist auf use beschränkt). Nur die Operator-Konfiguration (Ihre MCPServer-CRs) definiert sie.
• Kein echter Admin: Bei einer neuen ChatUI erstellt der Operator einen reservierten, nie genutzten Phantom-Admin (zufälliges, im Job erzeugtes, niemals gespeichertes Passwort), um den LibreChat-Slot „erster registrierter Benutzer wird ADMIN“ zu belegen, sodass alle echten Benutzer (Identity-CRs, SSO) als USER landen. Bestehende Admins bleiben unberührt.

Beispiel

apiVersion: core.navique.com/v1alpha1
kind: ChatUI
metadata:
  name: forge-ui
  namespace: forge-ui
spec:
  secretsRef: { name: chatui-secrets }
  gatewayRef: { name: gateway, namespace: forge-gateway }
  models: [ azure_ai/gpt-5.4 ]
  agents: false            # Standard — LibreChat Agents-Endpunkt aus
  host: chat.forge.example.com
  mongo:
    mode: ref
    ref: { name: forge-mongo, namespace: forge-data }
    databaseName: LibreChat
  meilisearch:
    mode: ref
    ref: { name: forge-ui-search }
  ingress:
    enabled: true
    className: nginx
    basicAuthSecret: forge-ui-basic-auth
  values:                  # frei wählbares Chart-Overlay (Operator-Schlüssel gewinnen weiterhin)
    replicaCount: 2

Status

Verfügbarkeit des Deployments und der Ingress-Host, zuzüglich der üblichen conditions und observedGeneration.