Log indBook en briefing

Kapitel 2.15

Dag to: drift af Nexus

Det rutinemæssige arbejde med at drive en installation efter den første uge. Det begynder med at ophæve forseglingen af nøglelageret efter en genstart og slutter med afinstallation.

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

18 minutters læsetid

Første gang strømmen gik i serverrummet hos Harrow Port Authority, kom alt op at køre igen undtagen de dele, der krævede nøgler. Pods havde status Running, og konsollen blev indlæst. Ingen kunne åbne en fil. Tomás Reilly havde læst om dette, og alligevel tog det ham tyve minutter at komme i tanker om årsagen. Nøglelagerets oplåsningsserver (unsealer) starter forseglet efter hver genstart af dens node, og kun en nøgleforvalter kan åbne den.

Dette kapitel følger operatørens rutine efter den første uge, fra nøglelageret og dets nøgleforvaltere til afinstallation. Hvert nexusctl-verbum her accepterer --explain, som udskriver de kubectl- og helm-operationer, det ville køre, uden at køre dem. Brug det første gang du kører noget på en produktionsklynge.

Forvaltning af nøglelager

En installation har to OpenBao-servere i sit namespace. Nøglelageret, openbao, opbevarer alle de nøgler, som Nexus bruger. Oplåsningsserveren (unsealer), openbao-unsealer, er en anden, lille OpenBao, hvis eneste opgave er at ophæve forseglingen af nøglelageret. Nøglelageret ophæver selv sin forsegling via oplåsningsserverens transitnøgle; oplåsningsserveren er forseglet med Shamirs ordning som 5 nøgleandele, hvoraf enhver kombination af 3 ophæver forseglingen.

Ved den første installation initialiserer et forvaltnings-Job (custody Job) begge servere inde i klyngen. Det krypterer oplåsningsserverens nøgleandele samt nøglelagerets gendannelsesnøgler i sin egen hukommelse til hver nøgleforvalter, der er angivet i keys.custody.recipients, og gemmer kun chifferteksten (de to Secrets openbao-unseal-shares-encrypted og openbao-recovery-keys-encrypted). Det tilbagekalder begge root-tokens i det samme Job. Hver nøgleforvalters pakke indeholder nok andele til at ophæve forseglingen på egen hånd, så én nøgleforvalter er alt, hvad du behøver efter en genstart.

Efter en genstart af en node

Efter enhver genstart af den node, som oplåsningsserveren kører på (et strømsvigt, en genstart af maskinen, en genstart af container-runtime), starter oplåsningsserveren forseglet. Indtil en nøgleforvalter ophæver forseglingen, forbliver nøglelageret også forseglet, og intet, der kræver en nøgle, fungerer. Konsollen svarer stadig, og brugere kan stadig logge ind, men enhver handling, der kræver en nøgle fra nøglelageret, venter: åbning af krypteret indhold, en aktivering (claim), en kontrol af en kompileret del.

Spørg selve OpenBao inde i hver pod. Dette er oplåsningsserveren:

kubectl -n nexus exec openbao-unsealer-0 -c openbao -- \
  bao status -format=json -address=https://127.0.0.1:8200 \
  -ca-cert=/openbao/tls/ca.crt -tls-server-name=openbao-unsealer
echo "exit $?"

Kør den samme kommando mod openbao-0 med -tls-server-name=openbao for nøglelageret. bao status afslutter med 0, når serveren er uforseglet, 2 når den er forseglet, og 1 når den ikke kunne svare. En afslutningskode på 1 konkluderer intet, da den pågældende pod måske ikke er oppe endnu. Vent et minut, og spørg igen. Hvis oplåsningsserveren er uforseglet, og nøglelageret stadig er forseglet, er nøglelageret i gang med at ophæve sin egen forsegling, og du behøver ikke gøre noget.

