Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// installation

RAGSRV-Konfiguration

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

Übersicht

RAGSRV (Retrieval-Augmented Generation Server) stellt Vektordatenbank- und Dokumentverarbeitungsfunktionen für die basebox-KI-Plattform bereit. Er übernimmt Dokumentaufnahme, Embedding-Erzeugung und semantische Suche und arbeitet für RAG-basierte Antworten mit Sprachmodellen zusammen. Der Dienst nutzt PostgreSQL mit der Erweiterung pgvector zur Vektorspeicherung.

Deployment

RAGSRV wird per Helm-Chart in Kubernetes-Cluster bereitgestellt, mit einer integrierten, von CloudNativePG verwalteten PostgreSQL-Datenbank. Für optimale Embedding-Leistung benötigt er GPU-Ressourcen.

Helm-Chart-Konfiguration

Grundeinstellungen

Parameter	Standard	Beschreibung
replicaCount	1	Anzahl der RAGSRV-Pod-Replikate
image.repository	gitea.basebox.health/basebox-distribution/ragsrv	Container-Image-Repository
image.pullPolicy	IfNotPresent	Image-Pull-Policy
image.tag	gpu-latest	Image-Tag (GPU-fähige Version)
fullnameOverride	ragsrv	Vollständigen Namen des Deployments überschreiben

Dienstkonfiguration

Parameter	Standard	Beschreibung
service.type	ClusterIP	Kubernetes-Service-Typ
service.port	3001	Service-Port

Ressourcenverwaltung

Parameter	Standard	Beschreibung
resources	{}	CPU-/Speicher-Requests und -Limits
autoscaling.enabled	false	Horizontales Pod-Autoscaling aktivieren
autoscaling.minReplicas	1	Minimale Anzahl Replikate
autoscaling.maxReplicas	100	Maximale Anzahl Replikate
autoscaling.targetCPUUtilizationPercentage	80	Ziel-CPU-Auslastung für die Skalierung

Health-Checks

Parameter	Standard	Beschreibung
livenessProbe	{}	Konfiguration der Liveness-Probe (standardmäßig aus)
readinessProbe	{}	Konfiguration der Readiness-Probe (standardmäßig aus)

Datenbankkonfiguration

Datenbankeinstellungen

Parameter	Standard	Beschreibung
database.enabled	true	Datenbankerstellung aktivieren
database.imageName	ghcr.io/cloudnative-pg/postgresql:16-standard-bookworm	PostgreSQL-Image
database.host	ragsrv-db-rw	Datenbank-Host (Read-Write-Service)
database.port	5432	Datenbank-Port
database.user	ragsrv	Datenbank-Benutzername
database.password	<secure-password>	Datenbank-Passwort
database.name	ragsrv	Datenbankname

CloudNativePG-Cluster-Einstellungen

Parameter	Standard	Beschreibung
ragsrv-db.cluster.instances	1	Anzahl PostgreSQL-Instanzen
ragsrv-db.cluster.storage.size	5Gi	Speichergröße der Datenbank
ragsrv-db.cluster.storage.storageClass	default	Zu verwendende Storage Class
ragsrv-db.cluster.monitoring.enablePodMonitor	false	Prometheus-Monitoring aktivieren

Datenbankerweiterungen

Die Datenbank wird automatisch initialisiert mit: - Erweiterung pgvector für die Vektor-Ähnlichkeitssuche - Eigenem Schema aus sql/01-schema.sql (per ConfigMap bereitgestellt) - Rolle SUPERUSER für den Anwendungsbenutzer

Umgebungsvariablen

Kernkonfiguration

Variable	Standard	Beschreibung
COMPUTE	gpu	Rechenmodus (gpu oder cpu)
HOST	0.0.0.0	Server-Host, an den gebunden wird
SERVER_PORT	3001	Server-Port
LOG_LEVEL	trace	Log-Level (trace, debug, info, warn, error)
API_KEY	Erforderlich	API-Schlüssel zur Authentifizierung
API_KEY_HEADER	X-API-KEY	HTTP-Header-Name für den API-Schlüssel
SUPPORT_HTTP_STREAM	true	HTTP-Streaming-Unterstützung aktivieren

Datenbankverbindung (aus Secrets)

