InloggenBriefing plannen

Hoofdstuk 2.3

Een installatie plannen

Wat een Kubernetes-installatie van Nexus nodig heeft voordat u een commando typt, hoe groot deze is, en de twee beslissingen die u niet kunt terugdraaien: de installatienaam en de sleutelbewaarders. Het sluit af met het ingevulde planningswerkblad van Harrow Port Authority.

Deze pagina is door AI vertaald vanuit het Engelse origineel. Als er iets onduidelijk is, geldt de Engelse pagina als referentie. Lees deze pagina in het Engels

16 minuten leestijd

Toen wij Nexus installeerden bij Harrow Port Authority, kostten de commando's een middag. De planning nam een week in beslag, en het grootste deel van die week ging op aan twee vragen die niets met Kubernetes te maken hebben: hoe we de installatie zouden noemen, en welke personen de herstelsleutels zouden beheren. Beide antwoorden zijn permanent. Al het andere in dit hoofdstuk kan later worden gewijzigd met een values-bestand en een helm upgrade.

Ik ben Tomás Reilly, de platformengineer bij Harrow. Harrow draait twee installaties. Dit hoofdstuk plant de verbonden installatie in ons bedrijfsnetwerk, waar we eerst een pilot met Community hebben uitgevoerd. Het operationele netwerk van de haven, dat geen verbinding met het internet heeft, kreeg later een eigen installatie; hoofdstuk 2.10, Air-gapped installatie, behandelt dit. Dit hoofdstuk is wat ik op de eerste ochtend had willen hebben: het cluster dat Nexus verwacht, de namen waarnaar het luistert, hoeveel het van uw nodes vraagt, en de beslissingen die u vóór de installatie met uw hoofd IT moet vastleggen. Het sluit af met het werkblad dat Aoife Brennan, ons hoofd IT, heeft ondertekend voordat we begonnen. Hoofdstuk 2.4, Een release ophalen en verifiëren, behandelt het downloaden en controleren van de release, en hoofdstuk 2.5, Preflight met nexusctl, controleert uw cluster aan de hand van alles wat hier staat.

Wat het cluster moet hebben

Nexus wordt geïnstalleerd als één Helm-chart, nexus, versie 1.0.0-alpha.1. De chart bevat de platformservices en hun datalaag, en weigert te installeren op een cluster waarin de onderstaande onderdelen ontbreken.

Vereiste Wat Nexus verwacht Waarom
Kubernetes 1.33 of nieuwer. Getest op k3s v1.33.6+k3s1 De kubeVersion van de chart is >=1.33.0-0, en helm install dwingt dit af
cert-manager v1.21.3, geïnstalleerd vóór Nexus De chart maakt zijn eigen lokale certificaatautoriteit (CA) en de certificaten die de services gebruiken om met elkaar te communiceren
Helm v4 (wij gebruikten v4.3.1) Helm 4 wacht standaard op de hook-Jobs van de chart, waarvan de installatie afhankelijk is
Een storage class Eén gemarkeerd als standaard, of één die u opgeeft in storage.className Elke datastore claimt een persistent volume
Een ingress class Eén gemarkeerd als standaard, of één die u opgeeft in ingress.className De drie openbare adressen zijn gewone networking.k8s.io/v1 Ingresses
Poorten 80 en 443 Open op de ingress-controller, als een LoadBalancer- of NodePort-Service Gebruikers bereiken Nexus via de ingress-controller
Architectuur linux/amd64- of linux/arm64-nodes Elke image is gebouwd voor beide

Twee zaken ontbreken met opzet in die tabel. Nexus heeft geen service mesh nodig: mutual TLS (mTLS, Transport Layer Security in beide richtingen) tussen services komt van de lokale CA van de chart via cert-manager. De chart heeft een sleutel istio.enabled die standaard op false staat, en u dient die zo te laten. Nexus heeft ook geen eigen admission policy engine nodig.

Op uw werkstation heeft u kubectl, Helm v4, cosign v3 voor het controleren van handtekeningen, age voor het aanmaken van beheerderssleutels, en nexusctl, de command-line-interface (CLI) voor de Nexus-operator, nodig. Hoofdstuk 2.4, Een release ophalen en verifiëren, vermeldt waar elke Nexus-download te vinden is.

Drie adressen

Elke installatie reageert op drie hostnamen. De chart noemt deze de installatie-identiteit, en elke service weigert te starten zonder deze namen.

