Logg innBestill en gjennomgang

Kapittel 2.6

Installere Community på Kubernetes

En nummerert installasjon av Community-utgaven med Helm, fra cert-manager til hver arbeidsbelastning er klar, med verdifilen forklart nøkkel for nøkkel, hvorfor det ikke brukes --wait, rekkefølgen chartets hooks kjører i, og installasjonsveien med nexusctl som et alternativ.

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

18 minutter å lese

Selve installasjonen er én helm install. Alt rundt den er der for at denne ene kommandoen skal fungere på første forsøk: cert-manager i forkant, en verdifil (values-fil) du har lest linje for linje, og en ventetid i etterkant som vet hva den skal vente på. Hos Harrow Port Authority installerte vi Community først, for en seks ukers pilot, på k3s-klyngen med tre noder fra planleggingsarket vårt. Utgivelsen kjørte på rundt tjue minutter, og ingen kunne logge inn før vi gjorde krav på den, slik det skal være.

Dette kapittelet forutsetter at du allerede har gjort tre ting: gjennomgått planleggingsarket (kapittel 2.3, Planlegge en installasjon), hentet og kontrollert utgivelsen (kapittel 2.4, Hente og verifisere en utgivelse), og kjørt forhåndskontrollen (kapittel 2.5, Forhåndskontroll med nexusctl). Hvis noe av dette fortsatt er ugjort, gå tilbake. Installasjonen avviser de fleste feil ved navn, men noen få, som en nøkkelforvalter hvis nøkkel du allerede har mistet, kan den ikke se.

Trinn 1: bekreft verktøy og kontekst

  1. Sjekk at Helm er versjon 4.

    helm version

    Installasjonen er avhengig av at Helm 4 som standard venter på chartets hook-Jobs. Vi brukte v4.3.1.

  2. Pek kubectl mot klyngen på planleggingsarket ditt, og bekreft det.

    kubectl config use-context harrow-prod
    kubectl get nodes

    Hver node skal vise Ready. Forhåndskontrollen sjekket dette allerede, men en node kan falle ut mellom forhåndskontrollen og installasjonen, og det er raskere å se det her.

Trinn 2: installer cert-manager først

Chartet oppretter sin egen lokale sertifikatautoritet (CA) med cert-manager, og hver tjeneste snakker med de andre ved hjelp av sertifikater den utsteder: en selvsignert Issuer, et tiårig lokalt CA-sertifikat og kortlivede sertifikater for tjenestene. Derfor må cert-manager kjøre før Nexus. Utgivelsen krever v1.21.3, og den trenger ikke trust-manager.

  1. Installer cert-manager fra sitt eget chart, med sine egendefinerte ressurser:

    helm install cert-manager <cert-manager-chart> -n cert-manager --create-namespace \
      --set crds.enabled=true --wait --timeout 10m

    <cert-manager-chart> er cert-manager v1.21.3-chartet fra cert-manager-prosjektets egen utgivelse. Det er riktig å vente her; det er cert-managers egen installasjon, uten hooks som er avhengige av noe annet.

  2. Vent på dens webhook, som hver sertifikatforespørsel går gjennom:

    kubectl -n cert-manager rollout status deploy/cert-manager-webhook --timeout=300s
    deployment "cert-manager-webhook" successfully rolled out

Trinn 3: opprett navnerommet og TLS Secret

Med tls.mode: existing forventer chartet sertifikatet ditt som en Kubernetes Secret i navnerommet før installasjonen. Transport Layer Security (TLS) for alle tre adressene kommer fra denne ene Secret-ressursen, så sertifikatet må navngi alle de tre vertene.

kubectl create namespace nexus
kubectl -n nexus create secret tls harrow-public-tls \
  --cert=harrow-public.crt --key=harrow-public.key

harrow-public.crt er sertifikatet, med tilhørende kjede, og harrow-public.key er den private nøkkelen. Hvis du valgte tls.mode: cert-manager eller none i kapittel 2.3, Planlegge en installasjon, hopper du over denne Secret-ressursen; du kan likevel opprette navnerommet nå, eller la Helm gjøre det med --create-namespace i trinn 6.