Til venstre: et personikon med teksten "Nøgleforvalter, med sin egen age-identitet". En pil går mod højre ind i en boks "unseal.sh på nøgleforvalterens maskine (én dekryptering)". Derfra går en pil med teksten "kubectl port-forward, Transport Layer Security (TLS) kontrolleret mod oplåsningsserverens certifikatmyndighed (CA)" ind i en boks "openbao-unsealer (Shamir 5 nøgleandele, enhver kombination af 3)". Fra oplåsningsserveren går en anden pil med teksten "transitnøgle, automatisk" ind i en boks "openbao, nøglelageret". Fra nøglelageret går en vifte af pile til små bokse "nexus-keys", "nexus-auth", "de andre tjenester". En note under nøgleforvalteren: "identiteten forlader aldrig denne maskine".
Hvad en nøgleforvalter gør efter en genstart af en node.

Ophævelse af forsegling

Dette chart leverer unseal.sh i sin files/custody/-mappe, byte for byte identisk i hver udgivelse. En nøgleforvalter kører det på sin egen maskine. Det læser den krypterede Secret, dekrypterer den én gang med nøgleforvalterens identitet (en Secure Enclave-identitet beder om Touch ID én gang), indsender nøgleandelene til oplåsningsserveren og bekræfter, at forseglingen er ophævet. Ingen nøgleandel skrives nogensinde til en fil eller placeres på en kommandolinje.

Harrow kører det i direkte tilstand via en port-forward:

kubectl -n nexus get secret openbao-unsealer-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > unsealer-ca.crt
kubectl -n nexus port-forward pod/openbao-unsealer-0 28200:8200 &

AGE_IDENTITY=<path-to-your-custodian-identity> \
OPENBAO_NS=nexus \
UNSEAL_ADDR=https://127.0.0.1:28200 \
UNSEAL_CACERT=unsealer-ca.crt \
UNSEAL_RESOLVE=openbao-unsealer.<namespace>.svc \
UNSEAL_SECRET_JSON_CMD='kubectl -n nexus get secret openbao-unseal-shares-encrypted -o json' \
bash unseal.sh

<path-to-your-custodian-identity> er nøgleforvalterens age-identitetsfil, den private halvdel af en af modtagerne i keys.custody.recipients. UNSEAL_RESOLVE er det navn, som oplåsningsserverens certifikat bærer (<namespace> er det namespace, som Nexus er installeret i, nexus som standard), så TLS kontrolleres mod oplåsningsserverens egen CA, selvom forbindelsen går til 127.0.0.1. Scriptet slår aldrig certifikatkontrol fra.

Afslutningskode Sidste linje Betydning
0 UNSEALED nexus/openbao-unsealer-0 Uforseglet. Hvis den allerede var det, blev intet sendt
1 STILL-SEALED … Stadig forseglet, eller et kald til ophævelse af forsegling mislykkedes
2 UNSEAL-REFUSED … En forudsætning mangler, som er nævnt i meddelelsen
3 UNSEAL-REFUSED … Denne identitet kan ikke dekryptere nøgleandelene, så den er ikke nøgleforvalter for denne installation. Intet blev sendt

Inden for et minut følger nøglelageret af sig selv. Kontroller med kubectl -n nexus get deploy,statefulset, at alt er klar igen.

Nøgleforvaltere vælges før installationen, og hver især opretter sin egen nøgle på sin egen maskine. Chartet ser kun nogensinde den offentlige halvdel:

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

Den første kommando opretter en almindelig age-identitet; dens modtager er # public key: age1...-linjen i filen. Den anden opretter en identitet, der opbevares i en Macs Secure Enclave, med en modtager, der starter med age1se1. Enhver af modtagerne indsættes i keys.custody.recipients. Identitetsfilen forbliver hos sin nøgleforvalter, offline.

Sikkerhedskopiering og gendannelse

