Přeskočit na hlavní obsah

Kubernetes

Libre WebUI obsahuje Helm chart v helm/libre-webui.

Work na Kubernetes​

Work běží nativně na Kubernetes bez daemonu, CLI nebo socketu Docker. Zapněte jej při instalaci:

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

Tím se backend přepne na WORK_RUNTIME_BACKEND=kubernetes a vytvoří:

  • vyhrazený namespace sandboxu (work.namespace, výchozí libre-webui-work) s jedním Podem na běžící sandbox a jedním PersistentVolumeClaim na pracovní prostor (work.workspaceSize, výchozí 5Gi, skutečná disková kvóta na úkol; pojmenovaná zásada Work může nastavit jinou velikost);
  • Role a RoleBinding v rozsahu namespace, které dávají ServiceAccount backendu přesně pods (get/list/create/delete), pods/exec (get/create) a persistentvolumeclaims (get/list/create/delete)—žádné secrets ani rozsah clusteru. Toto oprávnění plně nahrazuje socket Docker: API server, nikoli aplikace, vynucuje, že specifikace sandboxu nemůže připojit cesty hostitele;
  • NetworkPolicy, které ve výchozím stavu odmítají veškerý provoz sandboxu, povolují ingress jen z backendu na port náhledu a dávají síťovým sandboxům egress na internet kromě work.networkPolicy.blockedEgressCidrs (soukromé rozsahy, CGNAT používaný některými spravovanými clustery a metadata cloudu—ověřte pokrytí CIDR clusteru). DNS sandboxu je povoleno jen do kube-system; cluster s místním DNS uzlu potřebuje vlastní výjimku.

Sandboxy běží jako non-root s kořenovým systémem jen pro čtení, bez capabilities, se seccomp RuntimeDefault a bez tokenu ServiceAccount. Soubory, příkazy, git a terminály používají podprostředek exec přes API server. Náhled se podává z IP Podu přes podepsanou same-origin proxy a vyžaduje backend v clusteru. Pracovní prostory se složkou hostitele nejsou podporované.

Dvě poznámky pro operátory: NetworkPolicy vyžaduje CNI, které jej implementuje (Calico, Cilium, novější kind a většina spravovaných clusterů). Před považováním izolace za aktivní ji ověřte; end-to-end sada CI hlásí, zda ji cluster vynucuje. Socket runtime kontejnerů uzlu nikdy nepřipojujte do Podu WebUI; backend Kubernetes existuje právě proto, aby to nebylo nutné.

Instalace​

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

Výchozí chart nasazuje Libre WebUI s trvalým úložištěm a přibalenou Ollama. Přechod 0.14.1 je připnutý k ověřenému multiarchitekturnímu digestu image; další charty používají odpovídající sémantickou appVersion image. image.tag nebo image.digest nastavte jen při záměru použít jinou image. Neprázdná image.tag má přednost.

Výchozí profil solo přijímá replicaCount: 0 pro záměrné pozastavení nebo replicaCount: 1 pro běžný provoz. Vyšší hodnoty a HorizontalPodAutoscaler odmítá, protože SQLite, místní soubory a procesní koordinace nejsou bezpečné za více Pody. Vydání s nulou připraví řídicí prostředky, ale neposkytuje provoz Libre WebUI.

Pro více replik nastavte úplný profil team. Používá PostgreSQL/PGVector, blobové úložiště kompatibilní s S3, Redis a samostatný trvalý worker; chart odmítá částečnou směs sdílených a místních backendů. Začněte chráněným souborem values:

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 musí přesně odpovídat položce legacy a mapa klíčů musí obsahovat STORAGE_ENCRYPTION_ACTIVE_KEY_ID. secrets.jwtSecret musí být jedna stabilní hodnota s vysokou entropií sdílená všemi Pody aplikace a workeru; bez ní chart odmítá režim team, aby relace nezávisely na místních datech Podu. U spravovaného PostgreSQL zachovejte ověřené TLS a nepřidávejte parametry ovladače do databaseUrl. Limity poolu platí pro každý proces, proto rezervujte nejméně (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX spojení a rezervu. Instalujte s chráněným souborem values:

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

Soubor necommitujte a produkční tajné údaje neposílejte přes --set. Uložte jej chráněným tokem šifrovaných values. Poskytovatele modelů a sandbox Pody Work škálujte nezávisle. Při work.enabled=true dostává externí worker stejnou runtime image, StorageClass a limity work.env jako aplikace, i stejný vyřešený endpoint Ollama, timeouty a maximální kontext, protože volání poskytovatelů probíhá tam. Aktivní team aplikace vyžaduje alespoň jeden externí worker a chart odmítá nulu. Pro úplné pozastavení nastavte replicaCount i worker.replicaCount na nulu. Pouze aplikace na nule je záměrný režim vyprázdnění/obnovy workeru bez webového provozu, ale se zpracováním fronty.

Team upgrades and schema compatibility​

Libre vyžaduje přesnou verzi schématu, nikoli smíšené verze nebo upgrade databáze bez výpadku. Deployment aplikace i workeru používá Recreate, který brání překrytí v každém Deploymentu, ale Kubernetes je nekoordinuje jako jednu hranici. Před upgradem zastavte nový ingress, dokončete nebo zrušte aktivní trvalé a Work joby, škálujte oba staré Deploymenty na nulu, pořiďte ověřenou týmovou zálohu a potvrďte ukončení všech starých Podů. Poté upgradujte s POSTGRES_MIGRATION_MODE=apply; jeden proces drží poradní zámek PostgreSQL a ostatní čekají a ověřují stejnou migrační knihu. Pro rollback obnovte ověřenou zálohu do čistých cílů PostgreSQL/S3; starší binární soubor nikdy nesměřujte na nepodporované schéma. Očekávejte záměrný výpadek.

Místní přístup​

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

Otevřete http://localhost:8080.

Externí Ollama​

Použijte existující endpoint Ollama:

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

Tajné údaje​

Pro produkci nastavte stabilní tajný údaj JWT a šifrovací klíč. Chart ve výchozím stavu vytváří <release>-libre-webui-secrets z neprázdných hodnot secrets.*:

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)"

