Перейти до основного вмісту

Kubernetes

Libre WebUI постачається з чартом Helm у helm/libre-webui.

Work у Kubernetes​

Work працює безпосередньо в Kubernetes — без демона, CLI чи socket Docker. Увімкніть під час встановлення:

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

Це задає WORK_RUNTIME_BACKEND=kubernetes і створює:

  • окремий простір імен пісочниць (work.namespace, типово libre-webui-work) з одним Pod на активну пісочницю й одним PersistentVolumeClaim на робочу область (work.workspaceSize, типово 5Gi — справжня квота на завдання; іменована політика може задати інший розмір);
  • Role і RoleBinding у цьому просторі, що надають ServiceAccount сервера рівно pods (get/list/create/delete), pods/exec (get/create) і persistentvolumeclaims (get/list/create/delete) — без секретів і прав кластера. Це повністю замінює socket Docker: API-сервер не дозволяє специфікації монтувати шляхи хоста;
  • NetworkPolicies, що типово блокують увесь трафік пісочниць, дозволяють вхід лише від сервера на порт перегляду й надають мережевим пісочницям вихід в інтернет за винятком work.networkPolicy.blockedEgressCidrs (типово приватні діапазони, CGNAT деяких кластерів і link-local метаданих — перевірте CIDR Pod і служб). DNS дозволено лише до kube-system; node-local DNS потребує окремого винятку.

Пісочниці працюють без root, із коренем лише для читання, без capabilities, із seccomp RuntimeDefault і без токена ServiceAccount. Файли, команди, Git і термінали використовують підресурс exec через API-сервер; перегляд передається з IP Pod через підписаний проксі того самого походження, тому сервер має працювати в кластері. Папки хоста не підтримуються.

Дві примітки оператора. NetworkPolicy потребує CNI, що її реалізує (Calico, Cilium, нові kind і більшість керованих кластерів); перевірте це до покладання на ізоляцію. Ніколи не монтуйте socket контейнерного середовища вузла в Pod WebUI — Kubernetes-запуск існує саме для уникнення цього.

Установлення​

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

Типовий чарт розгортає Libre WebUI з постійним сховищем і вбудованим Ollama. Перехід 0.14.1 зафіксовано на перевіреному мультиархітектурному digest; наступні чарти використовують image відповідного appVersion. Явно задавайте image.tag або image.digest лише навмисно; непорожній image.tag має пріоритет над перехідним digest.

Типовий профіль solo приймає replicaCount: 0 для свідомого призупинення або replicaCount: 1 для роботи. Більші значення й HorizontalPodAutoscaler відхиляються, бо SQLite, локальні файли й локальна координація небезпечні за кількома Pod. Нуль реплік створює ресурси керування, але не обслуговує трафік.

Для кількох реплік налаштуйте повний профіль team із PostgreSQL/PGVector, S3-сумісним blob-сховищем, Redis і окремим постійним worker; часткове змішування спільних і локальних серверів відхиляється. Почніть із захищеного файлу:

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 має точно збігатися з legacy, а карта ключів містити STORAGE_ENCRYPTION_ACTIVE_KEY_ID. secrets.jwtSecret має бути одним стабільним високоентропійним значенням для всіх Pod застосунку й worker; без нього team відхиляється, щоб сеанси не залежали від локального матеріалу Pod. Зберігайте перевірений TLS PostgreSQL; не додавайте параметри TLS драйвера до databaseUrl. Ліміт пулу діє на кожен Pod, тому резервуйте щонайменше (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX з додатковим запасом. Установіть:

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

Не додавайте файл до репозиторію й не передавайте промислові секрети через --set; використовуйте захищений процес зашифрованих значень. Масштабуйте провайдерів моделей і Pod Work окремо. При work.enabled=true зовнішній worker отримує ту саму image середовища, StorageClass, work.env, кінцеву точку Ollama, тайм-аути й максимальний автоматично прийнятий контекст, бо в ньому виконуються векторизація документів, постійні чати й Work.

Активний team — додатний replicaCount або автоскейлінг — потребує хоча б одного зовнішнього worker; нуль worker відхиляється. Для повного призупинення задайте нуль і replicaCount, і worker.replicaCount. Нуль лише для застосунку є навмисним режимом дренування: вебтрафіку немає, worker продовжує чергу.

Оновлення team і сумісність схеми​

Libre вимагає точну версію схеми й не підтримує змішані версії або оновлення бази без простою. Deployment застосунку й worker використовують Recreate, але Kubernetes не координує їх разом. Перед оновленням зупиніть новий вхід, завершіть або скасуйте завдання, масштабуйте обидва старі Deployment до нуля, зробіть перевірену копію й дочекайтеся завершення всіх старих Pod. Лише тоді оновлюйте з POSTGRES_MIGRATION_MODE=apply; один процес утримує advisory lock PostgreSQL, інші чекають і перевіряють той самий реєстр міграцій. Для відкату відновіть попередню копію в чисті PostgreSQL/S3; ніколи не спрямовуйте старий двійковий файл на непідтримувану схему. Очікуйте запланований простій.

Локальний доступ​

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

Відкрийте http://localhost:8080.

Зовнішній 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

Секрети​

Для промислового середовища задайте стабільні JWT і ключ шифрування. Типово чарт створює <release>-libre-webui-secrets із непорожніх 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)"