Variable	Quelle	Beschreibung
DB_HOST	Secret ragsrv-database	Datenbank-Hostname
DB_PORT	Secret ragsrv-database	Datenbank-Port
DB_USER	Secret ragsrv-database	Datenbank-Benutzername
DB_NAME	Secret ragsrv-database	Datenbankname
DB_PASSWORD	Secret ragsrv-database	Datenbank-Passwort

OAuth/Authentifizierung

Variable	Beschreibung
REQUIRE_AUTH	Authentifizierungspflicht ein-/ausschalten
OAUTH_IDP_URL	URL des OAuth-Identitätsanbieters
OAUTH_IDP_AUD	OAuth-Audience-Claim
OAUTH_JWKS_URL	JWKS-Endpunkt zur Token-Prüfung
ALLOWED_IPS	Kommagetrennte Liste erlaubter IP-Adressen

GraphQL-Konfiguration

Variable	Standard	Beschreibung
GRAPHQL_ALLOW_INTROSPECTION	true	GraphQL-Introspektions-Queries erlauben
GRAPHQL_GRAPHIQL	true	GraphiQL-Oberfläche aktivieren

Integrationskonfiguration

Variable	Beschreibung
SUPPORT_SERVICE_URL	URL des Dienstes ragsrv-support für die Modellverarbeitung
WEBHOOK_STATE_URL	Webhook-URL für Statusaktualisierungen (AISRV-Endpunkt)
OWNER_NAMESPACE_UUID	Standard-Namespace-UUID für die Eigentümerschaft

Betriebseinstellungen

Variable	Standard	Beschreibung
LOG_HEALTH_CHECKS	false	Health-Check-Anfragen protokollieren

Speicherkonfiguration

Persistente Volumes

RAGSRV kann persistente Volumes für temporäre Dateien nutzen:

volumes:
  - name: ragsrv-tmp
    persistentVolumeClaim:
      claimName: <name>

volumeMounts:
  - name: ragsrv-tmp
    mountPath: /tmp/ragsrv

Konfigurationsbeispiele

Produktivkonfiguration

# values-production.yaml
replicaCount: 2

image:
  repository: gitea.basebox.health/basebox-distribution/ragsrv
  tag: "v1.2.3"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 3001

resources:
  requests:
    cpu: 2000m
    memory: 8Gi
    nvidia.com/gpu: 1
  limits:
    cpu: 4000m
    memory: 16Gi
    nvidia.com/gpu: 1

livenessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 60
  periodSeconds: 30
  timeoutSeconds: 10
  failureThreshold: 3

readinessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 30
  periodSeconds: 10
  timeoutSeconds: 5
  failureThreshold: 5

database:
  enabled: true
  imageName: ghcr.io/cloudnative-pg/postgresql:16-standard-bookworm
  host: ragsrv-db-rw
  port: 5432
  user: ragsrv
  password: "<generate-secure-password>"
  name: ragsrv

ragsrv-db:
  cluster:
    instances: 3
    storage:
      size: 50Gi
      storageClass: fast-ssd
    monitoring:
      enablePodMonitor: true

volumes:
  - name: ragsrv-tmp
    persistentVolumeClaim:
      claimName: ragsrv-shared-storage

volumeMounts:
  - name: ragsrv-tmp
    mountPath: /tmp/ragsrv

nodeSelector:
  nvidia.com/gpu: "true"

env:
  COMPUTE: "gpu"
  SUPPORT_HTTP_STREAM: "true"
  API_KEY: "<generate-secure-api-key>"
  LOG_LEVEL: "info"
  HOST: "0.0.0.0"
  SERVER_PORT: "3001"

  # OAuth/Auth
  REQUIRE_AUTH: "true"
  OAUTH_IDP_URL: "http://idp:8080/realms/production"
  OAUTH_IDP_AUD: "ragsrv"
  OAUTH_JWKS_URL: "http://idp:8080/realms/production/protocol/openid-connect/certs"

  # Integration
  SUPPORT_SERVICE_URL: "http://ragsrv-support:8000"
  WEBHOOK_STATE_URL: "http://aisrv:8888/rag/v1/state"
  OWNER_NAMESPACE_UUID: "<generate-uuid>"

  # GraphQL
  GRAPHQL_ALLOW_INTROSPECTION: "false"
  GRAPHQL_GRAPHIQL: "false"

  # API
  API_KEY_HEADER: "X-API-KEY"
  LOG_HEALTH_CHECKS: "false"

  # Database (from secrets)
  DB_HOST:
    valueFrom:
      secretKeyRef:
        name: ragsrv-database
        key: host
  DB_PORT:
    valueFrom:
      secretKeyRef:
        name: ragsrv-database
        key: port
  DB_USER:
    valueFrom:
      secretKeyRef:
        name: ragsrv-database
        key: username
  DB_NAME:
    valueFrom:
      secretKeyRef:
        name: ragsrv-database
        key: name
  DB_PASSWORD:
    valueFrom:
      secretKeyRef:
        name: ragsrv-database
        key: password

