Logg innBestill en gjennomgang

Kapittel 2.3

Planlegge en installasjon

Hva en Kubernetes-installasjon av Nexus krever før du skriver en kommando, hvor stor den er, og de to beslutningene du ikke kan omgjøre: installasjonsnavnet og nøkkelforvalterne. Det avsluttes med det utfylte planleggingsskjemaet til Harrow Port Authority.

Denne siden er oversatt med KI fra den engelske originalen. Hvis noe er uklart, er den engelske siden referansen. Les denne siden på engelsk

16 minutter å lese

Da vi installerte Nexus hos Harrow Port Authority, tok kommandoene en ettermiddag. Planleggingen tok en uke, og mesteparten av den uken gikk med til to spørsmål som ikke har noe med Kubernetes å gjøre: hva vi skulle kalle installasjonen, og hvilke personer som skulle oppbevare gjenopprettingsnøklene. Begge svarene er permanente. Alt annet i dette kapittelet kan endres senere med en verdifil og en helm upgrade.

Jeg er Tomás Reilly, plattformingeniør hos Harrow. Harrow kjører to installasjoner. Dette kapittelet planlegger den tilkoblede installasjonen i bedriftsnettverket vårt, der vi først kjørte en pilot med Community. Havnens driftsnettverk, som ikke har noen rute til internett, fikk sin egen installasjon senere; kapittel 2.10, Luftgapet installasjon, dekker denne. Dette kapittelet er det jeg skulle ønske jeg hadde den første morgenen: klyngen Nexus forventer, navnene den svarer på, hvor mye den krever av nodene dine, og beslutningene du må avklare med IT-sjefen før installasjonen. Det avsluttes med arbeidsarket som Aoife Brennan, IT-sjefen vår, godkjente før vi startet. Kapittel 2.4, Hente og verifisere en utgivelse, dekker nedlasting og kontroll av utgivelsen, og kapittel 2.5, Forhåndskontroll med nexusctl, sjekker klyngen din mot alt som står her.

Hva klyngen må ha

Nexus installeres som ett Helm-chart, nexus, versjon 1.0.0-alpha.1. Chartet inneholder plattformtjenestene og datalaget deres, og det nekter å la seg installere på en klynge som mangler delene nedenfor.

Krav Hva 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åndhever dette
cert-manager v1.21.3, installert før Nexus Chartet oppretter sin egen lokale sertifikatautoritet (CA) og sertifikatene som tjenestene bruker for å snakke med hverandre
Helm v4 (vi brukte v4.3.1) Helm 4 venter som standard på chartets hook-Jobs, noe installasjonen er avhengig av
En lagringsklasse Én som er merket som standard, eller én du oppgir i storage.className Hvert datalager gjør krav på et persistent volum
En ingress-klasse Én som er merket som standard, eller én du oppgir i ingress.className De tre offentlige adressene er vanlige networking.k8s.io/v1-Ingresser
Port 80 og 443 Åpne på ingress-kontrolleren, som en LoadBalancer- eller NodePort-Service Brukere når Nexus gjennom ingress-kontrolleren
Arkitektur linux/amd64- eller linux/arm64-noder Hvert avbildningsbilde er bygget for begge

To ting er utelatt fra den tabellen med hensikt. Nexus trenger ingen service mesh: gjensidig TLS (mTLS, Transport Layer Security i begge retninger) mellom tjenester kommer fra chartets lokale CA gjennom cert-manager. Chartet har en istio.enabled-nøkkel som har standardverdien false, og du bør la den stå slik. Nexus trenger heller ingen egen motor for tilgangspolicyer (admission policy engine).

På arbeidsstasjonen din trenger du kubectl, Helm v4, cosign v3 for å sjekke signaturer, age for å lage forvalternøkler, og nexusctl, kommandolinjegrensesnittet (CLI) for Nexus-operatøren. Kapittel 2.4, Hente og verifisere en utgivelse, forteller hvor hver Nexus-nedlasting befinner seg.

Tre adresser

Hver installasjon svarer på tre vertsnavn. Chartet kaller dem installasjonsidentiteten, og hver tjeneste nekter å starte uten dem.