Trinn 4: skriv verdifilen

Dette er Harrows verdifil for piloten. Hver nøkkel i den er en nøkkel som chartets skjema godtar; skjemaet avviser alle andre, så en feilstavet nøkkel gjør at installasjonen feiler i stedet for å bli ignorert i det stille.

# harrow-values.yaml (Helm values, Community)
global:
  imageRegistry: registry.adverant.ai
  domain: harrow.example
hosts:
  console: console.harrow.example
  api: api.harrow.example
  auth: auth.harrow.example
edition: community
enterprise:
  enabled: false
tls:
  mode: existing
  existingSecret: harrow-public-tls
ingress:
  className: traefik
storage:
  className: local-path
networkPolicy:
  ingressNamespace: kube-system
  externalEgressCIDRs: ["10.20.9.25/32"]
keys:
  installationName: harrow-port-authority
  custody:
    recipients:
      - "<recipient-aoife>"
      - "<recipient-tomas>"
      - "<recipient-safe-laptop>"

Hver <recipient-...> er én nøkkelforvalters offentlige age-mottaker, age1...- eller age1se1...-linjen de sendte deg. Her er hver nøkkel vi satte, og hvorfor.

global.imageRegistry er registeret nodene dine henter fra. Chartet har ingen standardverdi; det bygger hver avbildning som <this>/nexus/<service>@<digest>. For en tilkoblet installasjon er det registry.adverant.ai. Hvis du kopierte avbildningene inn i ditt eget register, er det den verten.

global.domain er domenet de tre adressene ligger under.

hosts.console, hosts.api og hosts.auth er installasjonens identitet: de tre navnene folk og programmer bruker. Hvert av dem må allerede kunne slås opp i Domain Name System (DNS), noe forhåndskontrollen sjekket.

edition og enterprise.enabled må samsvare: community med false, eller enterprise med true. Chartet avviser alt annet, og det avviser en utgave som avbildningenes låsefil ikke ble laget for.

tls.mode og tls.existingSecret velger hvordan det offentlige endepunktet får sertifikatet sitt. Med cert-manager ville du satt tls.clusterIssuer i stedet, og med none ingen av dem.

ingress.className navngir ingress-klassen. La den stå udefinert for å bruke klyngens standardklasse.

storage.className navngir lagringsklassen for hvert datavolum. La den stå udefinert for å bruke standarden.

networkPolicy.ingressNamespace er navnerommet ingress-kontrolleren din kjører i. Standarden, kube-system, er riktig for Traefik i k3s; vi satte den likevel slik at det står uttrykkelig i filen.

networkPolicy.externalEgressCIDRs lister opp adresseområder, i Classless Inter-Domain Routing (CIDR)-notasjon, utenfor navnerommet som tjenestene kan nå, utover DNS og Kubernetes sin application programming interface (API)-server. Vår inneholder e-postreléets ene adresse; hvis listen er tom, kan ingenting utenfor navnerommet nås.

keys.installationName er det permanente navnet nøkkellageret utsteder installasjonsidentiteten under.

keys.custody.recipients lister opp nøkkelforvalternes offentlige age-mottakere. Forvaltningsjobben (custody Job) krypterer hver opplåsingsdel (unseal share) og gjenopprettingsnøkkel til hver av dem.

Nøkler du kan trenge, og nøkler du bør la være i fred

Nøkkel Når den skal settes
networkPolicy.apiServerCIDRs Når chartet ikke kan lese API-serverens adresser fra kubernetes-endepunktene (Endpoints). Oppgi dem som /32-områder
proxy.trustedCIDRs Når ingress-kontrollerens podder ikke er på k3s sin 10.42.0.0/16
ai.localProvider.baseUrl Når organisasjonen kjører sin egen OpenAI-kompatible modellserver for kunstig intelligens (KI) (kapittel 2.14, KI-leverandører og -modeller)
ai.installationHosts Når den modellserveren ligger på private navn inne i installasjonen
dataTier.<store>.size Når et lager trenger mer enn standardvolumet sitt
dataTier.<store>.mode external for et lager du drifter selv (kapittel 2.11, Variasjoner: eksterne lagre, TLS og ingress)
components.<service>.replicas, components.<service>.resources Når du skalerer opp en tjeneste
auth.rateLimitPerMinute Når tung automatisering krever mer enn 5 000 forespørsler i minuttet per person
schemaWait.timeoutSeconds Når en treg disk gjør at de første migreringene tar mer enn 30 minutter

