AnmeldenBriefing buchen

Kapitel 2.3

Planung einer Installation

Was eine Kubernetes-Installation von Nexus benötigt, bevor Sie den ersten Befehl eingeben, wie groß sie dimensioniert sein muss und welche zwei Entscheidungen Sie nicht rückgängig machen können: den Installationsnamen und die Schlüsselverwahrer. Den Abschluss bildet das ausgefüllte Planungsarbeitsblatt der Harrow Port Authority.

Diese Seite wurde mithilfe von KI aus dem englischen Original übersetzt. Bei Unklarheiten gilt die englische Seite als Referenz. Diese Seite auf Englisch lesen

16 Minuten Lesezeit

Als wir Nexus bei der Harrow Port Authority installierten, dauerten die Befehle einen Nachmittag. Die Planung dauerte eine Woche, und der Großteil dieser Woche ging für zwei Fragen drauf, die nichts mit Kubernetes zu tun haben: wie wir die Installation nennen würden und welche Personen ihre Wiederherstellungsschlüssel verwahren sollten. Beide Antworten sind endgültig. Alles andere in diesem Kapitel kann später über eine Werte-Datei (Values-Datei) und ein helm upgrade geändert werden.

Ich bin Tomás Reilly, der Plattform-Ingenieur bei Harrow. Harrow betreibt zwei Installationen. Dieses Kapitel plant die vernetzte Installation in unserem Unternehmensnetzwerk, in dem wir zuerst die Community-Edition als Pilotprojekt getestet haben. Das Betriebsnetzwerk des Hafens, das keine Verbindung zum Internet hat, erhielt später eine eigene Installation; Kapitel 2.10, Air-Gapped-Installation, behandelt diese. Dieses Kapitel ist das, was ich mir am ersten Morgen gewünscht hätte: welchen Cluster Nexus erwartet, auf welche Namen es hört, wie viel es Ihren Knoten abverlangt und welche Entscheidungen Sie vor der Installation mit Ihrer IT-Leitung klären müssen. Es schließt mit dem Arbeitsblatt, das Aoife Brennan, unsere IT-Leiterin, vor dem Start abgezeichnet hat. Kapitel 2.4, Ein Release beziehen und verifizieren, behandelt das Herunterladen und Prüfen des Releases, und Kapitel 2.5, Preflight mit nexusctl, prüft Ihren Cluster gegen alle hier genannten Punkte.

Was der Cluster mitbringen muss

Nexus wird als ein einziges Helm-Chart installiert, nexus, Version 1.0.0-alpha.1. Das Chart enthält die Plattformdienste sowie deren Datenschicht und verweigert die Installation auf einem Cluster, dem die nachfolgenden Komponenten fehlen.

Anforderung Was Nexus erwartet Warum
Kubernetes 1.33 oder neuer. Getestet unter k3s v1.33.6+k3s1 Das kubeVersion des Charts ist >=1.33.0-0, und helm install setzt dies durch
cert-manager v1.21.3, installiert vor Nexus Das Chart erstellt seine eigene lokale Zertifizierungsstelle (CA) sowie die Zertifikate, die seine Dienste für die Kommunikation untereinander verwenden
Helm v4 (wir haben v4.3.1 verwendet) Helm 4 wartet standardmäßig auf die Hook-Jobs des Charts, wovon die Installation abhängt
Eine StorageClass Eine als Standard markierte oder eine, die Sie in storage.className benennen Jeder Datenspeicher beansprucht ein Persistent Volume
Eine IngressClass Eine als Standard markierte oder eine, die Sie in ingress.className benennen Die drei öffentlichen Adressen sind reguläre networking.k8s.io/v1-Ingresses
Ports 80 und 443 Offen am Ingress-Controller, als LoadBalancer- oder NodePort-Service Benutzer erreichen Nexus über den Ingress-Controller
Architektur linux/amd64- oder linux/arm64-Knoten Jedes Image ist für beide Architekturen gebaut

Zwei Dinge fehlen absichtlich in dieser Tabelle. Nexus benötigt kein Service-Mesh: Gegenseitiges TLS (mTLS, Transport Layer Security in beide Richtungen) zwischen den Diensten wird von der lokalen CA des Charts über den cert-manager bereitgestellt. Das Chart verfügt über einen Schlüssel istio.enabled, der standardmäßig auf false steht, und Sie sollten ihn so belassen. Nexus benötigt zudem keine eigene Admission-Policy-Engine.

