ChatUI

Ambito: namespaced · Workload: LibreChat tramite il chart ufficiale

La UI web di LibreChat, collegata a un Gateway. Richiede MongoDB e usa facoltativamente Meilisearch per la ricerca; entrambi sono risorse datastore di prima classe che la ChatUI si limita a referenziare.

Spec

Campo	Tipo	Descrizione
secretsRef	LocalRef (opzionale)	SecretsManagement nello stesso namespace da attendere. Omettilo per usare semplici Secret Kubernetes gestiti da te — vedi secretsRef
gatewayRef	ObjectRef	Un Gateway (collegato automaticamente se la licenza lo consente)
gateway	object	Fallback manuale dell'endpoint: { url, apiKeySecretRef: { name, key } }. key può essere qualsiasi voce del Secret (predefinito LITELLM_API_KEY); solo quel valore raggiunge LibreChat, non il resto del Secret
models[]	list	Elenco dei modelli esposto ai client. Il primo è il predefinito e dà il titolo alle nuove chat. Vuoto = tutti i modelli offerti dal gateway (le chat ricevono allora il titolo dal modello in uso): vengono elencati i nomi dei modelli del gateway referenziato, e anche i modelli aggiunti in seguito compaiono. Obbligatorio quando il gateway è indicato tramite gateway.url — i suoi modelli non possono essere individuati
agents	bool	L'endpoint Agents di LibreChat. Disabilitato di default (interface.agents: false); imposta true per abilitarlo
host	string	Hostname della UI
ingress	object	className, basic-auth, TLS
mongo	DatastoreRef (obbligatorio)	Lo store MongoDB di LibreChat
meilisearch	MeilisearchRef	Backend di ricerca (opzionale)
subcharts	object	Interruttori dei subchart di LibreChat (solo redis/ragApi)
values	object	Overlay libero di valori Helm per il chart librechat (vedi Valori personalizzati del chart)
imageVolume	object	PVC per le immagini caricate
sso	object	Login OIDC/SSO per LibreChat (vedi SSO)
mcpRefs[]	lista di ObjectRef	CR MCPServer da collegare (cross-namespace consentito). Referenziarne uno qualsiasi abilita automaticamente Agents (vedi Server MCP)

mongo (obbligatorio)

Modalità	Descrizione
ref	Un MongoCluster + databaseName (predefinito LibreChat, che deve essere dichiarato in databases[] del cluster)
external	Un connectionSecretRef che contiene MONGO_URI

MongoDB è un'infrastruttura obbligatoria, quindi non è soggetto a licenza.

meilisearch (opzionale)

Modalità	Descrizione
ref (predefinito)	Una MeilisearchInstance
external	host + masterKeySecretRef
disabled	Ricerca disattivata

I subchart MongoDB e Meilisearch inclusi in LibreChat sono sempre disabilitati — questi datastore sono gestiti dalle rispettive risorse.

Cosa installa

