Zum Hauptinhalt springen

Kubernetes

Libre WebUI enthält einen Helm-Chart unter helm/libre-webui.

Work auf Kubernetes​

Work läuft nativ auf Kubernetes; weder Docker-Daemon, CLI noch Socket sind beteiligt. Aktiviere es bei der Installation:

helm install libre-webui ./helm/libre-webui --set work.enabled=true

Dadurch wechselt das Backend zu WORK_RUNTIME_BACKEND=kubernetes und erstellt:

  • einen eigenen Sandbox-Namespace (work.namespace, Standard libre-webui-work) mit einem Pod pro laufender Sandbox und einem PersistentVolumeClaim pro Aufgabenarbeitsbereich (work.workspaceSize, Standard 5Gi, ein echtes Datenträgerkontingent; benannte Richtlinien können andere Größen setzen);
  • eine namespacebegrenzte Role und RoleBinding, die dem ServiceAccount exakt pods (get/list/create/delete), pods/exec (get/create) und persistentvolumeclaims (get/list/create/delete) gewähren – keine Secrets, kein Clusterbereich. Diese Freigabe ersetzt den Docker-Socket vollständig; der API-Server erzwingt, dass eine Sandbox keine Hostpfade einbindet;
  • NetworkPolicies, die standardmäßig allen Verkehr verweigern, eingehend nur das Backend am Vorschauport erlauben und netzwerkfähigen Sandboxes ausgehenden Internetzugriff außer work.networkPolicy.blockedEgressCidrs geben (standardmäßig private Bereiche, von einigen Clustern für Pod-/Service-CIDRs verwendetes CGNAT und Cloud-Metadaten; prüfe die Abdeckung deiner CIDRs). DNS ist nur zu kube-system erlaubt; node-lokales DNS braucht eine Ausnahme.

Sandboxes laufen ohne Root, mit schreibgeschütztem Root-Dateisystem, ohne Fähigkeiten, mit seccomp RuntimeDefault und ohne ServiceAccount-Token. Dateien, Befehle, Git und Terminals verwenden exec; Vorschauen werden von der Pod-IP über den signierten Same-Origin-Proxy bereitgestellt, daher muss das Backend im Cluster laufen. Hostordner werden nicht unterstützt.

Zwei Hinweise: NetworkPolicy erfordert ein CNI, das sie durchsetzt (Calico, Cilium, neuere kind-Versionen und die meisten verwalteten Standards). Prüfe dies, bevor du Isolation annimmst; die Ende-zu-Ende-Suite meldet die Durchsetzung. Binde niemals den Containerlaufzeitsocket eines Knotens in den WebUI-Pod ein; genau das soll dieses Backend vermeiden.

Installation​

helm install libre-webui oci://ghcr.io/libre-webui/charts/libre-webui

Der Standardchart stellt Libre WebUI mit persistentem Speicher und gebündeltem Ollama bereit. Der Übergang 0.14.1 ist auf den verifizierten Multiarchitektur-Image-Digest festgelegt; folgende Charts nutzen standardmäßig das passende semantische appVersion-Image. Setze image.tag oder image.digest nur bewusst für ein anderes Image. Ein nicht leeres image.tag hat Vorrang.

Das Standardprofil solo akzeptiert replicaCount: 0 für absichtliche Pause oder replicaCount: 1 für Betrieb. Höhere Werte und HorizontalPodAutoscaler werden abgewiesen, da SQLite, lokale Dateien und prozesslokale Koordination hinter mehreren Pods unsicher sind. Bei null Replikaten werden Steuerressourcen erstellt, aber kein Verkehr bedient.

Konfiguriere für mehrere Replikate das vollständige Profil team. Es verwendet PostgreSQL/PGVector, S3-kompatiblen Blobspeicher, Redis und einen getrennten dauerhaften Worker; der Chart lehnt Teilmischungen ab. Beginne mit einer geschützten Wertedatei:

replicaCount: 3