Values-sleutel Naam bij Harrow Wat daar reageert
hosts.console console.harrow.example De console, de webapplicatie waarop mensen inloggen
hosts.api api.harrow.example De gateway, die de application programming interface (API) bedient en elk verzoek voor kunstmatige intelligentie (AI) routeert
hosts.auth auth.harrow.example De aanmeldservice, nexus-auth

global.domain bevat het domein waaronder de drie vallen, voor ons harrow.example. Elke host is een volledige naam op zichzelf en kan onder elk domein vallen dat u beheert. Wij hebben alle drie onder één domein gehouden, zodat één certificaat ze allemaal kon dekken.

Maak voor elk van de drie een Domain Name System (DNS)-record aan dat verwijst naar het adres van uw ingress-controller. Doe dit vóór de preflight. nexusctl preflight zoekt elke naam op vanaf uw werkstation en laat de installatie mislukken als een ervan geen record heeft, omdat een gebruiker een naam die niet wordt omgezet niet kan bereiken.

Aan de linkerkant drie DNS-namen: console.harrow.example, api.harrow.example en auth.harrow.example, elk met een pijl naar één kader met het label "ingress controller, ports 80 and 443". Vanuit dat kader leiden drie pijlen naar een groter kader met het label "namespace nexus": de console-pijl naar "nexus-alpha :3000", de api-pijl naar "nexus-gateway :9092" en de auth-pijl naar "nexus-auth :9101". Een onderbroken rand rond de namespace heeft het label "default deny; only the ingress namespace may reach these three".
Hoe de drie openbare namen de achterliggende services bereiken.

Kiezen waar TLS eindigt

De tls.mode van de chart bepaalt wie de certificaten voor de drie openbare adressen beheert. Er zijn drie keuzes, en u kunt hier later met een upgrade tussen wisselen.

tls.mode U levert Wat de chart doet
existing (de standaard) Een Kubernetes TLS Secret in de nexus-namespace, genoemd in tls.existingSecret Alle drie de Ingresses gebruiken dat ene Secret
cert-manager Een ClusterIssuer die u beheert, genoemd in tls.clusterIssuer Annoteert elke Ingress zodat cert-manager nexus-console-tls, nexus-api-tls en nexus-auth-tls uitgeeft
none Iets vóór het cluster dat TLS termineert, zoals uw eigen loadbalancer Genereert de Ingresses zonder TLS-sectie

Met existing bedient één certificaat alle drie de hosts, dus het moet alle drie vermelden, ofwel als drie Subject Alternative Names of als een wildcard voor uw domein. Wij gebruikten een certificaat van de interne CA van Harrow. Preflight leest het Secret voordat u installeert en waarschuwt wanneer het certificaat binnen 30 dagen verloopt.

Met cert-manager en een Automatic Certificate Management Environment (ACME)-issuer voegt de chart zelf geen doorverwijzing toe, zodat een /.well-known/acme-challenge/-verzoek op poort 80 de solver ongewijzigd bereikt. Voeg geen HTTP-naar-HTTPS-doorverwijzing toe op uw ingress-controller die vóór het challenge-pad wordt uitgevoerd; een certificaat dat niet kan worden verlengd, loopt weken later stilletjes vast.

Wat u ook kiest voor de openbare rand, de services binnen de namespace communiceren altijd via TLS van de lokale CA van de chart. Dat deel is geen keuze, en dat is de reden waarom cert-manager een vereiste is, zelfs wanneer tls.mode is ingesteld op existing of none.

Wat het cluster verlaat en wat niet

De chart genereert een default-deny netwerkbeleid voor de nexus-namespace. Daarna zijn alleen deze verkeersstromen toegestaan:

  • verkeer tussen Nexus-pods binnen de namespace;
  • DNS-zoekopdrachten naar de DNS-service van het cluster;
  • de Kubernetes API-server, voor de enkele services die workload-tokens controleren;
  • de namespace van de ingress-controller, naar de drie openbare Services;
  • alle Classless Inter-Domain Routing (CIDR)-bereiken die u opgeeft in networkPolicy.externalEgressCIDRs.

Die laatste lijst is standaard leeg. Als u een mailrelay of een modelserver buiten het cluster gaat gebruiken, plaatst u het betreffende bereik daar. Telemetrie staat uit en blijft uit: het schema accepteert alleen telemetry.enabled: false, en de eigen gebruiksrapportage van de datastores is eveneens uitgeschakeld.

