Lewati ke konten utama

Kubernetes

Libre WebUI menyediakan chart Helm di helm/libre-webui.

Work di Kubernetes​

Work berjalan secara native di Kubernetes—tidak melibatkan daemon, CLI, atau soket Docker. Aktifkan saat instalasi:

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

Tindakan ini mengalihkan backend ke WORK_RUNTIME_BACKEND=kubernetes dan membuat:

  • namespace sandbox khusus (work.namespace, bawaan libre-webui-work) yang memuat satu Pod per sandbox berjalan dan satu PersistentVolumeClaim per ruang kerja tugas (work.workspaceSize, bawaan 5Gi—kuota disk nyata per tugas; kebijakan Work bernama dapat menetapkan ukuran berbeda bagi tugas yang dibuat di bawahnya);
  • Role dan RoleBinding bercakupan namespace yang memberi ServiceAccount backend tepat izin pods (get/list/create/delete), pods/exec (get/create), dan persistentvolumeclaims (get/list/create/delete) dalam namespace tersebut—tanpa secrets dan tanpa cakupan klaster. Pemberian ini sepenuhnya menggantikan soket Docker: server API, bukan aplikasi, yang memastikan spesifikasi sandbox tidak dapat memasang jalur host;
  • NetworkPolicy yang menolak semua lalu lintas sandbox secara bawaan, hanya mengizinkan ingress dari backend pada port pratinjau, dan memberi sandbox berjejaring akses keluar ke internet selain work.networkPolicy.blockedEgressCidrs (secara bawaan mencakup rentang privat, rentang CGNAT yang digunakan sebagian klaster terkelola untuk CIDR pod dan layanan, serta rentang link-local metadata cloud—pastikan CIDR pod dan layanan klaster Anda tercakup). DNS sandbox hanya diizinkan ke kube-system; klaster yang menjalankan DNS lokal-node memerlukan pengecualian DNS tersendiri.

Sandbox berjalan sebagai non-root dengan sistem berkas root hanya baca, semua kapabilitas dihapus, seccomp RuntimeDefault, dan tanpa token ServiceAccount. Berkas, perintah, git, dan terminal interaktif menggunakan subsumber daya exec melalui server API; pratinjau disajikan dari IP Pod sandbox melalui proksi same-origin bertanda tangan, yang mengharuskan backend berjalan di dalam klaster (topologi chart normal). Ruang kerja folder host tidak didukung pada backend ini.

Dua catatan untuk operator. Penegakan NetworkPolicy memerlukan CNI yang mengimplementasikannya (Calico, Cilium, rilis kind terbaru, dan sebagian besar bawaan klaster terkelola melakukannya)—verifikasikan pada klaster Anda sebelum menganggap isolasi sandbox aktif; rangkaian CI ujung-ke-ujung melaporkan apakah klaster tempatnya berjalan menegakkan kebijakan. Jangan pernah memasang soket runtime kontainer node ke pod WebUI; backend Kubernetes ada justru agar hal itu tidak diperlukan.

Instalasi​

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

Chart bawaan menerapkan Libre WebUI dengan penyimpanan persisten dan layanan Ollama yang disertakan. Transisi 0.14.1 dikunci pada digest image multiarsitektur yang telah diverifikasi; chart berikutnya secara bawaan menggunakan image appVersion semantik yang cocok. Tetapkan image.tag atau image.digest secara eksplisit hanya jika Anda sengaja menginginkan image lain. image.tag yang tidak kosong mengalahkan digest transisi.

Profil solo bawaan menerima replicaCount: 0 untuk penangguhan disengaja atau replicaCount: 1 untuk operasi normal. Profil menolak nilai lebih besar dan HorizontalPodAutoscaler karena SQLite, berkas lokal, serta koordinasi lokal-proses tidak aman di belakang beberapa pod. Rilis tanpa replika menyediakan sumber daya bidang kontrolnya tetapi tidak melayani lalu lintas Libre WebUI.