Для Secret оператора задайте secrets.existingSecret; чарт не створює Secret, а Pod посилаються на названий об’єкт:

secrets:
  existingSecret: libre-webui-runtime

Створіть його до встановлення. Потрібні jwt-secret і encryption-key; team також database-url, redis-url, storage-encryption-keys. Необов’язкові: session-secret, s3-access-key-id, s3-secret-access-key, s3-session-token. OAuth GitHub і Hugging Face можуть читати пари *-client-id/*-client-secret, якщо відповідне непорожнє secrets.githubClientId або secrets.huggingfaceClientId вмикає інтеграцію. Чарт навмисно не перевіряє й не копіює значення; відсутній ключ не дасть Pod запуститися.

Для автоматизації віддавайте перевагу secrets.existingSecret з external-secrets або зашифрованим значенням Helm. --set може бути видимим у процесах і зберігається в метаданих випуску. Облікові дані провайдерів додавайте через свідоме розширення чарта або per користувача у WebUI.

NetworkPolicies застосунку й worker​

Задайте networkPolicy.enabled=true, щоб створити політики входу для застосунку й зовнішнього worker у team:

networkPolicy:
  enabled: true

Застосунок приймає вхід лише на HTTP-порт контейнера. Worker не приймає входу. Політики не обмежують вихід: процеси мають досягати PostgreSQL, Redis, S3, Ollama, інструментів і провайдерів, а оператор визначає їх розташування.

Це окремо від work.networkPolicy.enabled, що керує типовою забороною в просторі Work і типово ввімкнено разом із Work. Обидва потребують CNI, що справді виконує NetworkPolicy; саме створення об’єктів не доводить ізоляцію.

Постійне зберігання​

Тримайте PVC даних Libre WebUI й моделей Ollama на постійному сховищі. Копіюйте том даних разом із ключем шифрування.

Робочі області Work живуть у власних PVC простору пісочниць, не в PVC Libre WebUI. Повне відновлення потребує бази з власністю, іменами й запусками та цих PVC; копіюйте разом.

Ingress​

Для публічного доступу налаштуйте HTTPS і точне походження браузера:

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 — точна кількість переходів, не boolean. Безпечне типове 0 ігнорує передані адреси. Використовуйте 1 лише коли один ingress-проксі напряму підключається до Libre; рахуйте кожен довірений балансувальник або проксі й не відкривайте Service поза ланцюгом. Замале значення об’єднує клієнтів під адресою проксі й може вичерпати спільні ліміти входу; завелике довіряє адресі клієнта. Чарт приймає лише 0–16, ніколи необмежене true, і передає значення лише HTTP Pod застосунку.

Поточний чарт не виставляє BASE_URL або URL зворотних викликів OAuth. Такі розгортання мають розширити чарт або змінити Deployment, а URL точно відповідати публічному домену.

Планування ресурсів​

Для локального Ollama в кластері розмістіть Pod на вузлах із достатньою пам’яттю й GPU. Якщо кластер уже має окремий Ollama або службу інференсу, зовнішній Ollama зазвичай простіший.

Пов’язана документація​