La istio.enabled stå på false; Nexus trenger ingen service mesh. La telemetry.enabled stå på false; skjemaet godtar ingen annen verdi. La orchestrator.platformServiceUserId og probitas.flags stå slik chartet setter dem.

Ingen påloggingsinformasjon er noen gang en verdi i chartet. Det finnes ingen nøkkel for en modelleverandørs API-nøkkel, et e-postpassord eller et pull-token. Tjenestene genererer sine egne interne hemmeligheter ved installasjon og beholder dem ved oppgradering, og hver organisasjons modellnøkler legges inn i dens egen nøkkelpool fra konsollen etter første kjøring.

Trinn 5: kjør forhåndskontroll mot den endelige filen

nexusctl preflight --context harrow-prod --values harrow-values.yaml

Kjøringen må avsluttes med 0 failed. Kapittel 2.5, Forhåndskontroll med nexusctl, forklarer hver rad. Hvis du har endret noe siden forrige kjøring, selv bare en størrelse, kjør den på nytt.

Trinn 6: installer, uten --wait

helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
  --namespace nexus -f harrow-values.yaml --timeout 45m

Hvis du ikke opprettet navnerommet i trinn 3, legg til --create-namespace. Hvis du installerer fra en chart-fil du har lastet ned og kontrollert, setter du inn filbanen i stedet for oci://-referansen.

Ikke legg til --wait. Chartets database-bootstrap kjører som en post-install-hook, etter at utgivelsens egne ressurser eksisterer, og det er denne hooken som gir hver tjeneste sin databaserolle og sitt passord. --wait ville holdt igjen installasjonen til hver Deployment er Available, og ingen Deployment kan bli Available før hooken den venter på har kjørt. Tjenestene blir stående med avviste databaseinnlogginger, og Helm venter på dem frem til tidsavbruddet. Uten --wait venter Helm 4 likevel på hver hook-Job, i rekkefølge, og det er den ventingen du vil ha.

Når den siste hooken er ferdig, skriver Helm ut sammendraget sitt:

NAME: nexus
NAMESPACE: nexus
STATUS: deployed
REVISION: 1

STATUS: deployed betyr at hver hook lyktes. Det betyr ennå ikke at hver tjeneste er klar til å betjene forespørsler; trinn 7 venter på det.

Hva som kjører, og i hvilken rekkefølge

Helm kjører hookene etter vekt, laveste først, og venter på hver enkelt før den neste. Hver migrerings-Job har backoffLimit: 0: en mislykket migrering gjør at installasjonen feiler, og den blir aldri prøvd på nytt i bakgrunnen. En Job som lykkes, slettes; en Job som feiler, blir værende med loggen sin, slik at du kan lese den.

Vekt Hook Hva den gjør
-30 Forutsetninger Hook-kontoen nexus-migrations, Secret-ressursen nexus-migrations-env som kun brukes av hooks og inneholder den genererte databasepåloggingsinformasjonen, samt forvaltningsjobbens konto, rolle, konfigurasjon og sertifikat
-20 nexus-db-bootstrap Oppretter databasene og rollene, hvorav ingen er superbruker og ingen kan omgå sikkerhet på radnivå (RLS); legger til utvidelsene, blant annet PostGIS og pgvector; oppretter utgivelsesprotokollen (release ledger)
-15 nexus-openbao-custody-init Initialiserer nøkkellageret og opplåseren (unsealer), krypterer delene og gjenopprettingsnøklene til nøkkelforvalterne dine, tilbakekaller begge rot-tokenene og utsteder installasjonsidentiteten under keys.installationName
-12 nexus-graphrag-migrations Legger inn graftjenestens skjema først, fordi innloggingstjenestens skjema refererer til objekter den eier
-10 nexus-auth-migrations Legger inn innloggingstjenestens skjema og dens to kjøretidsroller
-5 nexus-orchestrator-migrations, nexus-gateway-migrations, nexus-probitas-migrations Hver tjenestes eget skjema; probitas kjører etter auth fordi den kontrollerer auth sine tabeller først
0 nexus-alpha-bff-migrations Klargjør backend for frontend (BFF)-databasen og dens roller, og kjører deretter migreringene dens