Auf Ihrer Workstation benötigen Sie kubectl, Helm v4, cosign v3 zur Überprüfung von Signaturen, age zur Erstellung von Treuhänderschlüsseln (Custodian Keys) und nexusctl, die Befehlszeilenschnittstelle (CLI) für Nexus-Betreiber. Kapitel 2.4, Ein Release beziehen und verifizieren, beschreibt, wo die einzelnen Nexus-Downloads zu finden sind.

Drei Adressen

Jede Installation antwortet auf drei Hostnamen. Das Chart nennt diese die Installationsidentität, und ohne sie verweigert jeder Dienst den Start.

Values-Schlüssel Name bei Harrow Was dort antwortet
hosts.console console.harrow.example Die Konsole, die Webanwendung, bei der sich Personen anmelden
hosts.api api.harrow.example Das Gateway, das die Anwendungsprogrammierschnittstelle (API) bereitstellt und jede Anfrage an die künstliche Intelligenz (KI) weiterleitet
hosts.auth auth.harrow.example Der Anmeldedienst, nexus-auth

global.domain enthält die Domain, unter der sich die drei befinden – bei uns harrow.example. Jeder Host ist ein eigenständiger vollständiger Name und kann unter jeder von Ihnen kontrollierten Domain liegen. Wir haben alle drei unter einer Domain belassen, da sie so von einem einzigen Zertifikat abgedeckt werden konnten.

Erstellen Sie für jeden der drei Namen einen Eintrag im Domain Name System (DNS), der auf die Adresse Ihres Ingress-Controllers verweist. Tun Sie dies vor dem Preflight. nexusctl preflight schlägt jeden Namen von Ihrer Workstation aus nach und bricht die Installation ab, wenn für einen davon kein Eintrag existiert, da niemand einen Namen erreichen kann, der nicht aufgelöst wird.

Links drei DNS-Namen: console.harrow.example, api.harrow.example und auth.harrow.example, jeweils mit einem Pfeil in ein Kästchen mit der Beschriftung „ingress controller, ports 80 and 443“. Von diesem Kästchen führen drei Pfeile in ein größeres Kästchen mit der Beschriftung „namespace nexus“: der console-Pfeil zu „nexus-alpha :3000“, der api-Pfeil zu „nexus-gateway :9092“ und der auth-Pfeil zu „nexus-auth :9101“. Ein gestrichelter Rahmen um den Namespace ist beschriftet mit „default deny; only the ingress namespace may reach these three“.
Wie die drei öffentlichen Namen die dahinterliegenden Dienste erreichen.

Festlegen, wo TLS terminiert wird

Der Schlüssel tls.mode des Charts entscheidet, wer die Zertifikate für die drei öffentlichen Adressen hält. Es gibt drei Möglichkeiten, zwischen denen Sie später über ein Upgrade wechseln können.

tls.mode Sie stellen bereit Was das Chart tut
existing (der Standard) Ein Kubernetes-TLS-Secret im Namespace nexus, benannt in tls.existingSecret Alle drei Ingresses verwenden dieses eine Secret
cert-manager Einen von Ihnen betriebenen ClusterIssuer, benannt in tls.clusterIssuer Annotiert jeden Ingress, sodass cert-manager nexus-console-tls, nexus-api-tls und nexus-auth-tls ausstellt
none Eine Komponente vor dem Cluster, die TLS terminiert, wie etwa Ihr eigener Load Balancer Rendert die Ingresses ohne TLS-Abschnitt

Bei existing bedient ein einziges Zertifikat alle drei Hosts; es muss daher alle drei enthalten, entweder als drei Subject Alternative Names oder als Wildcard für Ihre Domain. Wir haben ein Zertifikat der internen CA von Harrow verwendet. Preflight liest das Secret vor der Installation aus und gibt eine Warnung aus, wenn das Zertifikat innerhalb von 30 Tagen abläuft.

Bei cert-manager und einem Aussteller über die Automatic Certificate Management Environment (ACME) fügt das Chart keine eigene Weiterleitung hinzu, sodass eine /.well-known/acme-challenge/-Anfrage auf Port 80 den Solver unverändert erreicht. Fügen Sie an Ihrem Ingress-Controller keine HTTP-zu-HTTPS-Weiterleitung hinzu, die vor dem Challenge-Pfad greift; ein Zertifikat, das nicht erneuert werden kann, schlägt Wochen später stillschweigend fehl.