env:
  LIBRE_PLATFORM_MODE: team
  DATABASE_BACKEND: postgres
  DATABASE_SSL_MODE: verify-full
  POSTGRES_MIGRATION_MODE: apply
  POSTGRES_POOL_MAX: 10
  POSTGRES_CONNECT_TIMEOUT_MS: 5000
  POSTGRES_IDLE_TIMEOUT_MS: 30000
  POSTGRES_STATEMENT_TIMEOUT_MS: 30000
  POSTGRES_MIGRATION_LOCK_TIMEOUT_MS: 60000
  OLLAMA_TIMEOUT: 300000
  OLLAMA_LONG_OPERATION_TIMEOUT: 900000
  OLLAMA_MAX_CONTEXT: 32768
  BLOB_STORE_BACKEND: s3
  VECTOR_STORE_BACKEND: pgvector
  COORDINATION_BACKEND: redis
  JOB_WORKER_MODE: external
  STORAGE_ENCRYPTION_ACTIVE_KEY_ID: active
  S3_BUCKET: libre-blobs
  S3_REGION: us-east-1
  S3_BLOB_PREFIX: libre/blobs

worker:
  replicaCount: 1

secrets:
  databaseUrl: postgresql://libre:replace-me@postgres.example/libre
  redisUrl: rediss://redis.example:6379/0
  jwtSecret: '<one-stable-high-entropy-secret-for-every-replica>'
  encryptionKey: '<legacy-64-character-lowercase-hex-key>'
  storageEncryptionKeys: '{"legacy":"<legacy-64-character-lowercase-hex-key>","active":"<active-64-character-lowercase-hex-key>"}'
  s3AccessKeyId: replace-me
  s3SecretAccessKey: replace-me