Sikkerhedskopiering og gendannelse viser hvert lager med dets seneste sikkerhedskopi og det seneste tidspunkt, hvor en gendannelse af det faktisk blev testet. En sikkerhedskopi er først bevist, når den er blevet gendannet, så siden sporer begge dele. Seks lagre sikkerhedskopieres. Hoveddatabasen indeholder personer og indstillinger, jobs og revisionsloggen. Ved siden af den ligger vidensgrafen og søgeindekset, dernæst fillageret og hukommelseslageret. Nøglerne udgør det sjette, forseglet og holdt adskilt fra dataene. Sikkerhedskopier går til dit eget lager, krypteret med dine egne nøgler, og Adverant kan ikke læse dem. Når et lager ikke er blevet testgendannet inden for din regel, viser siden skiltet RESTORE_TEST_OVERDUE med en knap til at teste det nu. En testgendannelse kører i et separat område, uden at nogen bemærker det.

De samme to handlinger er tilgængelige fra kommandolinjen:

nexusctl backup now
nexusctl backup verify

backup now tager en sikkerhedskopi af hvert lager på én gang. backup verify kontrollerer den seneste sikkerhedskopi. Kør begge før enhver ændring, du er nervøs for.

Sikkerhedskopiering og gendannelse
Sikkerhedskopiering og gendannelse
Hvert lager med dets seneste sikkerhedskopi og dets seneste testede gendannelse. Søgeindekset har overskredet fristen for en test, og skiltet tilbyder at køre en nu.

For at gendanne skal du angive sikkerhedskopien:

nexusctl restore --from <backup-id>

<backup-id> kommer fra listen under Sikkerhedskopiering og gendannelse. En gendannelse kræver, at en anden person godkender den, og mens den kører, viser statusbjælken den sammen med starttidspunktet og hvem, der godkendte den. Alle har kun læseadgang under gendannelsen, hvilket er anderledes end at være låst ude: brugere kan logge ind og læse. Jobs starter ikke (tidsplaner venter og indhenter det forsømte), og søgning vender tilbage, når søgeindekset er tilbage. Alt, hvad der er skrevet, efter at sikkerhedskopien blev taget, går tabt, så gendannelsesrapporten viser det pr. ejer, så de kan genskabe det.

Gendanner
Gendanner
En igangværende gendannelse. Lagre vender tilbage i rækkefølge, brugere har kun læseadgang, indtil det sidste er på plads, og en meddelelse på hver side oplyser, hvornår det forventes tilbage.

Opbevar endnu en ting sammen med dine sikkerhedskopier: den Secret, der hedder nexus-generated i nexus-namespacet. Chartet opretter installationens genererede adgangskoder og krypteringsnøgler ved den første installation og læser dem tilbage fra denne Secret ved hver opgradering. Data forseglet under EXTERNAL_KEY_ENCRYPTION_KEY kan kun åbnes med denne nøgle. Gem en kopi af denne Secret, hvor du end opbevarer det mest følsomme materiale, du har, for enhver, der er i besiddelse af den, er i besiddelse af disse nøgler.

Opgraderinger

Tomás opgraderer i to trin. Først spørger han, hvad der vil ændre sig:

nexusctl upgrade plan --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

Planen viser, hvad der ændres i udgivelsen, enhver ændring i databasens struktur, og hvorvidt det kan fortrydes. Derefter anvender han den:

nexusctl upgrade apply --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

Anvendelsen tager først en sikkerhedskopi og kører forhåndskontrollen (preflight). Derefter flytter den motorerne i bølger, og hver bølge venter, indtil den forrige har været fejlfri i 10 minutter. Siden Opgradering viser hver bølge undervejs samt installationens sundhedstilstand i mellemtiden. Den oplyser også, indtil hvornår vejen tilbage holdes åben; efter denne dato kræver det en gendannelse at gå tilbage. Hvis et trin mislykkes, ruller Nexus hver motor tilbage til den forrige udgivelse og kontrollerer dem. Meddelelsen UPGRADE_ROLLED_BACK nævner derefter det trin, der mislykkedes, og oplyser, at data ikke blev ændret. Løsningen vises før Prøv igen, og supportpakken er blot et klik væk.