Verdinøkkel Harrows navn Hva som svarer der
hosts.console console.harrow.example Konsollen, nettapplikasjonen folk logger inn på
hosts.api api.harrow.example Gatewayen, som betjener applikasjonsprogrammeringsgrensesnittet (API) og ruter hver forespørsel til kunstig intelligens (KI)
hosts.auth auth.harrow.example Innloggingstjenesten, nexus-auth

global.domain inneholder domenet de tre ligger under, harrow.example for vår del. Hver vert er et fullstendig navn i seg selv og kan ligge under hvilket som helst domene du kontrollerer. Vi beholdt alle tre under ett domene fordi ett sertifikat da kunne dekke dem.

Opprett en DNS-oppføring (Domain Name System) for hver av de tre, som peker til ingress-kontrollerens adresse. Gjør det før forhåndskontrollen. nexusctl preflight slår opp hvert navn fra arbeidsstasjonen din og avbryter installasjonen hvis noen av dem mangler en oppføring, fordi en bruker ikke kan nå et navn som ikke lar seg løse.

Til venstre, tre DNS-navn: console.harrow.example, api.harrow.example og auth.harrow.example, hvert med en pil inn i én boks merket «ingress controller, ports 80 and 443». Fra den boksen fører tre piler inn i en større boks merket «namespace nexus»: console-pilen til «nexus-alpha :3000», api-pilen til «nexus-gateway :9092» og auth-pilen til «nexus-auth :9101». En stiplet ramme rundt navnerommet er merket «default deny; only the ingress namespace may reach these three».
Hvordan de tre offentlige navnene når tjenestene bak dem.

Velge hvordan TLS termineres

Chartets tls.mode bestemmer hvem som holder sertifikatene for de tre offentlige adressene. Det finnes tre valg, og du kan bytte mellom dem senere ved en oppgradering.

tls.mode Du oppgir Hva chartet gjør
existing (standard) En Kubernetes TLS-Secret i navnerommet nexus, navngitt i tls.existingSecret Alle tre Ingresser bruker den ene Secret-en
cert-manager En ClusterIssuer du kjører, navngitt i tls.clusterIssuer Annoterer hver Ingress slik at cert-manager utsteder nexus-console-tls, nexus-api-tls og nexus-auth-tls
none Noe foran klyngen som terminerer TLS, for eksempel din egen lastbalanserer Genererer Ingressene uten TLS-seksjon

Med existing betjener ett sertifikat alle tre vertene, så det må navngi alle tre, enten som tre alternative subjektnavn (SAN) eller som et jokertegn (wildcard) for domenet ditt. Vi brukte et sertifikat fra Harrows interne CA. Forhåndskontrollen leser Secret-en før du installerer, og advarer når sertifikatet utløper innen 30 dager.

Med cert-manager og en ACME-utsteder (Automatic Certificate Management Environment) legger ikke chartet til noen egen videresending, slik at en /.well-known/acme-challenge/-forespørsel på port 80 når løseren urørt. Ikke legg til en HTTP-til-HTTPS-videresending på ingress-kontrolleren som kjører før utfordringsbanen; et sertifikat som ikke kan fornyes, feiler i det stille uker senere.

Uansett hva du velger for den offentlige kanten, snakker tjenestene inne i navnerommet alltid over TLS fra chartets lokale CA. Den delen er ikke valgfri, og det er grunnen til at cert-manager er en forutsetning selv når tls.mode er existing eller none.

Hva som forlater klyngen, og hva som ikke gjør det

Chartet genererer en nettverkspolicy som avviser alt som standard (default-deny) for navnerommet nexus. Etter det er kun disse trafikkflytene tillatt:

  • trafikk mellom Nexus-podder inne i navnerommet;
  • DNS-oppslag mot klyngens DNS-tjeneste;
  • Kubernetes API-serveren, for de få tjenestene som kontrollerer arbeidsbelastningstokener;
  • ingress-kontrollerens navnerom, til de tre offentlige Services;
  • eventuelle CIDR-områder (Classless Inter-Domain Routing) du fører opp i networkPolicy.externalEgressCIDRs.