Unabhängig davon, wofür Sie sich am öffentlichen Netzwerkrand (Edge) entscheiden, kommunizieren die Dienste innerhalb des Namespaces immer über TLS der lokalen CA des Charts. Dieser Teil steht nicht zur Wahl, und deshalb ist der cert-manager auch dann eine Voraussetzung, wenn tls.mode auf existing oder none gesetzt ist.

Was den Cluster verlässt und was nicht

Das Chart rendert für den Namespace nexus eine Netzwerkrichtlinie nach dem Prinzip „Standardmäßig ablehnen“ (Default-Deny). Danach sind nur noch folgende Datenflüsse erlaubt:

  • Datenverkehr zwischen Nexus-Pods innerhalb des Namespaces;
  • DNS-Abfragen an den DNS-Dienst des Clusters;
  • der Kubernetes-API-Server, für die wenigen Dienste, die Workload-Token überprüfen;
  • der Namespace des Ingress-Controllers zu den drei öffentlichen Services;
  • alle Bereiche des Classless Inter-Domain Routing (CIDR), die Sie in networkPolicy.externalEgressCIDRs auflisten.

Diese letzte Liste ist standardmäßig leer. Wenn Sie ein Mail-Relay oder einen Modellserver außerhalb des Clusters verwenden möchten, gehört dessen Adressbereich dorthin. Die Telemetrie ist ausgeschaltet und bleibt ausgeschaltet: Das Schema akzeptiert nur telemetry.enabled: false, und die eigene Nutzungsberichterstattung der Datenspeicher ist ebenfalls deaktiviert.

Das Chart liest bei der Installation die Adressen des API-Servers aus dem Cluster aus. Wenn Ihr Konto die kubernetes-Endpoints im Namespace default nicht lesen kann, geben Sie diese selbst in networkPolicy.apiServerCIDRs als /32-Bereiche an. proxy.trustedCIDRs benennt das Pod-Netzwerk, in dem sich Ihr Ingress-Controller befindet, damit nexus-auth weiß, wessen X-Forwarded-For-Header es vertrauen kann. Der Standardwert, 10.42.0.0/16, ist das Pod-Netzwerk von k3s.

Dimensionierung

Die Standardanforderungen (Requests) des Charts summieren sich auf etwa 2,05 Kerne der zentralen Verarbeitungseinheit (CPU) und 6,7 GiB Arbeitsspeicher. Das ist der Wert, den der Scheduler reserviert; die Limits liegen höher, und die Datenspeicher wachsen in diese hinein, wenn Sie Benutzer und Dateien hinzufügen.

Komponente Angeforderte CPU Angeforderter Arbeitsspeicher
Neun Plattformdienste (Konsole, Backend for Frontend (BFF), Auth, Orchestrator, Workflows, Gateway, GraphRAG, Probitas, Skills Engine) 1,1 Kerne 2,6 GiB
Der Schlüsseldienst, nexus-keys 0,05 Kerne 64 MiB
PostgreSQL 0,25 Kerne 1 GiB
Neo4j 0,25 Kerne 2 GiB
Valkey, Qdrant und der Objektspeicher zusammen 0,25 Kerne 640 MiB
Die zwei OpenBao-Server des Schlüsselspeichers 0,15 Kerne 384 MiB

Die Standard-Volumes summieren sich auf 142 GiB:

Speicher Values-Schlüssel Standardgröße
PostgreSQL 16 mit PostGIS 3 und pgvector 0.8 dataTier.postgres.size 50Gi
Objektspeicher (SeaweedFS) dataTier.objectStore.size 50Gi
Neo4j 5.26 Community Edition dataTier.neo4j.size 20Gi
Qdrant dataTier.qdrant.size 10Gi
Valkey dataTier.valkey.size 5Gi
Der Schlüsselspeicher und sein Unsealer keys.openbao.storage.keystore, keys.openbao.storage.unsealer 5Gi und 1Gi
Quittungen des Schlüsseldienstes keys.receiptsStorage 1Gi