For en installation uden forbindelse til omverdenen ankommer pakken på et fysisk medie. Import fra medie kontrollerer udgivelsens signatur mod den Adverant-udgivelsesnøgle, der er installeret på installationen, og kontrollerer, at versioner kun bevæger sig fremad. Filer signeret af andre afvises med MEDIA_SIGNATURE_INVALID: intet indlæses, og den kørende udgivelse fortsætter med at køre.

Opgradering
Opgradering
En igangværende opgradering. En sikkerhedskopi blev taget først, den anden af tre bølger er i bevægelse, og vejen tilbage holdes åben indtil en angivet dato.
Opgradering mislykkedes og blev rullet tilbage
Opgradering mislykkedes og blev rullet tilbage
En bølge mislykkedes, fordi en diskenhed løb tør for plads. Hver motor er tilbage på den forrige udgivelse med data urørt, og løsningen er angivet før Prøv igen.

Hvad der sker under motorhjelmen

nexusctl upgrade apply kører helm upgrade mod chartet. Hvis du selv opgraderer med Helm, gælder de samme regler:

helm upgrade nexus oci://registry.adverant.ai/nexus/charts/nexus --version <version> -n nexus -f harrow-values.yaml
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s

Skemaet flyttes, før de nye pods rulles ud. Chartets migreringer er pre-upgrade-hooks, der kører i rækkefølge: database-bootstrap først, derefter hver tjenestes migreringer, derefter migreringerne for konsollens backend for frontend (BFF). Forvaltnings-Jobbet kører også, og på en installation, der allerede er initialiseret, bekræfter det dette og ændrer intet. Hvert hook-Job har en backoff-grænse på 0, så en migrering, der mislykkes, stopper opgraderingen og forsøges aldrig igen i det skjulte: læs dens log med kubectl -n nexus logs job/<hook-job>, før du prøver igen.

Hver tjenestes pod venter i en init-container, wait-for-schema, indtil udgivelsesprotokollen viser, at dens migreringer er anvendt for den nye udgivelses image. Efter en tilbagerulning, eller en opgradering, der kun ændrede værdier, finder en genstartet pod sin række og starter med det samme.

Før du opgraderer

Tre punkter fra udgivelsesnoterne er værd at planlægge efter:

  1. Opgrader i en stille periode. Ved den første opgradering af en installation, der er oprettet ud fra et tidligere chart, fjerner bootstrap-jobbet de gamle standardtabelrettigheder, og hver tjeneste får sine egne tilbage fra sin egen migrering. Indtil denne migrering kører, kan en tjeneste ikke bruge sine tabeller. Afbrydelsen varer få sekunder. Hvis sekunder har betydning, skal du skalere tjenesterne til nul først og sikkerhedskopiere, når migreringsjobbene er færdige.
  2. Giv hver API-nøgle (application programming interface) en organisation. En nøgle uden organisation afvises med 403 TOKEN_ORG_MISSING af enhver tjeneste, der kontrollerer nøgler gennem nexus-auth, inklusive nexus-graphrag. Før du opgraderer, skal du give hver sådan nøgle en organisation eller udstede en ny nøgle. Gamle bcrypt-nøgler bliver ved med at fungere indtil deres endelige tilbagekaldelsesdato.
  3. Ryd de cachelagrede API-nøgler bagefter. Op til en times cachelagrede nøgleposter bærer det forkerte applikationsnavn, indtil du gør det. Kør dette mod nexus-auths cache, installationens Valkey (nexus-valkey, adgangskode i den Secret, der hedder nexus-generated under VALKEY_PASSWORD):
