Version 1.0.0-alpha.1seneste
Kapitel 2.3
Planlægning af en installation
Hvad en Kubernetes-installation af Nexus kræver, før du skriver en kommando, hvor stor den er, og de to beslutninger, du ikke kan gøre om: installationsnavnet og nøgleforvalterne. Det slutter med Harrow Port Authoritys udfyldte planlægningsark.
Denne side er oversat af AI fra den engelske original. Hvis noget er uklart, er den engelske side gældende. Læs denne side på engelsk

Da vi installerede Nexus hos Harrow Port Authority, tog kommandoerne en eftermiddag. Planlægningen tog en uge, og det meste af den uge gik med to spørgsmål, der ikke har noget med Kubernetes at gøre: hvad vi skulle kalde installationen, og hvilke personer der skulle opbevare dens gendannelsesnøgler. Begge svar er permanente. Alt andet i dette kapitel kan ændres senere med en værdifil og en helm upgrade.
Jeg hedder Tomás Reilly, platformsingeniør hos Harrow. Harrow kører to installationer. Dette kapitel planlægger den tilsluttede installation i vores virksomhedsnetværk, hvor vi først kørte et pilotprojekt med Community. Havnens driftsnetværk, som ikke har nogen rute til internettet, fik sin egen installation senere; kapitel 2.10, Air-gapped installation, dækker denne. Dette kapitel er, hvad jeg ville ønske, jeg havde haft den første morgen: den klynge, som Nexus forventer, de navne, den svarer på, hvor meget den kræver af jeres noder, og de beslutninger, der skal træffes sammen med jeres IT-chef inden installationen. Det slutter med det arbejdsark, som Aoife Brennan, vores IT-chef, godkendte, før vi gik i gang. Kapitel 2.4, Hentning og verificering af en udgivelse, dækker hentning og kontrol af udgivelsen, og kapitel 2.5, Forhåndskontrol med nexusctl, kontrollerer jeres klynge op imod alt her.
Hvad klyngen skal have
Nexus installeres som ét Helm-chart, nexus, version 1.0.0-alpha.1. Chartet indeholder platformstjenesterne og deres datalag, og det nægter at installere på en klynge, der mangler nedenstående dele.
| Krav | Hvad Nexus forventer | Hvorfor |
|---|---|---|
| Kubernetes | 1.33 eller nyere. Testet på k3s v1.33.6+k3s1 |
Chartets kubeVersion er >=1.33.0-0, og helm install håndhæver det |
| cert-manager | v1.21.3, installeret før Nexus |
Chartet opretter sin egen lokale certifikatautoritet (CA) og de certifikater, som dets tjenester bruger til at tale med hinanden |
| Helm | v4 (vi brugte v4.3.1) | Helm 4 venter som standard på chartets hook-Jobs, hvilket installationen afhænger af |
| En storage class | Én markeret som standard, eller én I angiver i storage.className |
Hvert datalager gør krav på en persistent diskenhed |
| En ingress class | Én markeret som standard, eller én I angiver i ingress.className |
De tre offentlige adresser er almindelige networking.k8s.io/v1 Ingress-ressourcer |
| Port 80 og 443 | Åbne på ingress-controlleren som en LoadBalancer- eller NodePort-Service | Brugere tilgår Nexus gennem ingress-controlleren |
| Arkitektur | linux/amd64- eller linux/arm64-noder |
Hvert image er bygget til begge |
To ting er med vilje udeladt fra den tabel. Nexus behøver intet service mesh: gensidig TLS (mTLS, Transport Layer Security i begge retninger) mellem tjenester kommer fra chartets lokale CA via cert-manager. Chartet har en istio.enabled-nøgle, der som standard er sat til false, og I bør lade den blive der. Nexus behøver heller ingen egen admission policy engine.
På jeres arbejdsstation får I brug for kubectl, Helm v4, cosign v3 til kontrol af signaturer, age til oprettelse af nøgleforvalternøgler samt nexusctl, kommandolinjegrænsefladen (CLI) for Nexus-operatøren. Kapitel 2.4, Hentning og verificering af en udgivelse, beskriver, hvor hver Nexus-download findes.
Tre adresser
Hver installation svarer på tre værtsnavne. Chartet kalder dem installationsidentiteten, og enhver tjeneste nægter at starte uden dem.
| Værdinøgle | Harrows navn | Hvad der svarer der |
|---|---|---|
hosts.console |
console.harrow.example |
Konsollen, den webapplikation brugerne logger ind på |
hosts.api |
api.harrow.example |
Gatewayen, som betjener applikationsprogrammeringsgrænsefladen (API) og ruter enhver forespørgsel til kunstig intelligens (AI) |
hosts.auth |
auth.harrow.example |
Login-tjenesten, nexus-auth |
global.domain indeholder det domæne, som de tre ligger under, harrow.example for os. Hver vært er et fuldt navn i sig selv og kan ligge under ethvert domæne, I kontrollerer. Vi beholdt alle tre under ét domæne, fordi ét certifikat derved kunne dække dem.
Opret en Domain Name System (DNS)-post for hver af de tre, som peger på jeres ingress-controllers adresse. Gør det før forhåndskontrollen. nexusctl preflight slår hvert navn op fra jeres arbejdsstation og lader installationen fejle, hvis et af dem ikke har nogen post, fordi en bruger ikke kan nå et navn, der ikke kan slås op.
Valg af hvor TLS termineres
Chartets tls.mode afgør, hvem der opbevarer certifikaterne for de tre offentlige adresser. Der er tre valgmuligheder, og I kan skifte mellem dem senere med en opgradering.
tls.mode |
I leverer | Hvad chartet gør |
|---|---|---|
existing (standarden) |
En Kubernetes TLS Secret i nexus-namespacet, navngivet i tls.existingSecret |
Alle tre Ingress-ressourcer bruger denne ene Secret |
cert-manager |
En ClusterIssuer, som I kører, navngivet i tls.clusterIssuer |
Annoterer hver Ingress, så cert-manager udsteder nexus-console-tls, nexus-api-tls og nexus-auth-tls |
none |
Noget foran klyngen, der terminerer TLS, såsom jeres egen load balancer | Genererer Ingress-ressourcerne uden nogen TLS-sektion |
Med existing betjener ét certifikat alle tre værter, så det skal navngive alle tre, enten som tre alternative emnenavne (SAN) eller som et wildcard for jeres domæne. Vi brugte et certifikat fra Harrows interne CA. Forhåndskontrollen læser den pågældende Secret, før I installerer, og advarer, når dens certifikat udløber inden for 30 dage.
Med cert-manager og en Automatic Certificate Management Environment (ACME)-udsteder tilføjer chartet ingen egen omdirigering, så en /.well-known/acme-challenge/-forespørgsel på port 80 når solveren urørt. Tilføj ikke en HTTP-til-HTTPS-omdirigering ved jeres ingress-controller, der kører før challenge-stien; et certifikat, der ikke kan fornyes, fejler i det skjulte uger senere.
Uanset hvad I vælger for den offentlige kant, taler tjenesterne inde i namespacet altid over TLS fra chartets lokale CA. Den del er ikke et valg, og det er grunden til, at cert-manager er en forudsætning, selv når tls.mode er existing eller none.
Hvad der forlader klyngen, og hvad der ikke gør
Chartet genererer en default-deny-netværkspolitik for nexus-namespacet. Derefter er kun disse trafikstrømme tilladt:
- trafik mellem Nexus-pods inde i namespacet;
- DNS-opslag til klyngens DNS-tjeneste;
- Kubernetes API-serveren, for de få tjenester, der kontrollerer workload-tokens;
- ingress-controllerens namespace, til de tre offentlige Services;
- eventuelle Classless Inter-Domain Routing (CIDR)-intervaller, som I angiver i
networkPolicy.externalEgressCIDRs.
Den sidste liste er som standard tom. Hvis I skal bruge et mail-relay eller en modelserver uden for klyngen, skal dens interval angives der. Telemetri er slået fra og forbliver slået fra: skemaet accepterer kun telemetry.enabled: false, og datalagrenes egen brugsrapportering er også slået fra.
Chartet læser API-serverens adresser fra klyngen, når I installerer. Hvis jeres konto ikke kan læse kubernetes Endpoints i default-namespacet, skal I selv angive dem i networkPolicy.apiServerCIDRs som /32-intervaller. proxy.trustedCIDRs angiver det pod-netværk, jeres ingress-controller befinder sig på, så nexus-auth ved, hvis X-Forwarded-For-header den skal stole på. Standarden, 10.42.0.0/16, er k3s' pod-netværk.
Dimensionering
Chartets standardforespørgsler løber op i omkring 2,05 central processing unit (CPU)-kerner og 6,7 GiB hukommelse. Det er, hvad scheduleren reserverer; grænserne er højere, og datalagrene vokser ind i dem, efterhånden som I tilføjer brugere og filer.
| Del | Anmodet CPU | Anmodet hukommelse |
|---|---|---|
| Ni platformstjenester (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) | 1,1 kerner | 2,6 GiB |
Nøgletjenesten, nexus-keys |
0,05 kerner | 64 MiB |
| PostgreSQL | 0,25 kerner | 1 GiB |
| Neo4j | 0,25 kerner | 2 GiB |
| Valkey, Qdrant og objektlageret tilsammen | 0,25 kerner | 640 MiB |
| Nøglelagerets to OpenBao-servere | 0,15 kerner | 384 MiB |
Standarddiskenhederne løber op i 142 GiB:
| Datalager | Værdinøgle | Standardstørrelse |
|---|---|---|
| PostgreSQL 16 med PostGIS 3 og pgvector 0.8 | dataTier.postgres.size |
50Gi |
| Objektlager (SeaweedFS) | dataTier.objectStore.size |
50Gi |
| Neo4j 5.26 Community Edition | dataTier.neo4j.size |
20Gi |
| Qdrant | dataTier.qdrant.size |
10Gi |
| Valkey | dataTier.valkey.size |
5Gi |
| Nøglelageret og dets oplåsningsserver (unsealer) | keys.openbao.storage.keystore, keys.openbao.storage.unsealer |
5Gi og 1Gi |
| Kvitteringer for nøgletjeneste | keys.receiptsStorage |
1Gi |
For en enkelt node bør I planlægge med 8 vCPU, 32 GiB random-access memory (RAM) og et 250 GB solid-state drive (SSD). Til en evaluering rækker 4 vCPU, 16 GiB og 200 GB. Installationsdisk-imaget afviser en maskine med mindre end 16 GiB hukommelse (se kapitel 2.9, Installationsdisk-imaget), og jeg ville betragte det som minimumsgrænsen overalt.
Grafiknoder er valgfrie. Uden en node, der tilbyder en graphics processing unit (GPU), svarer assistenten gennem en hostet model ved hjælp af organisationens egen nøgle. Forhåndskontrollen rapporterer dette som en advarsel, aldrig en fejl. Kapitel 2.14, AI-udbydere og -modeller, dækker begge veje.
Hvert lager kan også køre uden for klyngen: sæt dataTier.<store>.mode til external, og angiv dets vært og en Secret. En ekstern PostgreSQL kræver en superbrugerkonto til installationens bootstrap samt et certifikat, som Nexus kan verificere. Kapitel 2.11, Variationer: eksterne lagre, TLS og ingress, dækker dette. Hvis I beholder dem i klyngen, skal I placere dem på en storage class med rigtige diske bagved. Databasen er den del, I vil savne mest, hvis en nodes lokale disk står af.
Installationsnavnet er permanent
keys.installationName er det, operatører kalder denne installation. Det skal matche ^[a-z][a-z0-9-]{0,62}$: et lille bogstav efterfulgt af op til 62 små bogstaver, cifre eller bindestreger.
Første gang nøglelageret starter, opretter det installationens identitet under dette navn, og den identitet er fastlåst for altid. En licens fra Adverant udstedes til den identitet, så en licens lavet til én installation afvises på en anden med LICENCE_OTHER_INSTALLATION. En omdøbning ville betyde en ny installation, en ny identitet og nye licenser.
Chartet har ingen standardværdi for navnet. Det afviser en installation uden navn (INSTALLATION_NAME_MISSING) og afviser eksempelnavnet fra sine egne eksempelværdifiler (INSTALLATION_NAME_EXAMPLE). Forhåndskontrollen rapporterer begge dele, før I når så langt.
Hos Harrow brugte vi længere tid på dette, end jeg bryder mig om at indrømme. Vi endte på harrow-port-authority: det navngiver organisationen, siger intet om, hvilken klynge det kører på, og vil stadig være gældende, når hardwaren udskiftes. Undgå navne som prod-k3s-2, der beskriver nutidens maskiner.
Nøgleforvaltning
Nexus opbevarer hver organisations nøgler i sit eget nøglelager inde i klyngen. I driver det ikke til daglig, men I beslutter før installationen, hvem der kan bringe det tilbage efter en genstart. Dette er den beslutning, der koster dyrest, hvis I tager fejl.
Nøglelageret består af to OpenBao-servere. Den primære, openbao, opbevarer nøglerne og låser sig selv op gennem en anden, mindre server, openbao-unsealer. Oplåsningsserveren (unsealeren) er forseglet med Shamirs ordning: fem andele, hvoraf enhver kombination af tre åbner den. Når I installerer, initialiserer et custody-Job begge servere inde i klyngen. I dette Jobs hukommelse krypterer det oplåsningsserverens andele og nøglelagerets gendannelsesnøgler til hver nøgleforvalter, I angiver, gemmer kun chifferteksten (i Secrets openbao-unseal-shares-encrypted og openbao-recovery-keys-encrypted) og tilbagekalder begge root-tokens, før det afslutter. Ingen ukrypteret andel når nogensinde en disk eller en log.
Efter enhver genstart af oplåsningsserverens node starter oplåsningsserveren i forseglet tilstand. Nøglelageret venter på den, og intet, der kræver en nøgle, fungerer, før en nøgleforvalter låser den op. Det kræver én dekryptering med nøgleforvalterens egen private nøgle. Proceduren findes i kapitel 2.15, Dag to: drift af Nexus.
Oprettelse af en nøgleforvalternøgle
En nøgleforvalter angives ved den offentlige halvdel af en age-nøgle, kaldet dens modtager (recipient). Hver nøgleforvalter opretter sin egen nøgle på sin egen maskine og giver jer kun modtageren:
age-keygen -o custodian.keyFilens # public key:-linje er modtageren, som begynder med age1. En nøgleforvalter med en Mac kan i stedet opbevare nøglen i Mac'ens Secure Enclave, så den private halvdel aldrig forlader chippen, og hver brug beder om et fingeraftryk:
age-plugin-se keygen --access-control=any-biometry -o custodian.keyDen modtager begynder med age1se1. Custody-Jobbet krypterer til fem former for modtagere: age1 (X25519), age1tag1 og age1tagpq1 (tag), age1pq1 (hybrid post-kvante) samt age1se1 (Secure Enclave). Det afviser enhver anden plugin-form, såsom age1yubikey1; angiv i stedet den nøgle i en af de accepterede former.
Chartet kontrollerer hver modtager, når det genereres. En forkert indtastet modtager fejler sin bech32-kontrolsum og afvises, så intet nogensinde forsegles til en nøgle, som ingen har. Hvis nogen ved en fejl indsætter en privat nøgle på listen, afviser chartet den uden at udskrive den igen. Eksempelmodtageren i chartets egne værdifiler afvises også (KEYS_CUSTODIAN_EXAMPLE); ingen har dens private halvdel.
Hvor mange nøgleforvaltere
Hver andel krypteres til hver nøgleforvalter, så enhver enkelt nøgleforvalter kan låse op alene. Flere nøgleforvaltere betyder flere måder at gendanne på og flere personer, der hver især kan handle alene. Vi valgte tre hos Harrow: Aoife, mig og en Secure Enclave-nøgle på en ekstra bærbar computer, der ligger i havnens pengeskab. To er det mindste, jeg ville acceptere. Én er et single point of failure, som før eller siden vil være på ferie, når en node genstarter.
Valg af udgave
edition er community eller enterprise, og enterprise.enabled skal stemme overens med det. Chartet afviser en uoverensstemmelse, og det afviser enhver udgave, der ikke er en af de to.
Udgaven afgør også, hvilke images I installerer. Hver chart-pakke indeholder en images-lås, listen over hvert image efter digest, for én udgave. En Community-installation tager kun Community-images. En Enterprise-installation tager Enterprise-låsen, som er Community-images plus Enterprise-builds, og henter dem med et pull-token fra jeres Adverant-konto. Kapitel 2.4, Hentning og verificering af en udgivelse, forklarer låsen, og kapitel 2.2, Udgaverne under motorhjelmen, forklarer, hvad hver udgave indeholder.
I behøver ikke at beslutte jer endeligt. En Community-installation kan opgraderes til Enterprise på stedet, mens den beholder sine brugere, filer og historik; kapitel 2.7, Installation af Enterprise og anvendelse af en licens, viser hvordan. Vi kørte Community til pilotprojektet hos Harrow og skiftede seks uger senere.
Licensen er aldrig en del af denne plan. Den er ikke en chart-værdi eller en monteret fil: I importerer den efter installationen gennem konsollen, nexusctl eller API'et.
Valg af leveringsform
| Form | Hvornår den passer | Kapitel |
|---|---|---|
Helm-chart fra registry.adverant.ai |
Jeres egen Kubernetes-klynge, med en rute til registret | 2.6 og 2.7 |
nexusctl install |
Den samme klynge, hvor forhåndskontrollen og signaturkontrollen køres for jer | 2.6 |
nexusctl install --single-node |
Én maskine, hvor nexusctl også opsætter klyngen |
2.8 |
| Installationsdiskafbildningen | En rå server eller virtuel maskine (VM), som I helst ikke vil klargøre manuelt | 2.9 |
| Offline-pakken | Slet ingen rute ud; images og chart leveres på en disk | 2.10 |
Chartet er det samme i hver form. Det, der ændrer sig, er, hvem der opretter klyngen, og hvor images kommer fra.
Planlægningsarket
Dette er Harrows, som Aoife godkendte det. Kopiér de to venstre kolonner, og udfyld den højre for jeres egen installation.
| Beslutning | Værdinøgle eller kommando | Harrow Port Authority |
|---|---|---|
| Kubernetes og version | (forhåndskontrollen læser det) | k3s v1.33.6+k3s1, tre noder |
| Kube-kontekst for installationen | --context |
harrow-prod |
| Namespace | --namespace |
nexus |
| Udgave | edition, enterprise.enabled |
community til pilotprojektet, derefter enterprise |
| Image-register | global.imageRegistry |
registry.adverant.ai |
| Domæne | global.domain |
harrow.example |
| Konsoladresse | hosts.console |
console.harrow.example |
| API-adresse | hosts.api |
api.harrow.example |
| Login-adresse | hosts.auth |
auth.harrow.example |
| TLS ved kanten | tls.mode, tls.existingSecret |
existing, Secret harrow-public-tls fra Harrows interne CA |
| Ingress class | ingress.className |
traefik |
| Ingress-namespace | networkPolicy.ingressNamespace |
kube-system |
| Storage class | storage.className |
local-path |
| Datalagre | dataTier.<store>.mode |
Alle in-cluster, standardstørrelser |
| Udgående intervaller | networkPolicy.externalEgressCIDRs |
Kun mail-relayets interval |
| Installationsnavn (permanent) | keys.installationName |
harrow-port-authority |
| Nøgleforvaltere (i praksis permanente) | keys.custody.recipients |
Tre: Aoife Brennan, Tomás Reilly, den bærbare computer i pengeskabet (age1se1) |
| Grafiknoder | (forhåndskontrollen læser det) | Ingen til det tilsluttede pilotprojekt; hostet model med Harrows egen nøgle |
| Første administrator | nexusctl claim-code --administrator |
aoife.brennan@harrow.example |
To rækker på det ark kan ikke gøres om: installationsnavnet samt nøgleforvalterne i den forstand, at hvis man mister dem alle, mister man nøglelageret. Få disse to godkendt af en person med bemyndigelse til at sige ja. Alt andet er en ændring af værdier.
Når arbejdsarket er færdigt, kan I gå til kapitel 2.4, Hentning og verificering af en udgivelse, og hente udgivelsen.