Pro Secret spravovaný operátorem nastavte secrets.existingSecret. Chart pak žádný Secret nevykreslí a Pody aplikace i workeru odkazují na pojmenovaný objekt:

secrets:
  existingSecret: libre-webui-runtime

Secret vytvořte před instalací. Musí obsahovat jwt-secret a encryption-key; režim team také database-url, redis-url a storage-encryption-keys. Volitelné klíče jsou session-secret, s3-access-key-id, s3-secret-access-key a s3-session-token. GitHub a Hugging Face OAuth mohou číst páry *-client-id/*-client-secret, pokud integraci aktivuje secrets.githubClientId nebo secrets.huggingfaceClientId. Chart hodnoty záměrně neověřuje ani nekopíruje; chybějící povinný klíč brání spuštění Podu.

Pro produkční automatizaci upřednostněte secrets.existingSecret s controllerem external-secrets nebo stabilní hodnoty přes šifrovaný tok Helm values. Hodnoty --set mohou být odhalené kontrolou procesu a zůstávají v metadatech Helm. Přihlašovací údaje poskytovatelů přidejte záměrným rozšířením chartu nebo na uživatele ve WebUI.

NetworkPolicy aplikace a workeru​

Nastavte networkPolicy.enabled=true, aby se vykreslily ingress zásady pro aplikaci a v režimu team externí trvalý worker:

networkPolicy:
  enabled: true

Aplikace přijímá ingress jen na HTTP portu kontejneru. Worker nepřijímá žádný ingress. Zásady neomezují egress: procesy stále musí dosáhnout na nakonfigurované endpointy PostgreSQL, Redis, S3, Ollama, nástroje a modely a operátor rozhoduje o jejich umístění.

Nastavení je oddělené od work.networkPolicy.enabled, které řídí výchozí odmítavé zásady v namespace sandboxu Work a zapíná se s Work. Obě vyžadují CNI skutečně vynucující Kubernetes NetworkPolicy; samotné vykreslení objektů nedokazuje síťovou izolaci.

Perzistence​

PVC dat Libre WebUI a modelů Ollama uchovávejte na trvalém úložišti. Datový svazek a šifrovací klíč zálohujte společně.

Pracovní prostory Work jsou ve vlastních PVC v namespace sandboxu, nikoli v datovém PVC Libre WebUI. Úplná obnova Work vyžaduje databázi (vlastnictví, názvy prostředků, běhy) i PVC; zálohujte je společně podle stejné zásady.

Ingress​

Pro veřejný přístup nakonfigurujte ingress s HTTPS a přes chart nastavte přesný origin prohlížeče:

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 je přesný počet hopů, nikoli boolean. Bezpečná výchozí hodnota je 0, která ignoruje předané adresy. 1 použijte jen při jedné ingress proxy připojené přímo; v delším pevném řetězci počítejte všechny důvěryhodné load balancery a proxy a udržujte službu mimo řetězec nedostupnou. Příliš nízký počet seskupí klienty pod proxy a může vyčerpat sdílené limity; příliš vysoký důvěřuje adrese od klienta. Chart přijímá jen 0–16, nikdy neomezené true, a posílá hodnotu pouze HTTP Podům aplikace.

Aktuální chart nevystavuje BASE_URL ani URL callback OAuth. Nasazení s OAuth musí chart rozšířit nebo patchnout Deployment a URL musí odpovídat veřejné doméně.

Plánování prostředků​

Místní Pod Ollama plánujte na uzlech s dostatkem paměti a GPU pro modely. Pokud cluster již má vyhrazenou Ollama nebo inferenční službu, externí Ollama bývá jednodušší.

Související dokumentace​