Hver migrerings-hook avsluttes med å skrive én rad i utgivelsesprotokollen, nexus_release.schema_applied: navnet på kjeden og sjekksummen (digest) til avbildningen som kjørte den. Den skriver denne raden først etter at migreringskjøreren er ferdig uten feil. Bootstrap-jobben skriver ut db-bootstrap: done; SQL-migrerings-hookene skriver ut schema-ledger: recorded <chain> for this release's image som sin siste linje. Konsollens egen migrerings-hook, nexus-alpha-bff-migrations, registrerer raden sin på samme måte og skriver deretter ut bff-migrate: done.

En horisontal tidslinje som går fra venstre mot høyre, merket «helm install». På det øverste sporet, sju hook-bokser i rekkefølge: «-30 prerequisites», «-20 db-bootstrap», «-15 custody init», «-12 graphrag migrations», «-10 auth migrations», «-5 orchestrator, gateway, probitas migrations», «0 BFF migrations». Hver migreringsboks har en liten pil ned til en sylinder på et midtre spor merket «release ledger: nexus_release.schema_applied». På det nederste sporet, en lang stolpe som starter til venstre merket «Deployments start, wait-for-schema holds each pod»; korte vertikale piler går opp fra den til protokollen, og hver Deployments stolpe blir heltrukket når dens egen protokollrad dukker opp.
Rekkefølgen ved en ny installasjon, med hooks og arbeidsbelastninger (workloads) side om side.

Hvordan tjenestene venter på skjemaet sitt

Deployments starter så snart Helm oppretter dem, mens hookene fortsatt kjører. En tjeneste som startet mot en database uten rolle, passord eller skjema, ville krasjet og startet på nytt helt til hookene var ferdige. Derfor har hver Deployment som bruker databasen en init-kontainer, wait-for-schema, som holder podden tilbake i stedet.

Den leser utgivelsesprotokollen som nexus_ledger_reader, en bruker som kan lese den ene tabellen og ingenting annet, og venter til protokollen viser kjedene for denne utgivelsens avbildningssjekksummer. Den spør hvert schemaWait.intervalSeconds (3 som standard), skriver ut tilstanden sin når den endres og ved hver tjuende spørring, og gir opp etter schemaWait.timeoutSeconds (1 800 som standard) med en feilmelding som navngir tjenesten.

Utrulling Venter på
nexus-auth nexus-auth-migrations
nexus-orchestrator, nexus-workflows nexus-orchestrator-migrations
nexus-gateway nexus-gateway-migrations
nexus-graphrag nexus-graphrag-migrations
nexus-probitas nexus-probitas-migrations
nexus-skills-engine nexus-db-bootstrap
nexus-alpha-bff nexus-alpha-bff-migrations

For å følge med på en tjenestes ventetid mens det skjer, kan du lese loggen til init-kontaineren dens:

kubectl -n nexus logs deploy/nexus-auth -c wait-for-schema
wait-for-schema: nexus-auth waits for nexus_release.schema_applied (read as nexus_ledger_reader) to show: nexus-auth-migrations; gives up after 1800s
wait-for-schema: ready after 212s: the release ledger shows nexus-auth-migrations

Fordi ventingen er knyttet til avbildningens sjekksum, og ikke til et antall filer, vil poddene ved en senere oppgradering vente på den nye utgivelsens rader, og en podd som starter på nytt etter en endring som kun gjelder verdier, finner raden sin med det samme.

Trinn 7: vent på hver arbeidsbelastning

Vent på Deployments, med en tidsgrense:

kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s
deployment.apps/nexus-alpha condition met
deployment.apps/nexus-alpha-bff condition met
deployment.apps/nexus-auth condition met
deployment.apps/nexus-gateway condition met
deployment.apps/nexus-graphrag condition met
deployment.apps/nexus-keys condition met
deployment.apps/nexus-orchestrator condition met
deployment.apps/nexus-probitas condition met
deployment.apps/nexus-skills-engine condition met
deployment.apps/nexus-workflows condition met

