Passa al contenuto principale

Kubernetes

Libre WebUI fornisce un chart Helm in helm/libre-webui.

Work su Kubernetes​

Work funziona nativamente su Kubernetes, senza daemon, CLI o socket Docker. Attivalo:

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

Seleziona WORK_RUNTIME_BACKEND=kubernetes e crea:

  • namespace dedicato (work.namespace, default libre-webui-work) con un Pod per sandbox attivo e un PersistentVolumeClaim per attività (work.workspaceSize, default 5Gi, quota reale per attività; una policy può scegliere altro);
  • Role/RoleBinding limitati al namespace con soli pods (get/list/create/delete), pods/exec (get/create), persistentvolumeclaims (get/list/create/delete), senza secrets né cluster scope. Sostituisce il socket: l'API server impedisce mount di percorsi host;
  • NetworkPolicies deny-all, ingresso solo dal backend sulla porta preview e uscita Internet per sandbox abilitati tranne work.networkPolicy.blockedEgressCidrs (reti private, CGNAT e metadata link-local di default; verifica CIDR Pod/Service). DNS solo a kube-system; node-local DNS richiede eccezione.

I sandbox sono non-root, rootfs read-only, capabilities eliminate, seccomp RuntimeDefault, senza token ServiceAccount. File, comandi, git e terminali usano exec. La preview passa dall'IP del Pod tramite proxy same-origin firmato, quindi il backend deve essere nel cluster. Le cartelle host non sono supportate.

NetworkPolicy richiede un CNI che la applichi (Calico, Cilium, kind recente e molti cluster gestiti). Verifica prima di considerare attivo l'isolamento. Non montare mai il socket runtime del nodo: questo backend serve a evitarlo.

Installazione​

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

Il chart predefinito distribuisce storage persistente e Ollama incluso. La transizione 0.14.1 è fissata al digest multiarch verificato; i chart successivi usano l'immagine dell'appVersion. Imposta image.tag o image.digest solo intenzionalmente; un tag non vuoto prevale.

solo accetta replicaCount: 0 per sospensione o replicaCount: 1 per funzionamento. Rifiuta valori maggiori e HPA perché SQLite, file locali e coordinamento in-process non sono sicuri tra Pod. Zero crea le risorse ma non serve traffico.

Per più repliche usa team completo: PostgreSQL/PGVector, S3, Redis e worker duraturo separato. Il chart rifiuta combinazioni parziali. Esempio protetto:

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 deve coincidere con legacy e la mappa contenere STORAGE_ENCRYPTION_ACTIVE_KEY_ID. secrets.jwtSecret deve essere stabile e condiviso da tutti i Pod; senza, team viene rifiutato. Mantieni TLS verificato per PostgreSQL e non aggiungere parametri driver a databaseUrl. I pool sono per processo: riserva (replicaCount + worker.replicaCount) * POSTGRES_POOL_MAX connessioni più margine.

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

Non committare il file né passare segreti con --set. Scala provider e Pod Work separatamente. Con work.enabled=true, il worker riceve stessa immagine, StorageClass, limiti work.env, endpoint Ollama, timeout e contesto. Un valore positivo di replicaCount richiede un worker; imposta replicaCount e worker.replicaCount a zero per una sospensione totale. Solo app a zero è modalità worker-only di drain/recupero.

Aggiornamenti team e compatibilità schema​

Libre richiede schema esatto, non aggiornamenti misti o zero-downtime. App e worker usano Recreate, ma Kubernetes non li coordina insieme. Prima, ferma ingresso, completa/annulla lavori, scala entrambi a zero, crea backup verificato e verifica terminazione. Poi aggiorna con POSTGRES_MIGRATION_MODE=apply; un processo tiene l'advisory lock e gli altri validano. Per rollback ripristina il backup precedente in PostgreSQL/S3 puliti; non avviare binari vecchi su schema non supportato. È prevista interruzione.

Accesso locale​

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

Apri http://localhost:8080.

Ollama esterno​

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

Segreti​

Per impostazione predefinita il chart crea <release>-libre-webui-secrets dai valori non vuoti 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)"

Per Secret gestito imposta secrets.existingSecret; il chart non ne crea e i Pod riferiscono quello:

secrets:
  existingSecret: libre-webui-runtime

Crealo prima. Deve contenere jwt-secret, encryption-key; team anche database-url, redis-url, storage-encryption-keys. Opzionali: session-secret, s3-access-key-id, s3-secret-access-key, s3-session-token. GitHub e Hugging Face leggono *-client-id/*-client-secret quando secrets.githubClientId o secrets.huggingfaceClientId abilita l'integrazione. Il chart non convalida/copia; chiavi mancanti impediscono l'avvio.

Per automazione preferisci external-secrets o values cifrati. --set può apparire nei processi e metadati. Aggiungi credenziali con estensione deliberata o per utente.

NetworkPolicies applicazione e worker​

Imposta networkPolicy.enabled=true per generare le policy di ingresso:

networkPolicy:
  enabled: true

L'app accetta ingresso solo sulla porta HTTP; il worker nessuno. L'uscita non è limitata: devono raggiungere PostgreSQL, Redis, S3, Ollama, strumenti e provider.

È separato da work.networkPolicy.enabled, che controlla i sandbox ed è attivo con Work. Entrambi richiedono CNI effettivo.

Persistenza​

Mantieni PVC dati e modelli persistenti e fai backup con chiave. Gli spazi Work sono PVC separati nel namespace; il recupero richiede database e PVC insieme.

Ingress​

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 è numero esatto di hop. Default 0 ignora indirizzi inoltrati. Usa 1 per un proxy diretto e conta ogni hop. Troppo basso raggruppa client; troppo alto si fida del client. Il chart accetta 0–16, mai true, e lo invia solo ai Pod HTTP.

Il chart non espone BASE_URL né callback OAuth; estendilo o modifica Deployment, con URL uguali al dominio pubblico.

Pianificazione risorse​

Per Ollama locale, programma il Pod su nodi con memoria/GPU sufficienti. Un servizio dedicato esistente è spesso più semplice come Ollama esterno.

Documenti correlati​