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 (Kubernetes 1.33):

1. Kubernetes-Repository einbinden, Komponenten installieren und fixieren:

sudo apt-get update
sudo apt-get install -y apt-transport-https ca-certificates curl gpg
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.33/deb/Release.key | sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg
echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/v1.33/deb/ /' | sudo tee /etc/apt/sources.list.d/kubernetes.list
sudo apt-get update
sudo apt-get install -y kubelet kubeadm kubectl
sudo apt-mark hold kubelet kubeadm kubectl

2. Swap deaktivieren, Kernel-Module und sysctl-Parameter setzen:

sudo swapoff -a
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF
sudo modprobe overlay
sudo modprobe br_netfilter

cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF
sudo sysctl --system

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. Cluster initialisieren und kubeconfig für Ihren Benutzer einrichten:

sudo kubeadm init --pod-network-cidr=10.244.0.0/16
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

5. Netzwerk-Plugin installieren:

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. Danach den GPU Operator installieren – siehe NVIDIA / GPU → GPU Operator.

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; Values-Datei unter NVIDIA / GPU → GPU Operator) – 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

Zurück: NVIDIA / GPU · Weiter: Speicher