De chart leest tijdens de installatie de adressen van de API-server uit het cluster. Als uw account de kubernetes-Endpoints in de default-namespace niet kan lezen, geef ze dan zelf op in networkPolicy.apiServerCIDRs, als /32-bereiken. proxy.trustedCIDRs benoemt het pod-netwerk waarop uw ingress-controller zich bevindt, zodat nexus-auth weet wiens X-Forwarded-For-header te vertrouwen is. De standaardwaarde, 10.42.0.0/16, is het pod-netwerk van k3s.

Dimensionering

De standaardaanvragen van de chart tellen op tot ongeveer 2,05 central processing unit (CPU)-cores en 6,7 GiB aan geheugen. Dat is wat de scheduler reserveert; de limieten liggen hoger, en de datastores groeien daarin mee naarmate u mensen en bestanden toevoegt.

Onderdeel Aangevraagde CPU Aangevraagd geheugen
Negen platformservices (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) 1,1 cores 2,6 GiB
De sleutelservice, nexus-keys 0,05 cores 64 MiB
PostgreSQL 0,25 cores 1 GiB
Neo4j 0,25 cores 2 GiB
Valkey, Qdrant en de objectstore samen 0,25 cores 640 MiB
De twee OpenBao-servers van de keystore 0,15 cores 384 MiB

De standaardvolumes tellen op tot 142 GiB:

Opslag Values-sleutel Standaardgrootte
PostgreSQL 16 met PostGIS 3 en pgvector 0.8 dataTier.postgres.size 50Gi
Objectstore (SeaweedFS) dataTier.objectStore.size 50Gi
Neo4j 5.26 Community Edition dataTier.neo4j.size 20Gi
Qdrant dataTier.qdrant.size 10Gi
Valkey dataTier.valkey.size 5Gi
De keystore en zijn unsealer keys.openbao.storage.keystore, keys.openbao.storage.unsealer 5Gi en 1Gi
Ontvangstbewijzen van de sleutelservice keys.receiptsStorage 1Gi

Reken voor een enkele node op 8 vCPU, 32 GiB aan random-access memory (RAM) en een solid-state drive (SSD) van 250 GB. Voor een evaluatie volstaan 4 vCPU, 16 GiB en 200 GB. De schijfimage van het installatieprogramma weigert een machine met minder dan 16 GiB geheugen (zie hoofdstuk 2.9, De schijfimage van het installatieprogramma), en ik zou dat overal als de ondergrens beschouwen.

Grafische nodes zijn optioneel. Zonder een node die een graphics processing unit (GPU) biedt, antwoordt de assistent via een gehost model, met behulp van de eigen sleutel van de organisatie. Preflight meldt dat als een waarschuwing, nooit als een fout. Hoofdstuk 2.14, AI-providers en -modellen, behandelt beide routes.

Elke store kan ook buiten het cluster draaien: stel dataTier.<store>.mode in op external en geef de host en een Secret op. Een externe PostgreSQL heeft een superuser-account nodig voor de bootstrap van de installatie en een certificaat dat Nexus kan verifiëren. Hoofdstuk 2.11, Variaties: externe stores, TLS en ingress, behandelt dit. Als u ze in het cluster houdt, plaats ze dan op een storage class met echte fysieke schijven erachter. De database is het onderdeel dat u het meest zult missen als de lokale schijf van een node uitvalt.

De installatienaam is permanent

keys.installationName is hoe operators deze installatie noemen. Het moet overeenkomen met ^[a-z][a-z0-9-]{0,62}$: een kleine letter, gevolgd door maximaal 62 kleine letters, cijfers of koppeltekens.

De eerste keer dat de keystore start, maakt deze de identiteit van de installatie aan onder deze naam, en die identiteit ligt voorgoed vast. Een licentie van Adverant wordt uitgegeven voor die identiteit, waardoor een licentie die voor de ene installatie is gemaakt, op een andere wordt geweigerd met LICENCE_OTHER_INSTALLATION. Hernoemen zou een nieuwe installatie, een nieuwe identiteit en nieuwe licenties betekenen.

De chart heeft geen standaardwaarde voor de naam. Hij weigert een installatie zonder naam (INSTALLATION_NAME_MISSING) en weigert de voorbeeldnaam uit zijn eigen voorbeeld-values-bestanden (INSTALLATION_NAME_EXAMPLE). Preflight meldt beide voordat u zover bent.