Den siste listen er tom som standard. Hvis du skal bruke et e-postrelé eller en modellserver utenfor klyngen, skal området deres legges inn der. Telemetri er av og forblir av: skjemaet godtar kun telemetry.enabled: false, og datalagrenes egen bruksrapportering er også slått av.

Chartet leser API-serverens adresser fra klyngen når du installerer. Hvis kontoen din ikke kan lese kubernetes-Endpoints i navnerommet default, oppgir du dem selv i networkPolicy.apiServerCIDRs, som /32-områder. proxy.trustedCIDRs angir pod-nettverket som ingress-kontrolleren din ligger på, slik at nexus-auth vet hvem sin X-Forwarded-For-header den skal stole på. Standardverdien, 10.42.0.0/16, er pod-nettverket til k3s.

Dimensjonering

Chartets standardforespørsler utgjør til sammen omtrent 2.05 prosessorkjerner (CPU, central processing unit) og 6.7 GiB minne. Det er dette planleggeren (scheduler) reserverer; grensene er høyere, og datalagrene vokser inn i dem etter hvert som du legger til brukere og filer.

Del Forespurt CPU Forespurt minne
Ni plattformtjenester (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) 1.1 kjerner 2.6 GiB
Nøkkeltjenesten, nexus-keys 0.05 kjerner 64 MiB
PostgreSQL 0.25 kjerner 1 GiB
Neo4j 0.25 kjerner 2 GiB
Valkey, Qdrant og objektlageret til sammen 0.25 kjerner 640 MiB
De to OpenBao-serverne til nøkkellageret 0.15 kjerner 384 MiB

Standardvolumene utgjør til sammen 142 GiB:

Lager Verdinøkkel 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økkellageret og opplåseren (unsealer) keys.openbao.storage.keystore, keys.openbao.storage.unsealer 5Gi og 1Gi
Kvitteringer for nøkkeltjenesten keys.receiptsStorage 1Gi

For en enkelt node bør du planlegge for 8 vCPU, 32 GiB arbeidsminne (RAM, random-access memory) og en SSD-disk (solid-state drive) på 250 GB. For en evaluering holder det med 4 vCPU, 16 GiB og 200 GB. Diskbildet for installasjonsprogrammet avviser en maskin med mindre enn 16 GiB minne (se kapittel 2.9, Diskbildet for installasjonsprogrammet), og jeg ville behandlet det som nedre grense overalt.

Grafikknoder er valgfrie. Uten en node som tilbyr en grafikkprosessor (GPU, graphics processing unit), svarer assistenten gjennom en vertstilknyttet modell ved hjelp av organisasjonens egen nøkkel. Forhåndskontrollen rapporterer dette som en advarsel, aldri som en feil. Kapittel 2.14, KI-leverandører og -modeller, dekker begge veiene.

Hvert lager kan også kjøre utenfor klyngen: sett dataTier.<store>.mode til external og oppgi verten og en Secret. En ekstern PostgreSQL trenger en superbrukerkonto for installasjonens oppstartsprosess (bootstrap) og et sertifikat som Nexus kan verifisere. Kapittel 2.11, Variasjoner: eksterne lagre, TLS og ingress, dekker dette. Hvis du beholder dem i klyngen, bør du legge dem på en lagringsklasse med ekte disker bak. Databasen er den delen du vil savne mest hvis den lokale disken på en node dør.

Installasjonsnavnet er permanent

keys.installationName er det operatørene kaller denne installasjonen. Det må samsvare med ^[a-z][a-z0-9-]{0,62}$: en liten bokstav, etterfulgt av opptil 62 små bokstaver, sifre eller bindestreker.

Den første gangen nøkkellageret starter, oppretter det installasjonens identitet under dette navnet, og den identiteten er låst for godt. En lisens fra Adverant utstedes for denne identiteten, så en lisens laget for én installasjon blir avvist på en annen med LICENCE_OTHER_INSTALLATION. Å endre navn vil bety en ny installasjon, en ny identitet og nye lisenser.

Chartet har ingen standardverdi for navnet. Det avviser en installasjon uten navn (INSTALLATION_NAME_MISSING) og avviser eksempelnavnet fra sine egne eksempelverdifiler (INSTALLATION_NAME_EXAMPLE). Forhåndskontrollen rapporterer begge deler før du kommer så langt.