Planen Sie für einen einzelnen Knoten 8 vCPU, 32 GiB Arbeitsspeicher (RAM) und ein Solid-State-Drive (SSD) mit 250 GB ein. Für eine Evaluierung reichen 4 vCPU, 16 GiB und 200 GB aus. Das Installations-Disk-Image verweigert Maschinen mit weniger als 16 GiB Arbeitsspeicher (siehe Kapitel 2.9, Das Installations-Disk-Image), und ich würde dies überall als Untergrenze betrachten.

Grafikknoten sind optional. Ohne einen Knoten, der einen Grafikprozessor (GPU) bereitstellt, antwortet der Assistent über ein gehostetes Modell unter Verwendung des eigenen Schlüssels der Organisation. Preflight meldet dies als Warnung, niemals als Fehler. Kapitel 2.14, KI-Anbieter und -Modelle, behandelt beide Wege.

Jeder Speicher kann auch außerhalb des Clusters betrieben werden: Setzen Sie dataTier.<store>.mode auf external und geben Sie dessen Host sowie ein Secret an. Ein externes PostgreSQL benötigt für das Bootstrapping der Installation ein Superuser-Konto und ein Zertifikat, das Nexus verifizieren kann. Kapitel 2.11, Variationen: externe Speicher, TLS und Ingress, behandelt dies. Wenn Sie die Speicher im Cluster belassen, legen Sie sie auf einer StorageClass ab, hinter der echte Festplatten stehen. Die Datenbank ist der Teil, den Sie am meisten vermissen werden, wenn die lokale Festplatte eines Knotens ausfällt.

Der Installationsname ist dauerhaft

keys.installationName ist der Name, mit dem Betreiber diese Installation bezeichnen. Er muss ^[a-z][a-z0-9-]{0,62}$ entsprechen: ein Kleinbuchstabe, gefolgt von bis zu 62 Kleinbuchstaben, Ziffern oder Bindestrichen.

Wenn der Schlüsselspeicher zum ersten Mal startet, prägt er die Identität der Installation unter diesem Namen, und diese Identität steht danach endgültig fest. Eine Lizenz von Adverant wird für diese Identität ausgestellt, sodass eine für eine bestimmte Installation erstellte Lizenz auf einer anderen mit LICENCE_OTHER_INSTALLATION abgelehnt wird. Eine Umbenennung würde eine neue Installation, eine neue Identität und neue Lizenzen bedeuten.

Das Chart hat keinen Standardwert für den Namen. Es verweigert eine Installation ohne Namen (INSTALLATION_NAME_MISSING) und lehnt den Beispielnamen aus seinen eigenen Beispiel-Werte-Dateien ab (INSTALLATION_NAME_EXAMPLE). Preflight meldet beides, bevor Sie überhaupt so weit kommen.

Bei Harrow haben wir dafür länger gebraucht, als ich gerne zugebe. Wir haben uns auf harrow-port-authority geeinigt: Der Name benennt die Organisation, sagt nichts darüber aus, auf welchem Cluster sie läuft, und wird auch dann noch zutreffen, wenn die Hardware ausgetauscht wird. Vermeiden Sie Namen wie prod-k3s-2, die die heutigen Maschinen beschreiben.

Schlüsselverwahrung

Nexus bewahrt die Schlüssel jeder Organisation in einem eigenen Schlüsselspeicher innerhalb des Clusters auf. Sie betreiben ihn nicht im Tagesgeschäft, aber Sie entscheiden vor der Installation, wer ihn nach einem Neustart wiederherstellen kann. Dies ist die Entscheidung, die am teuersten wird, wenn Sie dabei einen Fehler machen.

Der Schlüsselspeicher besteht aus zwei OpenBao-Servern. Der Hauptserver, openbao, hält die Schlüssel und entsiegelt (unseals) sich selbst über einen zweiten, kleineren Server, openbao-unsealer. Der Unsealer ist mit dem Shamir-Schema versiegelt: fünf Fragmente (Shares), von denen beliebige drei ihn öffnen. Bei der Installation initialisiert ein Custody-Job beide Server innerhalb des Clusters. Im Arbeitsspeicher dieses Jobs verschlüsselt er die Fragmente des Unsealers und die Wiederherstellungsschlüssel des Schlüsselspeichers für jeden von Ihnen benannten Treuhänder (Custodian), speichert lediglich den Geheimtext (in den Secrets openbao-unseal-shares-encrypted und openbao-recovery-keys-encrypted) und widerruft beide Root-Token, bevor er beendet wird. Kein unverschlüsseltes Fragment gelangt jemals auf eine Festplatte oder in ein Protokoll.