Bij Harrow hebben we hier langer over gedaan dan ik graag toegeef. We kwamen uit op harrow-port-authority: het noemt de organisatie, zegt niets over op welk cluster het draait, en zal nog steeds kloppen wanneer de hardware wordt vervangen. Vermijd namen zoals prod-k3s-2 die de machines van vandaag beschrijven.

Sleutelbewaring

Nexus bewaart de sleutels van elke organisatie in zijn eigen keystore, binnen het cluster. U beheert deze niet van dag tot dag, maar u beslist wel vóór de installatie wie hem na een herstart weer online kan brengen. Dit is de beslissing die het meeste kost als u het verkeerd aanpakt.

De keystore bestaat uit twee OpenBao-servers. De belangrijkste, openbao, bewaart de sleutels en ontgrendelt (unsealt) zichzelf via een tweede, kleinere server, openbao-unsealer. De unsealer is verzegeld met het schema van Shamir: vijf delen (shares), waarvan er willekeurig drie nodig zijn om hem te openen. Wanneer u installeert, initialiseert een custody-Job beide servers binnen het cluster. In het geheugen van die Job versleutelt deze de delen van de unsealer en de herstelsleutels van de keystore voor elke sleutelbeheerder (custodian) die u opgeeft, slaat alleen de cijfertekst op (in de Secrets openbao-unseal-shares-encrypted en openbao-recovery-keys-encrypted), en trekt beide root-tokens in voordat hij klaar is. Geen enkel onversleuteld deel bereikt ooit een schijf of een logbestand.

Na elke herstart van de node van de unsealer, start de unsealer in verzegelde toestand. De keystore wacht erop, en niets dat een sleutel nodig heeft werkt totdat een sleutelbeheerder hem ontgrendelt. Dat vereist één ontsleuteling met de eigen privésleutel van de sleutelbeheerder. De procedure staat in hoofdstuk 2.15, Dag twee: Nexus beheren.

Een beheerderssleutel aanmaken

Een sleutelbeheerder wordt aangeduid met de publieke helft van een age-sleutel, de zogeheten ontvanger (recipient). Elke sleutelbeheerder maakt zijn eigen sleutel aan op zijn eigen machine en geeft u alleen de ontvanger:

age-keygen -o custodian.key

De regel # public key: in het bestand is de ontvanger, beginnend met age1. Een sleutelbeheerder met een Mac kan de sleutel in plaats daarvan in de Secure Enclave van de Mac bewaren, zodat de privéhelft de chip nooit verlaat en bij elk gebruik om een vingerafdruk wordt gevraagd:

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

Die ontvanger begint met age1se1. De custody-Job versleutelt naar vijf vormen van ontvangers: age1 (X25519), age1tag1 en age1tagpq1 (tag), age1pq1 (hybride post-kwantum), en age1se1 (Secure Enclave). Hij weigert elke andere plugin-vorm, zoals age1yubikey1; geef die sleutel in plaats daarvan op in een van de geaccepteerde vormen.

De chart controleert elke ontvanger bij het genereren. Een verkeerd getypte ontvanger slaagt niet voor de bech32-checksum en wordt geweigerd, zodat er nooit iets wordt verzegeld met een sleutel die niemand bezit. Als iemand per ongeluk een privésleutel in de lijst plakt, weigert de chart deze zonder hem terug te tonen. De voorbeeldontvanger in de eigen values-bestanden van de chart wordt eveneens geweigerd (KEYS_CUSTODIAN_EXAMPLE); niemand bezit de privéhelft daarvan.

Hoeveel sleutelbeheerders

Elk deel wordt versleuteld voor elke sleutelbeheerder, zodat elke afzonderlijke sleutelbeheerder alleen kan ontgrendelen. Meer sleutelbeheerders betekent meer manieren om te herstellen en meer mensen die elk zelfstandig kunnen handelen. Bij Harrow kozen we er drie: Aoife, ikzelf, en een Secure Enclave-sleutel op een reservelaptop die in de kluis van de haven ligt. Twee is het minimum dat ik zou accepteren. Eén is een single point of failure die vroeg of laat op vakantie zal zijn wanneer een node herstart.

De editie kiezen

