Licensed to be used in conjunction with basebox, only.
// installation
Netzwerk
Gilt für
Produkt: Server · Zielgruppe: Platform Operator
DNS, TLS-Modi (cert-manager, vorhandenes Secret, lokal), erforderlicher ausgehender Zugang und die Netzgrenze zwischen AISRV und Inferenz. Die Netzwerkentscheidungen fließen direkt in die Helm-Values ein – treffen Sie sie vor der Installation.
DNS
basebox läuft unter einem Hostname (global.domain), über den Frontend, GraphQL (/graphql, /subscriptions), REST/OpenAI-API (/rest, /v1), Medien (/media) und Keycloak (/auth) ausgeliefert werden. Der Hostname muss auf die Ingress-IP des Clusters auflösen – öffentlich, im internen DNS oder für die Evaluierung per /etc/hosts (basebox.local).
Der Hostname ist zugleich die Basis für OIDC: Das Frontend erwartet VITE_BB_OIDC_DOMAIN als https://<domain>/auth/realms/ – mit abschließendem Schrägstrich. Das Chart setzt das aus global.domain; ändern Sie den Hostname später, müssen Frontend- und AISRV-Konfiguration folgen (Fehlerbild „Organisation not found", Weiterleitungsschleife – siehe FAQ).
TLS-Modus
Das Chart-Verhalten steuert global.tls.mode:
| Modus | Wer stellt das Zertifikat | AISRV-JWKS-Modus | Wann |
|---|---|---|---|
cert-manager |
cert-manager erzeugt und erneuert das Secret global.tls.secretName über einen ClusterIssuer |
JWKS-URL | Öffentliche Domain mit ACME (Let's Encrypt) |
existing-secret |
Sie legen ein Secret vom Typ kubernetes.io/tls (tls.crt, tls.key) im Namespace an; Name = global.tls.secretName |
JWKS-URL | Interne CA, eigenes Zertifikat, private Installation ohne Internet |
local |
Das Chart erzeugt ein selbstsigniertes Secret (basebox-local-tls), sofern keines existiert |
JWKS-Datei | Evaluierung (basebox.local); Browser warnt, bis ein lokal vertrauenswürdiges Zertifikat (z. B. mkcert) hinterlegt ist |
Der Hostname ist nicht das Unterscheidungsmerkmal; basebox.internal kann local oder existing-secret nutzen. Entscheidend ist das Vertrauensmodell. Let's Encrypt ist für private Installationen nicht nötig. Befehle je Modus: Helm Charts verwenden.
Bestehendes Secret anlegen:
kubectl create namespace basebox --dry-run=client -o yaml | kubectl apply -f -
kubectl -n basebox create secret tls customer-tls \
--cert=<PATH_TO_TLS_CERTIFICATE> \
--key=<PATH_TO_TLS_PRIVATE_KEY>
Ingress
Das Chart bringt nginx-Annotationen mit, die Sie kennen sollten, weil sie das Verhalten bestimmen: proxy-body-size: 20m (Uploads), große Header-Puffer (JWT), proxy-read/send-timeout: 86400 (WebSocket, Streaming), proxy-buffering: off (Streaming), CORS (Authorization, Content-Type, X-Realm), Cache-Control no-store. Details: Helm-Chart-Übersicht → Ingress-Konfiguration. Ein Reverse Proxy vor dem Ingress muss dieselben Eigenschaften haben – vor allem keine Pufferung und lange Timeouts, sonst bricht Streaming.
Firewall
Eingehend zum Server:
| Port | Zweck |
|---|---|
| 22/TCP | SSH (auf Admin-Netz beschränken) |
| 443/TCP (80/TCP) | Ingress für Nutzer und API-Clients |
| 6443/TCP | Kubernetes-API – nur wenn extern benötigt |
| 10250/TCP | Kubelet – nur innerhalb des Clusters |
Ausgehend (Installation und Updates): HTTPS 443 zu den Paketquellen, NVIDIA, Kubernetes, Helm, Registries und gitea.basebox.health – die vollständige Liste mit Testbefehlen unter Erforderlicher Netzzugang. Ausgehend im Betrieb: nur, was Integrationen brauchen – SMTP, LDAP/OIDC, Konnektor-Zielsysteme, Websuche-Anbieter (api.staan.ai bzw. DuckDuckGo-Hosts). Übersicht aller Pfade: VPN / Netzwerk.
UFW-Beispiel aus dem Server Preparation Guide:
sudo ufw allow 22/tcp && sudo ufw allow 443/tcp && sudo ufw allow 80/tcp
sudo ufw allow 6443/tcp && sudo ufw allow 10250/tcp
sudo ufw enable
Die Grenze AISRV ↔ Inferenz
Nutzer sprechen nie direkt mit der Inferenz; nur AISRV tut das. Läuft die Inferenz auf demselben Cluster, bleibt der Verkehr intern (http://inference:8000). Läuft sie auf einem separaten GPU-Host, gilt:
- Nur AISRV darf den Inferenz-Endpunkt erreichen (Firewall-Regel von AISRV-Knoten zum GPU-Host); Endnutzer nicht.
- Der Endpunkt verlangt einen API-Schlüssel, gespeichert als Kubernetes-Secret, nie in Values.
- TLS, wenn Hosts oder Sicherheitszonen überschritten werden. Nutzt der Endpunkt ein Zertifikat einer privaten CA, importieren Sie die CA in den basebox-Workload – Ingress-Zertifikat und Inferenz-Zertifikat sind getrennte Vertrauensentscheidungen.
- Prompts, abgerufener Kontext und Dokumentinhalte wandern über diesen Pfad; beide Hosts gehören in dieselbe Datenverarbeitungsgrenze.
Ausgearbeitetes Beispiel mit Values und Prüfschritten: Deployment-Topologien.
Cluster-DNS
Auf k3s mit systemd-resolved schlägt die Namensauflösung in inference und ragsrv-support fehl („Temporary error in name resolution"). Lösung: coredns auf einen erreichbaren DNS-Server zeigen lassen – FAQ.
Prüfen
nslookup <domain> # zeigt auf die Ingress-IP
kubectl -n basebox get ingress # nach der Installation: Host = global.domain
kubectl -n basebox get secret <tls-secret> -o jsonpath='{.type}{"\n"}' # kubernetes.io/tls
curl -fsSL https://gitea.basebox.health -o /dev/null && echo registry ok
Checkliste
- Hostname entschieden und im DNS auf die Ingress-IP gesetzt
- TLS-Modus gewählt; Zertifikat/Secret oder ClusterIssuer bereit
- Eingehende Ports 443 (und 22 für Admins) offen; 6443/10250 nur intern
- Ausgehende Domains für Installation freigegeben – oder Offline-Transfer
- Bei externer Inferenz: Firewall AISRV → GPU-Host, API-Schlüssel als Secret, TLS/CA geklärt
- Ausgehende Pfade für Integrationen (SMTP, LDAP/OIDC, Konnektoren, Websuche) geplant
Nächster Schritt: basebox installieren