Deretter StatefulSets. De to nøkkellagerserverne oppdateres bare når du sletter poddene deres, og kubectl rollout status avviser den oppdateringsstrategien, så vent på antallet som er klare (ready) i stedet:

for s in $(kubectl -n nexus get statefulset -o name); do
  kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'=1 --timeout=900s
done

Hver av dem skriver ut condition met. På klyngen vår tok begge ventetidene til sammen under fem minutter etter at Helm var ferdig.

Hvordan klart ser ut

kubectl -n nexus get deploy,statefulset
NAME                                  READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/nexus-alpha           1/1     1            1           14m
deployment.apps/nexus-alpha-bff       1/1     1            1           14m
deployment.apps/nexus-auth            1/1     1            1           14m
deployment.apps/nexus-gateway         1/1     1            1           14m
deployment.apps/nexus-graphrag        1/1     1            1           14m
deployment.apps/nexus-keys            1/1     1            1           14m
deployment.apps/nexus-orchestrator    1/1     1            1           14m
deployment.apps/nexus-probitas        1/1     1            1           14m
deployment.apps/nexus-skills-engine   1/1     1            1           14m
deployment.apps/nexus-workflows       1/1     1            1           14m

NAME                                READY   AGE
statefulset.apps/nexus-neo4j        1/1     14m
statefulset.apps/nexus-postgres     1/1     14m
statefulset.apps/nexus-qdrant       1/1     14m
statefulset.apps/nexus-seaweedfs    1/1     14m
statefulset.apps/nexus-valkey       1/1     14m
statefulset.apps/openbao            1/1     14m
statefulset.apps/openbao-unsealer   1/1     14m

Ti Deployments og sju StatefulSets, alle sammen klare. Ved siden av dem finner du tre CronJobs, nexus-keys-rotate-epoch, nexus-keys-run-schedule og nexus-keys-export-receipts, som er nøkkeltjenestens nattlige vedlikehold. kubectl -n nexus get jobs skal ikke liste opp noen hook-Jobs: de som lyktes, ble slettet.

Det er to ting det er verdt å gjøre før du forlater terminalen. Lagre (commit) verdifilen der teamet ditt oppbevarer konfigurasjon; hver oppgradering tar utgangspunkt i den. Og la Secret-ressursen nexus-generated være i fred. Chartet genererer de interne passordene og nøklene én gang, ved installasjon, oppbevarer dem der og leser dem tilbake ved hver oppgradering, så hvis du sletter den, vil ikke tjenestene lenger få tilgang til sine egne data.

Klar betyr at plattformen kjører og at ingen har gjort krav på den. Åpne https://console.harrow.example, så kommer du til installasjonsveiviseren, ikke en innloggingsside: ingen kan logge inn før noen gjør krav på installasjonen. Det er den første kjøringen, i kapittel 2.12, Den første kjøringen.

Denne installasjonen (Community)
Denne installasjonen (Community)
En Community-installasjons egen side når det er gjort krav på den: versjonen som kjører, motorens helsetilstand, diskbruk, sikkerhetskopier og løftet om sikkerhetsfeilrettinger, med Enterprise-delene vist som smakebiter som oppgir hvem som kan slå dem på.

Hvis dette feiler

De fleste feil forklarer seg selv. Les meldingen før du endrer noe.