Hos Harrow brukte vi lengre tid på dette enn jeg liker å innrømme. Vi landet på harrow-port-authority: det navngir organisasjonen, sier ingenting om hvilken klynge den kjører på, og vil fortsatt være gyldig når maskinvaren byttes ut. Unngå navn som prod-k3s-2 som beskriver dagens maskiner.

Nøkkelforvaltning

Nexus oppbevarer hver organisasjons nøkler i sitt eget nøkkellager, inne i klyngen. Du drifter det ikke til daglig, men du bestemmer før installasjonen hvem som kan få det opp igjen etter en omstart. Dette er beslutningen som koster mest hvis du gjør feil.

Nøkkellageret består av to OpenBao-servere. Hovedserveren, openbao, holder nøklene og låser seg selv opp gjennom en annen, mindre server, openbao-unsealer. Opplåseren (unsealer) er forseglet med Shamirs ordning: fem deler, hvor hvilke som helst tre åpner den. Når du installerer, initialiserer en forvaltnings-Job begge serverne inne i klyngen. I minnet til denne Job-en krypterer den opplåserens deler og nøkkellagerets gjenopprettingsnøkler til hver forvalter (custodian) du oppgir, lagrer kun chifferteksten (i Secret-ene openbao-unseal-shares-encrypted og openbao-recovery-keys-encrypted), og tilbakekaller begge rot-tokenene før den fullfører. Ingen ukryptert del når noen gang en disk eller en logg.

Etter enhver omstart av opplåserens node, starter opplåseren i forseglet tilstand. Nøkkellageret venter på den, og ingenting som trenger en nøkkel fungerer før en forvalter låser den opp. Det krever én dekryptering med forvalterens egen private nøkkel. Prosedyren finnes i kapittel 2.15, Dag to: drift av Nexus.

Lage en forvalternøkkel

En forvalter navngis ved den offentlige halvdelen av en age-nøkkel, kalt mottakeren (recipient). Hver forvalter lager sin egen nøkkel på sin egen maskin og gir deg kun mottakeren:

age-keygen -o custodian.key

Filens # public key:-linje er mottakeren, som begynner med age1. En forvalter med en Mac kan i stedet oppbevare nøkkelen i Mac-ens Secure Enclave, slik at den private halvdelen aldri forlater brikken og hver bruk ber om et fingeravtrykk:

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

Den mottakeren begynner med age1se1. Forvaltnings-Job-en krypterer til fem former for mottaker: age1 (X25519), age1tag1 og age1tagpq1 (tag), age1pq1 (hybrid post-kvante), og age1se1 (Secure Enclave). Den avviser enhver annen programtilleggsform, for eksempel age1yubikey1; oppgi i stedet den nøkkelen i en av de godkjente formene.

Chartet sjekker hver mottaker når det genereres. En feilskrevet mottaker feiler i bech32-kontrollsummen og blir avvist, slik at ingenting noen gang blir forseglet til en nøkkel ingen eier. Hvis noen ved et uhell limer inn en privat nøkkel i listen, avviser chartet den uten å skrive den ut tilbake. Eksempelmottakeren i chartets egne verdifiler blir også avvist (KEYS_CUSTODIAN_EXAMPLE); ingen har den private halvdelen til denne.

Hvor mange forvaltere

Hver del krypteres til hver forvalter, slik at én enkelt forvalter kan låse opp alene. Flere forvaltere betyr flere måter å gjenopprette på og flere personer som hver kan handle alene. Vi valgte tre hos Harrow: Aoife, meg, og en Secure Enclave-nøkkel på en ekstra bærbar PC som ligger i havnens safe. To er det minste jeg ville godtatt. Én er et enkelt feilpunkt (single point of failure) som før eller siden vil være på ferie når en node starter på nytt.

Velge utgave

edition er community eller enterprise, og enterprise.enabled må samsvare med den. Chartet avviser manglende samsvar, og det avviser enhver utgave som ikke er en av de to.