edition is community of enterprise, en enterprise.enabled moet daarmee overeenkomen. De chart weigert een niet-overeenkomende waarde, en weigert elke editie die niet een van deze twee is.

De editie bepaalt ook welke images u installeert. Elk chart-pakket bevat een images-lock, de lijst van elke image op digest, voor één editie. Een Community-installatie gebruikt alleen Community-images. Een Enterprise-installatie gebruikt de Enterprise-lock, die bestaat uit de Community-images plus de Enterprise-builds, en haalt deze op met een pull-token uit uw Adverant-account. Hoofdstuk 2.4, Een release ophalen en verifiëren, legt de lock uit, en hoofdstuk 2.2, Edities onder de motorkap, legt uit wat elke editie bevat.

U hoeft niet voorgoed te beslissen. Een Community-installatie kan ter plaatse (in place) worden omgezet naar Enterprise, met behoud van gebruikers, bestanden en geschiedenis; hoofdstuk 2.7, Enterprise installeren en een licentie toepassen, laat zien hoe. Wij draaiden Community voor de pilot bij Harrow en stapten zes weken later over.

De licentie maakt nooit deel uit van dit plan. Het is geen chart-waarde of een gekoppeld bestand: u importeert deze na de installatie, via de console, nexusctl of de API.

De leveringsvorm kiezen

Vorm Wanneer dit past Hoofdstuk
Helm-chart van registry.adverant.ai Uw eigen Kubernetes-cluster, met een route naar de registry 2.6 en 2.7
nexusctl install Hetzelfde cluster, waarbij de preflight en de handtekeningcontrole voor u worden uitgevoerd 2.6
nexusctl install --single-node Eén machine, waarop nexusctl ook het cluster opzet 2.8
De schijfimage van het installatieprogramma Een fysieke server of virtuele machine (VM) die u liever niet handmatig voorbereidt 2.9
De offline bundel Helemaal geen uitgaande route; images en chart worden op een schijf aangeleverd 2.10

De chart is in elke vorm hetzelfde. Wat verandert, is wie het cluster aanmaakt en waar de images vandaan komen.

De release ophalen
De release ophalen
Dit is de releasepagina in het Adverant-account. Let op de heldere verklaring van wat een alpha-release belooft, de grootte en handtekening naast elk bestand, en de offline commando's voor het controleren van een download.

Het planningswerkblad

Dit is die van Harrow, zoals Aoife hem heeft goedgekeurd. Kopieer de linker twee kolommen en vul de rechterkolom in voor uw eigen installatie.

Beslissing Values-sleutel of commando Harrow Port Authority
Kubernetes en versie (preflight leest dit uit) k3s v1.33.6+k3s1, drie nodes
Kube-context voor de installatie --context harrow-prod
Namespace --namespace nexus
Editie edition, enterprise.enabled community voor de pilot, daarna enterprise
Image-registry global.imageRegistry registry.adverant.ai
Domein global.domain harrow.example
Console-adres hosts.console console.harrow.example
API-adres hosts.api api.harrow.example
Aanmeldadres hosts.auth auth.harrow.example
TLS aan de rand tls.mode, tls.existingSecret existing, Secret harrow-public-tls van de interne CA van Harrow
Ingress class ingress.className traefik
Ingress-namespace networkPolicy.ingressNamespace kube-system
Storage class storage.className local-path
Datastores dataTier.<store>.mode Alle in-cluster, standaardgroottes
Uitgaande bereiken networkPolicy.externalEgressCIDRs Alleen het bereik van de mailrelay
Installatienaam (permanent) keys.installationName harrow-port-authority
Sleutelbeheerders (in de praktijk permanent) keys.custody.recipients Drie: Aoife Brennan, Tomás Reilly, de laptop in de kluis (age1se1)
Grafische nodes (preflight leest dit uit) Geen voor de verbonden pilot; gehost model met de eigen sleutel van Harrow
Eerste beheerder nexusctl claim-code --administrator aoife.brennan@harrow.example

Twee rijen op dat blad kunnen niet ongedaan worden gemaakt: de installatienaam, en de sleutelbeheerders in die zin dat het verlies van allemaal het verlies van de keystore betekent. Laat die twee ondertekenen door iemand met de bevoegdheid om ja te zeggen. Al het andere is een wijziging in de values.

Nu het werkblad klaar is, gaat u naar hoofdstuk 2.4, Een release ophalen en verifiëren, en haalt u de release op.