Hva dere ser Årsak Hva du skal gjøre
INSTALLATION_NAME_MISSING eller INSTALLATION_NAME_EXAMPLE keys.installationName er tom eller inneholder eksempelverdien Angi ditt eget permanente navn
KEYS_CUSTODIAN_MISSING eller KEYS_CUSTODIAN_EXAMPLE Ingen nøkkelforvaltere, eller eksempelverdien Angi nøkkelforvalternes egne mottakere
keys.installationName ... does not match ^[a-z][a-z0-9-]{0,62}$ Store bokstaver, punktum eller et innledende siffer Bruk små bokstaver, sifre og bindestreker, og start med en bokstav
keys.custody.recipients: ... og en årsak En mottaker er feilskrevet, er en privat nøkkel, eller har et format forvaltningsjobben ikke kan kryptere til Be nøkkelforvalteren om mottakeren på nytt
hosts.console is required (the installation identity) En vert er ikke satt Angi alle de tre vertene
tls.existingSecret is required when tls.mode is existing Ingen Secret er navngitt Angi den, eller endre tls.mode
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read Kontoen din kan ikke lese API-serverens adresser Oppgi dem som /32-områder
global.imageRegistry is required Registeret er ikke satt Angi det
Helm blir stående til tidsavbruddet; nexus-auth logger password authentication failed --wait ble oppgitt Avinstaller og installer på nytt uten --wait
Error: ... job failed som navngir en hook En migrering feilet kubectl -n nexus logs job/<hook-name> og les de siste linjene
En podd står fast i Init Dens wait-for-schema venter fortsatt Les loggen dens: den navngir kjeden den mangler
wait-for-schema: FAILED Kjedens hook skrev aldri raden sin Finn feilen i den hooken først
ImagePullBackOff Noden kan ikke hente fra global.imageRegistry Sjekk at noden kan nå registeret og, for Enterprise, at den har pull-tokenet

Hver hook som venter på PostgreSQL, venter en begrenset tid og sier fra om det, waiting for postgres (12/60), så en database som har hengt seg opp, vises i hookens logg i løpet av et minutt.

Installasjonsveien med nexusctl

nexusctl install gjør den samme installasjonen, men kjører kontrollene rundt den for deg. Den tar den samme verdifilen:

nexusctl install --context harrow-prod --values harrow-values.yaml

Den kjører forhåndskontrollen på nytt og stopper hvis en kontroll har begynt å feile. Den verifiserer chart-pakkens signatur mot utgivelsesnøkkelen. Deretter installerer den, venter gjennom hookene og arbeidsbelastningene, og skriver ut hvert trinn med hvor lang tid det tok. --edition community angir utgaven på kommandolinjen i tillegg til i filen. --ca-bundle <file> legger til dine egne CA-sertifikater, på samme måte som ved forhåndskontrollen. For å se helm- og kubectl-operasjonene den ville kjørt, uten å kjøre dem, legg til --explain:

nexusctl install --context harrow-prod --values harrow-values.yaml --explain

Når den er ferdig, skriver den ut kravadressen, en engangskode for å gjøre krav på installasjonen (claim code) og installasjonens fingeravtrykk:

Installed in <time>. Nobody can sign in yet.

  Open   https://console.harrow.example/claim
  Code   <code>          works once, for 30 minutes
  Fingerprint of this installation, to compare in the browser:
         <eight groups of four>

Koden har tre grupper og tillater fem forsøk; fingeravtrykket består av åtte grupper på fire tegn, og nettleseren viser de samme åtte gruppene slik at du kan sammenligne dem før du gjør krav på installasjonen.

Installerer
Installerer
Installasjonen som kjører i operatørens terminal. Hvert trinn skrives ut med tidsbruk, og kjøringen avsluttes med en engangskode og installasjonens fingeravtrykk; ingen kan logge inn før det er gjort krav på installasjonen i en nettleser.

Overgang til første oppstart

Hvis du installerte med Helm, lager du kravkoden selv, og navngir personen som skal være den første administratoren:

nexusctl claim-code --administrator aoife.brennan@harrow.example

Den kjører nøkkeltjenestens egen kommando for kravkode i nexus-keys-podden med klyngetilgangen din, og skriver ut adressen, koden og fingeravtrykket som ovenfor. Koden fungerer i 30 minutter; kjør kommandoen på nytt for å få en ny.

Herfra tar nettleseren over: gjør krav på installasjonen, opprett den første administratoren med en passnøkkel (passkey), og gå gjennom de seks punktene før noen logger inn. Det er kapittel 2.12, Den første kjøringen. Hvis du skal lisensiere Enterprise med det samme, bør du lese kapittel 2.7, Installere Enterprise og legge inn en lisens, først, fordi lisensen er ett av disse seks punktene.