pw=$(kubectl -n nexus get secret nexus-generated -o jsonpath='{.data.VALKEY_PASSWORD}' | base64 -d)
kubectl -n nexus exec nexus-valkey-0 -- sh -c \
  'valkey-cli -a "$1" --scan --pattern "apikey:prefix:*" | xargs -r valkey-cli -a "$1" del' _ "$pw"

Dette gælder for standardlageret i klyngen. Med dataTier.valkey.mode: external findes der ikke en sådan pod: kør den samme scanning og sletning mod din egen Valkey-host med adgangskoden fra den Secret, der er angivet i dataTier.valkey.external.existingSecret.

Tilbagerulning

Inden for det tidsvindue, som siden Opgradering viser, fører Gå tilbage hver motor tilbage til den forrige udgivelse. Efter tidsvinduet betyder det at gå tilbage, at man skal gendanne den sikkerhedskopi, som opgraderingen tog først.

To værdier må aldrig ændre sig på tværs af en opgradering eller en tilbagerulning.

keys.installationName er permanent. Den første nøglelager-bootstrap opretter installationens identitet under den, og den identitet er det, din licens angiver. Brug nøjagtig den samme værdi i hver values-fil, du nogensinde anvender på denne installation.

Den Secret, der hedder nexus-generated, skal forblive, som den er. Ved hver opgradering læser chartet EXTERNAL_KEY_ENCRYPTION_KEY fra den og kontrollerer dens form. En værdi, der hverken er base64 af 32 bytes eller den rå 32-byte-nøgle fra en ældre installation, stopper genereringen med EXTERNAL_KEY_ENCRYPTION_KEY_INVALID, og chartet udskriver aldrig værdien. Det betyder, at nogen har redigeret eller erstattet denne Secret. Læg den nøgle tilbage, som denne installations data er forseglet under, som base64 af dens 32 bytes (printf %s "$OLD" | base64), og opgrader igen. En ny tilfældig nøgle ville efterlade alt, hvad der er forseglet under den gamle, ulæseligt.

Skalering

Hver komponent har en kontakt og en størrelse i values-filen. Påkrævede komponenter kan ikke slås fra: chartet kører dem uanset, hvad deres kontakt siger. De andre kan tildeles flere replikaer og flere ressourcer.

# harrow-values.yaml (Helm values): scaling
components:
  gateway:
    replicas: 2
    resources: { requests: { cpu: 400m, memory: 1Gi }, limits: { memory: 3Gi } }
  graphrag:
    replicas: 2
  workflows:
    replicas: 2
workflows:
  concurrency: "8"
dataTier:
  qdrant:
    resources: { requests: { cpu: 200m, memory: 512Mi }, limits: { memory: 4Gi } }

Anvend det med helm upgrade som ovenfor. Diskenheder dimensioneres under dataTier.<store>.size; kontroller, at din storage class kan udvide en diskenhed, før du øger en. Installationens tilstand viser i grafer, hvor belastede klyngens processorer og hukommelse har været, samt den resterende plads i hver. Udvid den, der løber tør først.

Supportpakker

Når Harrow har brug for Adverants hjælp, opretter Tomás en supportpakke:

nexusctl support-bundle --out harrow-support-4471.tar.gz

Konsollens side Supportpakke opretter den samme fil. Den indsamler motorloggene fra de seneste 24 timer med sundheds- og versionsoplysninger. Indstillinger medtages uden deres hemmeligheder sammen med forhåndskontrol- og installationsrapporterne. Før noget skrives, erstatter sløringen navne og hemmeligheder med pladsholdere, og du læser en forhåndsvisning af nøjagtig det, der sendes ud. Brugernes eget indhold indsamles aldrig. Pakken sendes til Adverant enten som et upload til din kontos side Support og supportpakker eller som en fil, der tages ud på et fysisk medie. Kun de supportingeniører, der er angivet på anmodningen, kan åbne den, og den slettes efter 30 dage.

Supportpakke
Supportpakke
Oprettelse af en supportpakke. Forhåndsvisningen af sløringen viser, hvad der skjules, før noget sendes ud, og kun de angivne ingeniører kan åbne den.

