Log indBook en briefing

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

16 minutters læsetid

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.

Til venstre tre DNS-navne: console.harrow.example, api.harrow.example og auth.harrow.example, hver med en pil ind i én boks med teksten "ingress controller, ports 80 and 443". Fra den boks fører tre pile ind i en større boks med teksten "namespace nexus": console-pilen til "nexus-alpha :3000", api-pilen til "nexus-gateway :9092" og auth-pilen til "nexus-auth :9101". En stiplet ramme omkring namespacet har teksten "default deny; only the ingress namespace may reach these three".
Sådan når de tre offentlige navne tjenesterne bag dem.

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.key

Filens # 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.key

Den 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.

Hent udgivelsen
Hent udgivelsen
Dette er udgivelsessiden på Adverant-kontoen. Bemærk den klare erklæring om, hvad en alfa-udgivelse lover, størrelsen og signaturen ved siden af hver fil samt offline-kommandoerne til kontrol af en download.

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.