secrets.encryptionKey muss exakt dem Eintrag legacy entsprechen, und die Karte muss STORAGE_ENCRYPTION_ACTIVE_KEY_ID enthalten. secrets.jwtSecret muss ein stabiler hochentropischer Wert für alle App- und Worker-Pods sein; der Chart verweigert team ohne ihn, damit Sitzungen nicht von podlokalem Material abhängen. Behalte verifiziertes TLS für verwaltetes PostgreSQL und füge keine Treiber-TLS-Parameter zu databaseUrl hinzu. Poollimits gelten pro Prozess: Reserviere mindestens (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX Verbindungen plus Reserve. Installiere mit der geschützten Datei:

helm upgrade --install libre-webui \
  oci://ghcr.io/libre-webui/charts/libre-webui \
  --values /absolute/path/to/libre-team-values.yaml

Committe die Datei nicht und übergib Produktionsgeheimnisse nicht mit --set. Verwahre sie verschlüsselt. Skaliere Modellanbieter und Work-Pods unabhängig. Mit work.enabled=true erhält der externe Worker dasselbe Laufzeitimage, StorageClass und dieselben work.env-Grenzen wie die App. Er erhält auch denselben Ollama-Endpunkt, dieselben Zeitlimits und denselben maximalen Kontext, da Einbettungen, dauerhafte Chats und Work dort Anbieter aufrufen. Eine aktive Team-App (positives replicaCount oder Autoscaling) erfordert mindestens einen Worker; null wird abgewiesen. Setze replicaCount und worker.replicaCount für eine vollständige Pause auf null. App null mit positivem Worker ist ein bewusster Worker-only-Abfluss-/Wiederherstellungsmodus: kein Webverkehr, aber Verarbeitung der Warteschlange.

Team-Upgrades und Schemakompatibilität​

Libre unterstützt eine exakte Schemaversion, keine gemischten oder unterbrechungsfreien Datenbankupgrades. App und Worker verwenden Recreate, was alte und neue Pods innerhalb eines Deployments trennt; Kubernetes koordiniert beide Deployments jedoch nicht gemeinsam. Stoppe vor dem Upgrade neue Anfragen, lasse dauerhafte und Work-Aufträge fertig werden oder brich sie ab, skaliere beide alten Deployments auf null, erstelle eine verifizierte Sicherung und bestätige das Ende aller alten Pods. Aktualisiere erst dann mit POSTGRES_MIGRATION_MODE=apply; ein neuer Prozess hält den Advisory-Leader-Lock, während andere warten und dasselbe Migrationsbuch prüfen. Stelle für Rollback die vorherige Sicherung in saubere PostgreSQL-/S3-Ziele wieder her; richte niemals ein älteres Programm auf ein nicht exakt unterstütztes Schema. Plane eine Unterbrechung ein.

Lokaler Zugriff​

kubectl port-forward svc/libre-webui 8080:8080

Öffne http://localhost:8080.

Externes Ollama​

Verwende einen vorhandenen Endpunkt:

helm install libre-webui oci://ghcr.io/libre-webui/charts/libre-webui \
  --set ollama.bundled.enabled=false \
  --set ollama.external.enabled=true \
  --set ollama.external.url=http://my-ollama:11434

Secrets​

Setze ein stabiles JWT-Geheimnis und einen Schlüssel. Der Chart erstellt standardmäßig <release>-libre-webui-secrets aus nicht leeren secrets.*-Werten:

helm upgrade --install libre-webui \
  oci://ghcr.io/libre-webui/charts/libre-webui \
  --set-string secrets.jwtSecret="$(openssl rand -hex 64)" \
  --set-string secrets.encryptionKey="$(openssl rand -hex 32)"

Setze für ein betreiberverwaltetes Secret secrets.existingSecret. Der Chart rendert kein Secret und App wie Worker referenzieren das Objekt:

secrets:
  existingSecret: libre-webui-runtime

Erstelle es vor der Installation. Es muss jwt-secret und encryption-key enthalten; team benötigt zusätzlich database-url, redis-url und storage-encryption-keys. Optionale Schlüssel sind session-secret, s3-access-key-id, s3-secret-access-key und s3-session-token. GitHub- und Hugging Face-OAuth können *-client-id/*-client-secret lesen, wenn ein nicht leerer Wert secrets.githubClientId oder secrets.huggingfaceClientId die Integration aktiviert. Der Chart validiert oder kopiert Werte absichtlich nicht; ein fehlender Pflichtschlüssel verhindert den Podstart.

Bevorzuge für Automatisierung secrets.existingSecret mit externem Secret-Controller oder verschlüsselte stabile Werte. --set kann in Prozessprüfung erscheinen und wird in Helm-Metadaten bewahrt. Füge Anbieterzugangsdaten bewusst zum Chart hinzu oder konfiguriere sie pro Benutzer.

NetworkPolicies für App und Worker​

Setze networkPolicy.enabled=true für eingehende Richtlinien:

networkPolicy:
  enabled: true

Die App akzeptiert eingehend nur ihren HTTP-Port; der Worker gar nichts. Ausgehend wird nicht beschränkt: Prozesse müssen PostgreSQL, Redis, S3, Ollama, Werkzeuge und Anbieter erreichen.

Dies ist getrennt von work.networkPolicy.enabled für die Standardverweigerung im Work-Namespace, die mit Work standardmäßig aktiv ist. Beide brauchen ein tatsächlich durchsetzendes CNI; das Rendern beweist keine Isolation.

Persistenz​

Bewahre Libre WebUI-Daten-PVC und Ollama-Modell-PVC persistent. Sichere Datenvolume und Schlüssel gemeinsam.

Work-Arbeitsbereiche liegen in eigenen PVCs im Sandbox-Namespace. Eine vollständige Wiederherstellung benötigt Datenbank (Besitz, Namen, Ausführungen) und PVCs; sichere sie gemeinsam.

Ingress​

Konfiguriere für öffentlichen Zugriff Ingress mit HTTPS und exaktem Ursprung:

helm upgrade libre-webui \
  oci://ghcr.io/libre-webui/charts/libre-webui \
  --reuse-values \
  --set env.TRUST_PROXY=1 \
  --set-string env.CORS_ORIGIN=https://your-domain.example

TRUST_PROXY ist eine exakte Hopzahl, kein Boolean. Der sichere Standard 0 ignoriert weitergeleitete Adressen. Nutze 1 nur bei einem direkten Ingressproxy; zähle jeden vertrauenswürdigen Hop und halte den Service außerhalb unerreichbar. Ein zu kleiner Wert gruppiert Clients und erschöpft gemeinsame Limits, ein zu großer vertraut eventuell Clientangaben. Der Chart akzeptiert 0 bis 16, nie true, und sendet den Wert nur an HTTP-Pods.

Der Chart stellt derzeit BASE_URL und OAuth-Callback-Werte nicht bereit. OAuth-Bereitstellungen müssen ihn erweitern oder das Deployment patchen; Callbacks müssen zur öffentlichen Domain passen.

Ressourcenplanung​

Plane einen lokalen Ollama-Pod auf Knoten mit ausreichend Speicher und GPU für die Modelle. Wenn bereits ein Inferenzdienst vorhanden ist, ist externes Ollama meist einfacher.

Verwandte Dokumentation​