Reine CPU-Konfiguration

Für Umgebungen ohne GPU-Unterstützung:

# values-cpu.yaml
image:
  tag: "cpu-latest"

resources:
  requests:
    cpu: 4000m
    memory: 16Gi
  limits:
    cpu: 8000m
    memory: 32Gi

env:
  COMPUTE: "cpu"
  # ... other configuration

Hochverfügbarkeitskonfiguration

# values-ha.yaml
replicaCount: 3

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

resources:
  requests:
    cpu: 2000m
    memory: 8Gi
    nvidia.com/gpu: 1
  limits:
    cpu: 4000m
    memory: 16Gi
    nvidia.com/gpu: 1

ragsrv-db:
  cluster:
    instances: 3
    storage:
      size: 100Gi
      storageClass: fast-ssd

affinity:
  podAntiAffinity:
    preferredDuringSchedulingIgnoredDuringExecution:
      - weight: 100
        podAffinityTerm:
          labelSelector:
            matchExpressions:
              - key: app.kubernetes.io/name
                operator: In
                values:
                  - ragsrv
          topologyKey: kubernetes.io/hostname

Installation

Voraussetzungen

• Kubernetes-Cluster (1.23+)
• Helm 3.x
• CloudNativePG-Operator installiert
• GPU-Knoten mit NVIDIA GPU Operator (für den GPU-Modus)
• Storage-Provisioner mit dynamischer Bereitstellung

CloudNativePG-Operator installieren

helm repo add cnpg https://cloudnative-pg.github.io/charts
helm upgrade --install cnpg \
  --namespace cnpg-system \
  --create-namespace \
  cnpg/cloudnative-pg

RAGSRV-Chart installieren

# Install with custom values
helm install ragsrv oci://gitea.basebox.health/basebox-distribution/helm/ragsrv \
  --values values-production.yaml \
  --namespace basebox \
  --create-namespace

# Verify installation
kubectl get pods -n basebox -l app.kubernetes.io/name=ragsrv
kubectl get cluster -n basebox ragsrv-db

Upgrade

helm upgrade ragsrv oci://gitea.basebox.health/basebox-distribution/helm/ragsrv \
  --values values-production.yaml \
  --namespace basebox

Deinstallation

helm uninstall ragsrv --namespace basebox

# Delete PVCs if needed
kubectl delete pvc -n basebox -l cnpg.io/cluster=ragsrv-db

Prüfung

Deployment prüfen

# Check RAGSRV pods
kubectl get pods -n basebox -l app.kubernetes.io/name=ragsrv

# Check database cluster
kubectl get cluster -n basebox ragsrv-db

# View logs
kubectl logs -n basebox -l app.kubernetes.io/name=ragsrv --tail=100

# Check GPU allocation (if using GPU mode)
kubectl describe pod -n basebox -l app.kubernetes.io/name=ragsrv | grep -A5 "nvidia.com/gpu"

Health-Endpunkt testen

# Port forward
kubectl port-forward -n basebox svc/ragsrv 3001:3001

# Test health endpoint
curl http://localhost:3001/health

GraphQL-API testen

# Access GraphiQL interface
kubectl port-forward -n basebox svc/ragsrv 3001:3001

# Open browser to http://localhost:3001/graphql

Secrets-Verwaltung

Das Chart erzeugt das Secret ragsrv-database automatisch mit den Datenbank-Verbindungsdaten: - host – Datenbank-Hostname - port – Datenbank-Port - name – Datenbankname - username – Datenbank-Benutzername - password – Datenbank-Passwort

Wichtig: Ändern Sie Standardpasswörter in der Produktion.

Initialisierung des Datenbankschemas

Die Datenbank wird initialisiert mit:

1. Erweiterung pgvector – Vektor-Ähnlichkeitssuche
2. Eigenem Schema – geladen aus sql/01-schema.sql per ConfigMap
3. Rolle SUPERUSER – erforderlich für die Erweiterungsverwaltung

Die Schema-SQL-Datei ist im Chart eingebettet und wird bei der Datenbankinitialisierung angewendet.

GPU-Konfiguration

GPU-Anforderungen

• NVIDIA-GPU mit CUDA-Unterstützung
• NVIDIA GPU Operator im Cluster installiert
• Knoten mit Label nvidia.com/gpu=true

GPU-Ressourcenzuteilung

resources:
  requests:
    nvidia.com/gpu: 1
  limits:
    nvidia.com/gpu: 1

nodeSelector:
  nvidia.com/gpu: "true"

GPU-Zugriff prüfen

# Check GPU allocation
kubectl describe pod -n basebox <ragsrv-pod-name> | grep -A5 Limits

# Check GPU usage inside pod
kubectl exec -n basebox <ragsrv-pod-name> -- nvidia-smi

Integration mit anderen Diensten

AISRV-Integration

RAGSRV sendet Statusaktualisierungen per Webhook an AISRV:

env:
  WEBHOOK_STATE_URL: "http://aisrv:8888/rag/v1/state"

RAGSRV-Support-Integration

RAGSRV delegiert die Modellinferenz an den Support-Dienst:

env:
  SUPPORT_SERVICE_URL: "http://ragsrv-support:8000"

Authentifizierung über den IDP

OAuth-/OIDC-Authentifizierung über Keycloak:

env:
  OAUTH_IDP_URL: "http://idp:8080/realms/production"
  OAUTH_JWKS_URL: "http://idp:8080/realms/production/protocol/openid-connect/certs"

Sicherheitsaspekte

API-Schlüsselverwaltung

• Kryptografisch sichere API-Schlüssel erzeugen
• API-Schlüssel regelmäßig rotieren
• API-Schlüssel in Kubernetes-Secrets speichern (nicht in Values-Dateien)
• Je Umgebung unterschiedliche API-Schlüssel verwenden

Datenbanksicherheit

• Starke Datenbankpasswörter verwenden
• SSL/TLS für Datenbankverbindungen in Produktion aktivieren
• Regelmäßige Backups und getestete Wiederherstellungsverfahren
• Auf ungewöhnliche Abfragemuster achten

Netzwerksicherheit

• ClusterIP für rein interne Dienste nutzen
• Network Policies zur Verkehrsbeschränkung umsetzen
• Authentifizierung in Produktion aktivieren (REQUIRE_AUTH: true)
• IP-Allowlisting für zusätzliche Sicherheit nutzen

Performance-Tuning

GPU- vs. CPU-Modus

• GPU-Modus: Schnellere Embedding-Erzeugung, geringere Latenz, höherer Durchsatz
• CPU-Modus: Flexibler, keine GPU nötig, höherer Speicherbedarf

Ressourcenzuteilung

Für den GPU-Modus:

resources:
  requests:
    cpu: 2000m
    memory: 8Gi
    nvidia.com/gpu: 1
  limits:
    cpu: 4000m
    memory: 16Gi
    nvidia.com/gpu: 1

Für den CPU-Modus:

resources:
  requests:
    cpu: 4000m
    memory: 16Gi
  limits:
    cpu: 8000m
    memory: 32Gi

Datenbank-Performance

• PostgreSQL-Instanzen für Lesereplikate erhöhen
• Schnellen Speicher (SSD/NVMe) für besseres I/O nutzen
• pgvector-Index-Performance überwachen
• PostgreSQL-Parameter für Vektoroperationen tunen

Skalierungsstrategien

• Horizontale Skalierung mit Autoscaling bei variabler Last
• Vertikale Skalierung (mehr GPU/CPU) bei konstant hoher Last
• Datenbank-Lesereplikate für abfragelastige Workloads

Monitoring und Metriken

Health-Checks

Health-Probes für die Produktion konfigurieren:

livenessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 60
  periodSeconds: 30

readinessProbe:
  httpGet:
    path: /health
    port: http
  initialDelaySeconds: 30
  periodSeconds: 10

Datenbank-Monitoring

CloudNativePG-Monitoring aktivieren:

ragsrv-db:
  cluster:
    monitoring:
      enablePodMonitor: true