Il controller installa il chart librechat come release standalone nel namespace della ChatUI, più la ConfigMap di configurazione del Forge Gateway. Traduce la risorsa in valori del chart (URL di base del gateway, elenco dei modelli, host dell'ingress + basic-auth, nomi dei secret ESO, MONGO_URI / MEILI_HOST risolti, interruttori dei subchart).

Per Meilisearch, il controller copia la master key risolta in un Secret di sua proprietà nello stesso namespace, <ui>-meili-key, e inietta MEILI_MASTER_KEY tramite global.librechat.env — così anche una MeilisearchInstance in un altro namespace funziona.

Endpoint Agents

LibreChat viene distribuito con l'endpoint Agents abilitato. L'operatore lo disattiva di default — scrive interface.agents: false in librechat.yaml — così una ChatUI nuova non espone la creazione di agenti. Per riattivarlo:

spec:
  agents: true

Referenziare un qualsiasi server MCP attiva anche Agents, perché LibreChat espone gli strumenti MCP attraverso di essi. In tal caso l'operatore concede solo ciò che serve agli strumenti:

Come sono stati abilitati gli Agents	use (eseguire agenti)	create (builder di agenti nella UI)
spec.agents: true (attivazione esplicita)	✅	✅
implicitamente, collegando un server MCP	✅	❌

Questo è importante perché in LibreChat la creazione di agenti non è riservata agli admin: i permessi vengono emessi come oggetto anziché come semplice true, che erediterebbe il valore predefinito create: true di LibreChat e mostrerebbe il builder di agenti a tutti gli utenti. share/public restano disattivati in entrambi i casi.

Valori personalizzati del chart

Non tutte le opzioni del chart librechat sono modellate come campi del CRD. spec.values è un oggetto libero unito ai valori del chart, così puoi impostare qualsiasi cosa il chart supporti (numero di repliche, risorse dei pod, annotation aggiuntive, …) senza attendere un nuovo campo del CRD:

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

Le chiavi gestite dall'operatore prevalgono. I tuoi valori sono la base; i valori calcolati dall'operatore (cablaggio dei datastore, riferimenti ai secret, gli interruttori enabled dei subchart inclusi e l'ambiente di tracing/SSO che inietta) vengono sovrapposti, quindi spec.values non può compromettere il cablaggio da cui dipende l'operatore. Usa i campi dedicati (mongo, meilisearch, subcharts, agents, sso, …) per tutto ciò che l'operatore modella; riserva spec.values ai casi residui.

Collegamento al Gateway

• Con la funzionalità auto-wiring e un gatewayRef, il controller genera una LiteLLMVirtualKey sul Gateway referenziato, la memorizza in un Secret di sua proprietà e inietta baseURL = http://<gw-svc>.<gw-ns>.svc.cluster.local:4000/v1 insieme alla chiave.
• Senza di essa, fornisci manualmente gateway.{ url, apiKeySecretRef }. Vedi Auto-Wiring.

Login SSO / OIDC

spec.sso abilita il provider OpenID Connect di LibreChat — attiva ALLOW_SOCIAL_LOGIN e inietta l'ambiente OPENID_*. Le credenziali del client OAuth provengono da un Secret nello stesso namespace (tramite SecretsManagement); l'operatore genera da sé l'OPENID_SESSION_SECRET e collega DOMAIN_SERVER/DOMAIN_CLIENT all'URL pubblico della UI, così le callback vengono risolte.

Campo	Descrizione
issuerURL	URL di base dell'issuer / discovery OIDC
clientSecretRef.name	Secret che contiene il client OAuth (chiavi predefinite client-id / client-secret)
scopes	Scope richiesti (predefiniti openid, profile, email)
providerName	Etichetta del pulsante di login

I campi provider, tenantID e degli endpoint espliciti del tipo SSO condiviso sono solo per il Gateway e qui vengono ignorati (LibreChat ricava gli endpoint da issuerURL).

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

Server MCP

spec.mcpRefs collega CR MCPServer (catalogo incluso o esterni) all'endpoint Agents di LibreChat. Referenziare un qualsiasi server abilita automaticamente Agents; l'operatore genera la configurazione mcpServers e, per le destinazioni interne al cluster, la allowlist SSRF mcpSettings — automaticamente.

spec:
  mcpRefs:
    - { name: websearch }            # an MCPServer in this namespace
    - { name: docs, namespace: team } # cross-namespace allowed

Impostazioni predefinite rafforzate e modello di amministrazione

L'operatore genera sempre un'interfaccia LibreChat rafforzata, indipendentemente dall'uso di MCP:

• Web Search e Code Interpreter nativi sono DISATTIVATI (interface.webSearch: false, interface.runCode: false). Il web_search MCP è il percorso supportato per la ricerca web.
• Gli utenti non possono aggiungere o disattivare server MCP dalla UI — admin compresi (il permesso interface.mcpServers è bloccato su use soltanto). Solo la configurazione dell'operatore (i tuoi CR MCPServer) li definisce.
• Nessun admin reale: su una ChatUI nuova l'operatore crea un admin fantasma riservato e mai utilizzato (password casuale interna al Job, mai persistita) per occupare lo slot di LibreChat "il primo utente registrato diventa ADMIN", così tutti gli utenti reali (CR Identity, SSO) vengono creati come USER. Gli admin preesistenti non vengono toccati.

Esempio

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            # default — LibreChat Agents endpoint off
  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:                  # free-form chart overlay (operator keys still win)
    replicaCount: 2

Stato

Disponibilità del Deployment e host dell'ingress, più i consueti conditions e observedGeneration.