Untuk beberapa replika, konfigurasikan profil team lengkap. Profil ini menggunakan PostgreSQL/PGVector, penyimpanan blob kompatibel S3, Redis, dan worker tahan lama terpisah; chart menolak campuran parsial backend bersama dan lokal. Mulailah dari berkas values terlindungi seperti berikut:

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 harus persis cocok dengan entri legacy, dan peta kunci juga harus memuat STORAGE_ENCRYPTION_ACTIVE_KEY_ID. secrets.jwtSecret harus berupa satu nilai stabil berentropi tinggi yang digunakan bersama oleh setiap pod aplikasi dan worker; chart menolak mode team tanpanya agar sesi tidak bergantung pada materi yang dibuat secara lokal di pod. Pertahankan TLS terverifikasi untuk PostgreSQL terkelola; jangan tambahkan parameter TLS driver ke databaseUrl. Batas pool berlaku bagi setiap pod aplikasi dan worker, jadi cadangkan sedikitnya (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX koneksi database ditambah ruang operasional. Instal dengan berkas values terlindungi:

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

Jangan commit berkas tersebut atau meneruskan rahasia produksi melalui --set. Simpan dengan alur values terenkripsi yang dilindungi. Skalakan penyedia model dan Pod sandbox Work secara terpisah; ketika work.enabled=true, worker team eksternal menerima image runtime, StorageClass, dan batas work.env yang sama dengan pod aplikasi. Worker juga menerima endpoint Ollama hasil resolusi, batas waktu permintaan, dan konteks maksimum yang diadopsi otomatis seperti aplikasi, karena embedding dokumen, chat tahan lama, serta proses Work mengeksekusi panggilan penyedia di sana. Aplikasi team aktif (replicaCount positif atau penskalaan otomatis aktif) memerlukan sedikitnya satu worker eksternal, dan chart menolak konfigurasi tanpa worker sebelum instalasi. Tetapkan replicaCount dan worker.replicaCount ke nol untuk penangguhan penuh. Menetapkan hanya jumlah aplikasi ke nol adalah mode pengurasan atau pemulihan khusus-worker yang disengaja: tidak ada lalu lintas web yang dilayani, tetapi worker tetap memproses pekerjaan tahan lama dalam antrean.

Peningkatan Team dan Kompatibilitas Skema​

Libre mendukung kebijakan versi skema persis, bukan peningkatan database versi campuran atau tanpa waktu henti. Deployment aplikasi dan worker eksternal masing-masing menggunakan Recreate, yang mencegah pod lama dan baru tumpang tindih dalam satu Deployment tersebut. Kubernetes tidak mengoordinasikan kedua Deployment sebagai satu batas peningkatan. Sebelum meningkatkan, hentikan ingress baru, biarkan selesai atau batalkan pekerjaan tahan lama dan Work yang aktif, skalakan kedua Deployment lama ke nol, ambil cadangan team terverifikasi, dan pastikan semua pod aplikasi serta worker lama telah berhenti. Baru setelah itu tingkatkan rilis dengan POSTGRES_MIGRATION_MODE=apply; satu proses baru memegang kunci pemimpin advisory PostgreSQL sementara proses baru lainnya menunggu dan memvalidasi buku besar migrasi yang sama. Untuk rollback, pulihkan cadangan terverifikasi sebelumnya ke tujuan PostgreSQL/S3 yang bersih; jangan pernah arahkan biner lama ke skema yang tidak didukungnya secara persis. Prosedur ini sengaja menyebabkan gangguan layanan.

Akses Lokal​

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

Buka http://localhost:8080.

Ollama Eksternal​

Gunakan endpoint Ollama yang sudah ada:

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

Rahasia​

Tetapkan rahasia JWT dan kunci enkripsi yang stabil untuk produksi. Secara bawaan, chart membuat <release>-libre-webui-secrets dari nilai secrets.* yang tidak kosong:

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

Untuk Secret yang dikelola operator, tetapkan secrets.existingSecret. Chart kemudian tidak merender Secret dan pod aplikasi serta worker merujuk objek bernama tersebut:

secrets:
  existingSecret: libre-webui-runtime

Buat Secret tersebut sebelum menginstal rilis. Secret harus memuat jwt-secret dan encryption-key. Mode team juga memerlukan database-url, redis-url, dan storage-encryption-keys. Kunci opsional yang dipahami chart adalah session-secret, s3-access-key-id, s3-secret-access-key, dan s3-session-token. GitHub dan Hugging Face OAuth juga dapat membaca pasangan *-client-id dan *-client-secret dari Secret bernama ketika nilai secrets.githubClientId atau secrets.huggingfaceClientId terkait yang tidak kosong mengaktifkan integrasi. Chart sengaja tidak memvalidasi atau menyalin nilai Secret; kunci wajib yang hilang membuat Pod tidak dapat dimulai.

Untuk otomatisasi produksi, utamakan secrets.existingSecret bersama controller external-secrets atau berikan nilai stabil melalui alur values Helm terenkripsi. Nilai --set pada baris perintah dapat terlihat melalui inspeksi proses dan dipertahankan dalam metadata rilis Helm. Tambahkan kredensial penyedia melalui ekstensi chart yang disengaja atau konfigurasikan kredensial per pengguna dalam WebUI.

NetworkPolicy Aplikasi dan Worker​

Tetapkan networkPolicy.enabled=true untuk merender kebijakan ingress bagi aplikasi dan, dalam mode team, worker tahan lama eksternal:

networkPolicy:
  enabled: true

Aplikasi hanya menerima ingress pada port kontainer HTTP. Worker tidak menerima ingress. Kebijakan ini tidak membatasi egress: proses aplikasi dan worker tetap harus menjangkau endpoint PostgreSQL, Redis, S3, Ollama, alat, dan penyedia model yang dikonfigurasi, dan operator menentukan lokasi layanan tersebut.

Pengaturan ini terpisah dari work.networkPolicy.enabled, yang mengontrol kebijakan tolak-bawaan dalam namespace sandbox Work dan diaktifkan secara bawaan ketika Work aktif. Kedua pengaturan memerlukan CNI yang benar-benar menegakkan Kubernetes NetworkPolicy; sekadar merender objek tidak membuktikan isolasi jaringan.

Persistensi​

Simpan PVC data Libre WebUI dan PVC model Ollama pada penyimpanan persisten. Cadangkan volume data Libre WebUI dan kunci enkripsi secara bersamaan.

Ruang kerja tugas Work berada dalam PVC tersendiri di namespace sandbox, bukan dalam PVC data Libre WebUI. Pemulihan Work lengkap memerlukan database (kepemilikan tugas, nama sumber daya, proses) dan PVC tersebut; cadangkan keduanya bersama berdasarkan kebijakan yang sama.

Ingress​

Untuk akses publik, konfigurasikan ingress dengan HTTPS dan tetapkan origin peramban yang persis melalui chart:

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 adalah jumlah hop yang persis, bukan boolean. Nilai bawaan chart yang aman adalah 0, yang mengabaikan alamat klien terusan. Gunakan 1 hanya jika satu proksi ingress terhubung langsung ke Libre; hitung setiap hop load balancer atau proksi tepercaya dalam rantai tetap yang lebih panjang dan pastikan Service tidak dapat dijangkau di luar rantai itu. Jumlah yang terlalu kecil mengelompokkan klien di bawah alamat proksi dan dapat menghabiskan batas login bersama; jumlah yang terlalu besar dapat memercayai alamat yang diberikan klien. Chart hanya menerima 0 hingga 16, tidak pernah true tanpa batas, dan hanya mengirim nilai tersebut ke pod aplikasi HTTP.

Chart saat ini tidak mengekspos nilai BASE_URL atau URL callback OAuth. Deployment yang menggunakan OAuth harus memperluas chart atau menambal Deployment untuk menetapkan variabel tersebut, dan URL callback harus cocok dengan domain publik.

Perencanaan Sumber Daya​

Untuk Ollama lokal di dalam klaster, jadwalkan pod Ollama pada node dengan memori dan kapasitas GPU yang cukup untuk model yang ingin Anda jalankan. Jika klaster sudah memiliki Ollama atau layanan inferensi khusus, Ollama eksternal biasanya lebih sederhana.

Dokumentasi Terkait​