Nasadenie Vektorovej Databázy ChromaDB v K3s s NFS Úložiskom

title: "Nasadenie Vektorovej Databázy ChromaDB v K3s s NFS Úložiskom"
slug: "k3s-nasadenie-chromadb-nfs"
technologies: ["Kubernetes", "k3s", "ChromaDB", "NFS", "YAML"]
tags: ["chromadb", "kubernetes", "k3s", "deployment", "vector-db", "rag", "nfs", "persistent-storage", "debugging"]
date_solved: "2025-08-20"

Projekt/Téma: Nasadenie perzistentnej inštancie vektorovej databázy ChromaDB do K3s klastra s využitím existujúceho NFS úložiska pre potreby RAG systému.

1. Cieľ / Problém na vyriešenie: Vytvoriť v K3s klastri spoľahlivú a perzistentnú službu vektorovej databázy ChromaDB. Služba musí byť dostupná pre ostatné aplikácie v rámci klastra (napr. n8n) a jej dáta musia byť ukladané na existujúci zdieľaný NFS server, aby prežili reštarty a zmeny v Padoch.

2. Použité technológie a nástroje:

• kubectl: Nástroj na správu Kubernetes objektov.
• YAML: Formát pre definíciu Kubernetes manifestov.
• ChromaDB: Vektorová databáza, nasadená z oficiálneho kontajnerového obrazu chromadb/chroma.
• NFS (Network File System): Existujúce zdieľané úložisko v klastri.
• nfs-subdir-external-provisioner: Dynamický provisioner, ktorý automaticky vytvára adresáre na NFS serveri pre nové PersistentVolumeClaim.

3. Kľúčové postupy a konfiguračné kroky:

1. Vytvorenie dedikovaného Namespace: Pre lepšiu organizáciu a izoláciu zdrojov bol vytvorený menný priestor vector-db.
2. Definícia PersistentVolumeClaim (PVC): Bol vytvorený PVC, ktorý explicitne požaduje úložisko od StorageClass s názvom nfs-client, čím sa zabezpečilo, že dáta budú uložené na NFS serveri.
3. Definícia Deployment: Nasadenie definuje Pod pre ChromaDB, pripája k nemu PVC a konfiguruje spôsob spustenia aplikácie.
4. Definícia Service: Služba typu ClusterIP bola vytvorená na vystavenie ChromaDB na stabilnej DNS adrese a porte v rámci klastra.
5. Aplikácia manifestu: Všetky objekty boli nasadené do klastra pomocou príkazu kubectl apply.
6. Diagnostika a oprava: Po počiatočnom neúspechu nasadenia (CrashLoopBackOff) boli analyzované logy Podu na identifikáciu a opravu chybnej konfigurácie.

4. Výsledné kódy a skripty:

• Finálny a funkčný manifest vector-db-deployment.yaml:

  apiVersion: v1
  kind: Namespace
  metadata:
    name: vector-db
  ---
  apiVersion: v1
  kind: PersistentVolumeClaim
  metadata:
    name: chromadb-pvc
    namespace: vector-db
  spec:
    accessModes:
      - ReadWriteOnce
    resources:
      requests:
        storage: 5Gi 
    storageClassName: "nfs-client"
  ---
  apiVersion: apps/v1
  kind: Deployment
  metadata:
    name: chromadb
    namespace: vector-db
  spec:
    replicas: 1
    selector:
      matchLabels:
        app: chromadb
    template:
      metadata:
        labels:
          app: chromadb
      spec:
        containers:
          - name: chromadb
            image: chromadb/chroma:0.5.4
            env:
              - name: PERSIST_DIRECTORY
                value: "/chroma-data"
            args: ["--host", "0.0.0.0", "--port", "8000"]
            ports:
              - containerPort: 8000
                protocol: TCP
            volumeMounts:
              - name: chromadb-storage
                mountPath: /chroma-data
        volumes:
          - name: chromadb-storage
            persistentVolumeClaim:
              claimName: chromadb-pvc
  ---
  apiVersion: v1
  kind: Service
  metadata:
    name: chromadb-service
    namespace: vector-db
  spec:
    type: ClusterIP
    selector:
      app: chromadb
    ports:
      - protocol: TCP
        port: 8000
        targetPort: 8000

• Príkazy na nasadenie a overenie:

  # Nasadenie alebo aktualizácia
  kubectl apply -f vector-db-deployment.yaml
  
  # Overenie stavu
  kubectl get pods -n vector-db
  kubectl get svc -n vector-db
  kubectl get pvc -n vector-db

5. Zistené problémy a riešenia (Gotchas):

• Problém: Po prvotnom nasadení prešiel Pod do stavu CrashLoopBackOff.
  • Diagnostika: Príkaz kubectl logs -n vector-db <pod-name> odhalil chybovú hlášku: Error: No such option: --path.
  • Príčina: Použitá verzia obrazu chromadb/chroma:0.5.4 nepodporuje štartovací argument --path na definovanie cesty k dátam. Tento spôsob konfigurácie bol v novších verziách zmenený.
  • Riešenie: V manifeste Deployment bol chybný argument args: ["--path", "/chroma-data"] nahradený správnou metódou – použitím premennej prostredia (env). Aplikácia v tejto verzii očakáva premennú PERSIST_DIRECTORY s hodnotou cesty, kam má ukladať dáta.

6. Finálny výsledok / Záver: Po oprave konfiguračného manifestu bol Pod ChromaDB úspešne spustený a prešiel do stavu Running (1/1). Vektorová databáza je teraz plne funkčná, dostupná v rámci klastra na adrese chromadb-service.vector-db:8000 a jej dáta sú bezpečne a perzistentne ukladané na zdieľanom NFS úložisku.