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

// installation

Kubernetes

Gilt für

Produkt: Server · Zielgruppe: Platform Operator

Cluster-Anforderungen für basebox, Ingress-Controller, CloudNativePG und die Unterschiede zwischen Einzelknoten und CPU-/GPU-Knoten-Layout. Am Ende dieses Schritts bietet Ihr Cluster alles, was das basebox-Umbrella-Chart voraussetzt.

Offizielle Dokumentation: Kubernetes mit kubeadm · Calico · CloudNativePG · ingress-nginx

Was das Chart verlangt

Anforderung Wert
Kubernetes 1.23+ (geprüft: 1.33.7; 1.33+ empfohlen)
Helm 3.x (geprüft: 3.20.0)
Ingress-Controller Beliebig; das Chart bringt nginx-Annotationen mit
Speicher Dynamische Volume-Bereitstellung mit einer Standard-Storage-Class
Datenbanken CloudNativePG-Operator im Cluster
GPU NVIDIA GPU Operator (oder Vergleichbares) auf GPU-Knoten – siehe NVIDIA / GPU
Registry Pull-Zugang zu gitea.basebox.health aus der Runtime der Knoten

1. Kubernetes installieren (kubeadm)

Der geprüfte Weg mit kubeadm, containerd und Calico steht mit allen Befehlen unter Server Preparation Guide → Schritt 7. Die Reihenfolge:

  1. Kubernetes-Repository (1.33) einbinden, kubelet kubeadm kubectl installieren und per apt-mark hold fixieren.
  2. Swap deaktivieren; Kernel-Module overlay, br_netfilter und die sysctl-Parameter für Bridge-Netfilter und IP-Forwarding setzen.
  3. containerd konfigurieren, bevor Sie kubeadm init ausführen – die Standardkonfiguration hat das CRI-Plugin deaktiviert: 
    sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml > /dev/null
sudo systemctl restart containerd && sudo systemctl enable containerd
  4. sudo kubeadm init --pod-network-cidr=10.244.0.0/16, dann kubeconfig für Ihren Benutzer einrichten.
  5. Netzwerk-Plugin: kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.31.3/manifests/calico.yaml
  6. Prüfen: kubectl get nodes zeigt den Knoten Ready.

Alternative Distributionen wie k3s funktionieren; beachten Sie dort das DNS-Problem mit systemd-resolved – Lösung in der FAQ.

2. Einzelknoten oder mehrere Knoten

Einzelknoten (die Referenzkonfigurationen): Control Plane und Workloads auf derselben Maschine. Der Control-Plane-Taint verhindert standardmäßig, dass Pods geplant werden. Zwei Wege:

  • Tolerations in den Values der Komponenten, die sie brauchen (GPU Operator; siehe dessen Values-Datei im Server Preparation Guide) – der saubere Weg für Produktion.
  • Taint entfernen – nur für Entwicklung/Test: 
    kubectl taint nodes --all node-role.kubernetes.io/control-plane-

CPU- und GPU-Knoten: Die basebox-Plattform läuft auf CPU-Knoten, Service-Modelle und Inferenz auf GPU-Knoten. Labeln Sie Knoten (nvidia.com/gpu: "true", ggf. gpu-type) und nutzen Sie nodeSelector/tolerations in den Values der GPU-Dienste – Beispiele auf den Seiten Inference Server und Ragsrv. Der GPU Operator muss nur auf den GPU-Knoten arbeiten.

Getrennte Cluster für Plattform und Inferenz: Deployment-Topologien.

3. Ingress-Controller

Das Chart konfiguriert Ingress-Ressourcen mit nginx-Annotationen: 20 MB Body für Uploads, große Puffer für JWT-Header, 24-Stunden-Timeouts für WebSocket und Streaming, Pufferung aus, CORS, Cache-Control. Installieren Sie ingress-nginx (oder einen Controller, der diese Annotationen versteht) und merken Sie sich die Ingress-Klasse (nginx) und die externe IP:

kubectl get svc -A | grep -i ingress

Die Annotationen im Detail: Helm-Chart-Übersicht → Ingress-Konfiguration.

4. Storage Class

basebox braucht dynamische Volume-Bereitstellung für die PostgreSQL-Cluster, Medien und Modell-Caches. Für die Evaluierung genügt eine lokale Storage Class (local-path, Standard im Schnellstart); für Produktion eine Storage Class auf SSD/NVMe mit Snapshots oder Replikation. Setzen Sie sie als Standard oder benennen Sie sie in den Values (storageClass). Kapazitätsplanung: Speicher.

kubectl get storageclass

5. CloudNativePG-Operator

Jeder basebox-Dienst mit Datenbank (AISRV, storesrv, ragsrv, Keycloak) erhält einen eigenen PostgreSQL-Cluster, verwaltet von CloudNativePG:

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

Das Umbrella-Chart enthält den Operator ebenfalls als Abhängigkeit (cnpg-operator.fullnameOverride: cnpg); installieren Sie ihn nur einmal – entweder vorab wie hier oder über das Chart.

6. cert-manager (optional)

Für öffentliche Domains mit automatischen Zertifikaten: cert-manager installieren und einen ClusterIssuer (z. B. letsencrypt-prod) anlegen. Bei interner CA oder Evaluierung nicht nötig – siehe Netzwerk.

7. Prüfen

kubectl get nodes -o wide
kubectl get pods -A
kubectl get storageclass
kubectl get svc -A | grep -i ingress
kubectl get pods -n cnpg-system
kubectl get pods -n gpu-operator            # auf GPU-Knoten
kubectl describe nodes | grep -A5 "Allocated resources"

Alles Ready/Running, eine Standard-Storage-Class, eine Ingress-IP, GPU-Ressourcen auf den GPU-Knoten – dann ist der Cluster bereit.

Häufige Fehlerbilder

Symptom Ursache Lösung
kubeadm init: „unknown service runtime.v1.RuntimeService" containerd-CRI deaktiviert Schritt 1.3, dann kubeadm reset und erneut init
Pods Pending Control-Plane-Taint, keine Storage Class, keine GPU Tolerations; kubectl get pvc; GPU Operator prüfen
inference/ragsrv-support: „Temporary error in name resolution" k3s mit systemd-resolved coredns auf externen DNS zeigen lassen (FAQ)
Image-Pull scheitert auf Knoten Registry-Zugang der Runtime Pull aus der Runtime testen, nicht nur von der Workstation

Nächster Schritt: Speicher