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

// installation

Netzwerk

Schritt 6 von 10 · Weg A (Bare Metal)

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), OpenAI-kompatible API (/v1), Anwendungsendpunkte (/rest), 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.

Client-Geräte müssen der ausstellenden CA vertrauen

Bei existing-secret mit einem Zertifikat Ihrer internen CA und bei local zeigt der Browser nur dann eine sichere Verbindung, wenn das Gerät der ausstellenden CA vertraut. Sonst erscheint eine Sicherheitswarnung, obwohl die Verbindung verschlüsselt ist.

  • Domänen-PCs erhalten das Stammzertifikat Ihrer internen CA meist automatisch per Gruppenrichtlinie. Dort ist nichts zu tun.
  • Geräte ohne Domänenbeitritt (Testrechner, private Geräte, Tablets) kennen die CA nicht. Importieren Sie dort das Stammzertifikat in den Zertifikatsspeicher des Betriebssystems unter „Vertrauenswürdige Stammzertifizierungsstellen“, oder verteilen Sie es über Ihr Geräte-Management.
  • Firefox nutzt je nach Einstellung einen eigenen Zertifikatsspeicher. Aktivieren Sie dort security.enterprise_roots.enabled oder importieren Sie die CA in Firefox selbst.

Mit cert-manager und einer öffentlichen CA wie Let's Encrypt entfällt dieser Schritt, weil alle Geräte der CA bereits vertrauen.

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 Server vorbereiten:

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

Zurück: Speicher · Weiter: basebox installieren