Nach jedem Neustart des Knotens, auf dem der Unsealer läuft, startet der Unsealer im versiegelten Zustand. Der Schlüsselspeicher wartet auf ihn, und nichts, was einen Schlüssel benötigt, funktioniert, bis ein Treuhänder ihn entsiegelt. Dazu ist eine einzige Entschlüsselung mit dem eigenen privaten Schlüssel des Treuhänders erforderlich. Das Verfahren ist in Kapitel 2.15, Tag zwei: Betrieb von Nexus, beschrieben.

Erstellen eines Treuhänderschlüssels

Ein Treuhänder wird durch den öffentlichen Teil eines age-Schlüssels benannt, der als Empfänger (Recipient) bezeichnet wird. Jeder Treuhänder erstellt seinen eigenen Schlüssel auf seiner eigenen Maschine und gibt Ihnen nur den Empfänger:

age-keygen -o custodian.key

Die # public key:-Zeile der Datei ist der Empfänger, beginnend mit age1. Ein Treuhänder mit einem Mac kann den Schlüssel stattdessen in der Secure Enclave des Macs aufbewahren, sodass der private Teil den Chip niemals verlässt und bei jeder Verwendung ein Fingerabdruck angefordert wird:

age-plugin-se keygen --access-control=any-biometry -o custodian.key

Dieser Empfänger beginnt mit age1se1. Der Custody-Job verschlüsselt für fünf Empfängerformen: age1 (X25519), age1tag1 und age1tagpq1 (Tag), age1pq1 (Hybrid-Post-Quanten) und age1se1 (Secure Enclave). Er verweigert jede andere Plugin-Form wie etwa age1yubikey1; geben Sie diesen Schlüssel stattdessen in einer der akzeptierten Formen an.

Das Chart überprüft jeden Empfänger beim Rendern. Ein falsch eingegebener Empfänger besteht die bech32-Prüfsummenprüfung nicht und wird abgelehnt, sodass niemals etwas für einen Schlüssel versiegelt wird, den niemand besitzt. Wenn jemand versehentlich einen privaten Schlüssel in die Liste einfügt, lehnt das Chart ihn ab, ohne ihn im Klartext auszugeben. Der Beispielempfänger in den eigenen Werte-Dateien des Charts wird ebenfalls abgelehnt (KEYS_CUSTODIAN_EXAMPLE); niemand besitzt dessen privaten Teil.

Wie viele Treuhänder

Jedes Fragment wird für jeden Treuhänder verschlüsselt, sodass jeder einzelne Treuhänder die Entsiegelung alleine durchführen kann. Mehr Treuhänder bedeuten mehr Wege zur Wiederherstellung und mehr Personen, die jeweils eigenständig handeln können. Wir haben uns bei Harrow für drei entschieden: Aoife, mich und einen Secure-Enclave-Schlüssel auf einem Ersatz-Laptop, der im Tresor des Hafens liegt. Zwei ist das Mindeste, was ich akzeptieren würde. Einer allein ist eine einzelne Fehlerquelle (Single Point of Failure), die früher oder später im Urlaub sein wird, wenn ein Knoten neu startet.

Auswahl der Edition

edition ist community oder enterprise, und enterprise.enabled muss damit übereinstimmen. Das Chart verweigert abweichende Angaben und lehnt jede Edition ab, die nicht eine dieser beiden ist.

Die Edition entscheidet auch darüber, welche Images Sie installieren. Jedes Chart-Paket enthält für eine Edition eine Image-Sperrdatei (Images Lock), also die Liste aller Images nach Digest. Eine Community-Installation verwendet nur Community-Images. Eine Enterprise-Installation verwendet die Enterprise-Sperrdatei, die aus den Community-Images plus den Enterprise-Builds besteht, und ruft diese mit einem Pull-Token aus Ihrem Adverant-Konto ab. Kapitel 2.4, Ein Release beziehen und verifizieren, erläutert die Sperrdatei, und Kapitel 2.2, Editionen unter der Haube, erklärt, was jede Edition beinhaltet.