Utgaven bestemmer også hvilke avbildningsbilder du installerer. Hver chart-pakke inneholder en bildelås (images lock), listen over hvert avbildningsbilde etter sjekksum (digest), for én utgave. En Community-installasjon bruker kun Community-bilder. En Enterprise-installasjon bruker Enterprise-låsen, som består av Community-bildene pluss Enterprise-byggene, og henter dem med et pull-token fra Adverant-kontoen din. Kapittel 2.4, Hente og verifisere en utgivelse, forklarer låsen, og kapittel 2.2, Utgavene under panseret, forklarer hva hver utgave inneholder.

Du trenger ikke å bestemme deg for godt. En Community-installasjon kan oppgraderes til Enterprise på stedet, og beholder brukere, filer og historikk; kapittel 2.7, Installere Enterprise og legge inn en lisens, viser hvordan. Vi kjørte Community for piloten hos Harrow og byttet seks uker senere.

Lisensen er aldri en del av denne planen. Den er ikke en chart-verdi eller en montert fil: du importerer den etter installasjonen, gjennom konsollen, nexusctl eller API-et.

Velge leveranseform

Skjema Når det passer Kapittel
Helm-chart fra registry.adverant.ai Din egen Kubernetes-klynge, med en rute til registeret 2.6 og 2.7
nexusctl install Den samme klyngen, der forhåndskontrollen og signatursjekken kjøres for deg 2.6
nexusctl install --single-node Én maskin, der nexusctl også setter opp klyngen 2.8
Diskavbildningen for installasjonsprogrammet En fysisk server eller virtuell maskin (VM) du helst ikke vil klargjøre for hånd 2.9
Frakoblet pakke Ingen rute ut i det hele tatt; avbildningsbilder og chart kommer på en disk 2.10

Chartet er det samme i hver form. Det som endrer seg, er hvem som oppretter klyngen og hvor avbildningsbildene kommer fra.

Hent utgivelsen
Hent utgivelsen
Dette er utgivelsessiden i Adverant-kontoen. Legg merke til den tydelige erklæringen om hva en alfa-utgivelse lover, størrelsen og signaturen ved siden av hver fil, og de frakoblede kommandoene for å kontrollere en nedlasting.

Planleggingsskjemaet

Dette er Harrows, slik Aoife godkjente det. Kopier de to kolonnene til venstre og fyll ut den høyre for din egen installasjon.

Beslutning Verdinøkkel eller kommando Harrow Port Authority
Kubernetes og versjon (forhåndskontrollen leser det) k3s v1.33.6+k3s1, tre noder
Kube-kontekst for installasjonen --context harrow-prod
Navnerom --namespace nexus
Utgave edition, enterprise.enabled community for piloten, deretter enterprise
Bilderegister global.imageRegistry registry.adverant.ai
Domene global.domain harrow.example
Konsolladresse hosts.console console.harrow.example
API-adresse hosts.api api.harrow.example
Innloggingsadresse hosts.auth auth.harrow.example
TLS ved kanten tls.mode, tls.existingSecret existing, Secret harrow-public-tls fra Harrows interne CA
Ingress-klasse ingress.className traefik
Ingress-navnerom networkPolicy.ingressNamespace kube-system
Lagringsklasse storage.className local-path
Datalagre dataTier.<store>.mode Alle in-cluster, standardstørrelser
Utgående områder networkPolicy.externalEgressCIDRs Kun e-postreléets område
Installasjonsnavn (permanent) keys.installationName harrow-port-authority
Forvaltere (i praksis permanente) keys.custody.recipients Tre: Aoife Brennan, Tomás Reilly, den bærbare PC-en i safen (age1se1)
Grafikknoder (forhåndskontrollen leser det) Ingen for den tilkoblede piloten; vertstilknyttet modell med Harrows egen nøkkel
Første administrator nexusctl claim-code --administrator aoife.brennan@harrow.example

To rader på det arket kan ikke gjøres om: installasjonsnavnet, og forvalterne i den forstand at hvis du mister alle sammen, mister du nøkkellageret. Få disse to godkjent av noen med myndighet til å si ja. Alt annet er en verdiendring.

Når arbeidsarket er ferdig, går du til kapittel 2.4, Hente og verifisere en utgivelse, og laster ned utgivelsen.