Eksport af dokumentation

Revisorer og dit eget compliance-team ønsker ofte bevis for, at platformen opfører sig som beskrevet. nexusctl evidence export skriver det:

nexusctl evidence export --out harrow-evidence-2027-01

Udover de optegnelser, den eksporterer, kører kommandoen platformens accepttests: AI-routeren (kunstig intelligens) kan nås og svarer, et UNO-job afsendes og fuldføres, og en læsning på tværs af organisationer afvises. Deres resultater findes i probes.json i outputmappen.

Status i overblik

nexusctl status --json svarer på, om installationen er fejlfri, og hvilken tilstand hver komponent er i. Den rapporterer også licenstilstanden med dens udløbsdato, udgaven og den kørende udgivelse. Hver kompileret del er angivet med sit kontrolsum-digest og sin signatur. Det er den kommando, du skal lægge bag din egen overvågning.

Afinstallation

nexusctl uninstall --profile <profile-file>

<profile-file> er udrulningsprofilen for klyngen, den samme fil, som du sendte til nexusctl handoff --profile <profile-file> --out <dir>, hvis dit platformsteam driver klyngen. Handoff skriver til det team en liste i klart sprog over, hvad Nexus har brug for fra klyngen, samt manifesterne til at opfylde det. Uninstall fjerner Nexus-namespaces og intet andet, og den beholder dine sikkerhedskopier. Installationens identitet forsvinder med den. En senere installation på den samme klynge er en ny installation med en ny identitet, så dens aktivering (claim) er en ny aktivering, og dens licens er en ny licens.

Siderne Denne installation

Operatører af installationen har deres egen gruppe i menuen, Denne installation, og dens sider er der, hvor det meste af dette kapitel foregår i konsollen. Et medlem, der åbner en af dem, ser siden Ikke en administrator, som oplyser, hvem der kan handle.

Side Hvad den bruges til
Licens og hvad den låser op for Licensen og dens funktionsgrupper (kapitel 2.13, Licenser)
Hvis licensen udløber Udløbstrappen i ord, med denne licens' datoer
Kompilerede komponenter Hvert licenseret modul med dets natlige signaturkontrol
Forbrugsopgørelse til Adverant De årlige tællere, læsbare før de sendes ud
Versioner og opgraderinger Hver installeret version, med hvem der installerede den og hvornår
Opgradering Den trinopdelte opgradering og vejen tilbage
Sikkerhedskopiering og gendannelse Hvert lager, dets seneste sikkerhedskopi og dets seneste testede gendannelse
Installationens tilstand Noder, kapacitet og driftsomkostninger, med advarsler
Nøgler og sletning Hver organisations nøgle, og Slet med en årsag og en anden person
Hændelser Åbne og lukkede problemer, med hvad der blev gjort
Udfases snart Funktioner, der slås fra, med datoer, eksport og erstatning
Status Hver del af Nexus nu og over 30 dage, i ord som alle kan læse
Supportpakke Hvad der sendes ud til Adverant, og hvordan

To af disse sider fortjener en kommentar. Kompilerede dele kontrollerer hvert licenseret modul mod Adverants signatur hver nat. En ændret kopi af et modul afvises og indlæses aldrig, mens den signerede kopi fortsætter med at køre, og siden tæller afvisninger pr. måned, så en manipuleret kopi ikke kan passere ubemærket. Status er skrevet, så alle i organisationen kan læse den. Den viser hver del af Nexus nu og over de seneste 30 dage som en stribe af dage med planlagt vedligeholdelse og nylige hændelser, og en operatør tilføjer en hændelse eller et vedligeholdelsesvindue fra den samme side.

En Community-installation har én side, Denne installation (Community), med dens version, sundhedstilstand og opdateringer. Enterprise-siderne vises på den som smagsprøver, der oplyser, hvem der kan slå dem til.