Sie müssen sich nicht endgültig festlegen. Eine Community-Installation lässt sich im laufenden Betrieb (in-place) auf Enterprise umstellen, wobei Benutzer, Dateien und Verlauf erhalten bleiben; Kapitel 2.7, Enterprise installieren und eine Lizenz anwenden, zeigt, wie das geht. Wir haben für das Pilotprojekt bei Harrow die Community-Edition genutzt und sind sechs Wochen später umgestiegen.

Die Lizenz ist niemals Teil dieses Plans. Sie ist kein Chart-Wert und keine eingebundene Datei: Sie importieren sie nach der Installation über die Konsole, nexusctl oder die API.

Auswahl der Bereitstellungsform

Form Wann sie passt Kapitel
Helm-Chart von registry.adverant.ai Ihr eigener Kubernetes-Cluster mit einer Verbindung zur Registry 2.6 und 2.7
nexusctl install Derselbe Cluster, wobei Preflight und die Signaturprüfung für Sie ausgeführt werden 2.6
nexusctl install --single-node Eine einzelne Maschine, auf der nexusctl auch den Cluster einrichtet 2.8
Das Installations-Disk-Image Ein Bare-Metal-Server oder eine virtuelle Maschine (VM), die Sie lieber nicht von Hand vorbereiten möchten 2.9
Das Offline-Bundle Überhaupt keine Verbindung nach außen; Images und Chart werden auf einem Datenträger bereitgestellt 2.10

Das Chart ist in jeder Form dasselbe. Was sich ändert, ist, wer den Cluster erstellt und woher die Images stammen.

Das Release beziehen
Das Release beziehen
Dies ist die Release-Seite im Adverant-Konto. Beachten Sie die klare Aussage darüber, was ein Alpha-Release verspricht, die Größe und Signatur neben jeder Datei sowie die Offline-Befehle zur Überprüfung eines Downloads.

Das Planungsarbeitsblatt

Dies ist das Blatt von Harrow, wie Aoife es abgezeichnet hat. Kopieren Sie die beiden linken Spalten und füllen Sie die rechte für Ihre eigene Installation aus.

Entscheidung Values-Schlüssel oder Befehl Harrow Port Authority
Kubernetes und Version (wird von Preflight ausgelesen) k3s v1.33.6+k3s1, drei Knoten
Kube-Kontext für die Installation --context harrow-prod
Namespace --namespace nexus
Edition edition, enterprise.enabled community für den Piloten, danach enterprise
Image-Registry global.imageRegistry registry.adverant.ai
Domain global.domain harrow.example
Konsolenadresse hosts.console console.harrow.example
API-Adresse hosts.api api.harrow.example
Anmeldeadresse hosts.auth auth.harrow.example
TLS am Netzwerkrand (Edge) tls.mode, tls.existingSecret existing, Secret harrow-public-tls von der internen CA von Harrow
IngressClass ingress.className traefik
Ingress-Namespace networkPolicy.ingressNamespace kube-system
StorageClass storage.className local-path
Datenspeicher dataTier.<store>.mode Alle in-cluster, Standardgrößen
Ausgehende Adressbereiche networkPolicy.externalEgressCIDRs Nur der Adressbereich des Mail-Relays
Installationsname (endgültig) keys.installationName harrow-port-authority
Treuhänder (faktisch endgültig) keys.custody.recipients Drei: Aoife Brennan, Tomás Reilly, der Tresor-Laptop (age1se1)
Grafikknoten (wird von Preflight ausgelesen) Keine für den vernetzten Piloten; gehostetes Modell mit dem eigenen Schlüssel von Harrow
Erster Administrator nexusctl claim-code --administrator aoife.brennan@harrow.example

Zwei Zeilen auf diesem Blatt lassen sich nicht rückgängig machen: der Installationsname und die Treuhänder in dem Sinne, dass bei einem Verlust aller Treuhänder auch der Schlüsselspeicher verloren ist. Lassen Sie diese beiden Punkte von einer Person abzeichnen, die die Befugnis hat, Ja zu sagen. Alles andere ist eine Änderung in den Values.

Gehen Sie nach Fertigstellung des Arbeitsblatts zu Kapitel 2.4, Ein Release beziehen und verifizieren, und laden Sie das Release herunter.