Log indBook en briefing

Kapitel 2.6

Installation af Community på Kubernetes

En nummereret installation af Community-udgaven med Helm, fra cert-manager til hver workload er klar, med values-filen forklaret nøgle for nøgle, hvorfor der ikke bruges --wait, rækkefølgen chartets hooks kører i, samt installationsvejen med nexusctl som et alternativ.

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

Selve installationen er én helm install. Alt omkring den er der, så den ene kommando virker første gang: cert-manager før den, en values-fil, De har læst linje for linje, og en ventetid bagefter, der ved, hvad den skal vente på. Hos Harrow Port Authority installerede vi først Community til et seks ugers pilotprojekt på den k3s-klynge med tre noder fra vores planlægningsark. Udgivelsen kørte på cirka tyve minutter, og ingen kunne logge ind, før vi gjorde krav på den, hvilket er sådan, det skal være.

Dette kapitel forudsætter, at De allerede har gjort tre ting: gennemarbejdet planlægningsarket (kapitel 2.3, Planlægning af en installation), hentet og kontrolleret udgivelsen (kapitel 2.4, Hentning og verificering af en udgivelse) og kørt forhåndskontrollen (kapitel 2.5, Forhåndskontrol med nexusctl). Hvis nogen af disse stadig udestår, skal De gå tilbage. Installationen afviser de fleste fejl ved navn, men nogle få – som en nøgleforvalter, hvis nøgle De allerede har mistet – kan den ikke se.

Trin 1: Bekræft dine værktøjer og din kontekst

  1. Kontrollér, at Helm er version 4.

    helm version

    Installationen er afhængig af, at Helm 4 som standard venter på chartets hook-Jobs. Vi brugte v4.3.1.

  2. Peg kubectl mod klyngen på Deres planlægningsark, og bekræft det.

    kubectl config use-context harrow-prod
    kubectl get nodes

    Hver node bør melde Ready. Forhåndskontrollen tjekkede allerede dette, men en node kan falde ud mellem forhåndskontrollen og installationen, og det er hurtigere at se det her.

Trin 2: Installér cert-manager først

Chartet opretter sin egen lokale certifikatautoritet (CA) med cert-manager, og hver tjeneste kommunikerer med de andre ved hjælp af certifikater, den udsteder: en selvsigneret Issuer, et tiårigt lokalt CA-certifikat og kortlivede certifikater til tjenesterne. Derfor skal cert-manager køre før Nexus. Udgivelsen kræver v1.21.3, og den behøver ingen trust-manager.

  1. Installér cert-manager fra dets eget chart med dets tilpassede ressourcer:

    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-projektets egen udgivelse. Her er det rigtigt at vente; det er cert-managers egen installation uden hooks, der afhænger af noget andet.

  2. Vent på dets webhook, som hver certifikatanmodning går igennem:

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

Trin 3: Opret namespacet og TLS-Secret

Med tls.mode: existing forventer chartet Deres certifikat som en Kubernetes Secret i namespacet før installationen. Transport Layer Security (TLS) for alle tre adresser kommer fra denne ene Secret, så dens certifikat skal angive alle tre værter.

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 certifikatet med dets kæde, og harrow-public.key er dets private nøgle. Hvis De valgte tls.mode: cert-manager eller none i kapitel 2.3, Planlægning af en installation, skal De springe denne Secret over; De kan stadig oprette namespacet nu eller lade Helm gøre det med --create-namespace i trin 6.

Trin 4: Skriv values-filen

Dette er Harrows values-fil til pilotprojektet. Hver nøgle i den er en nøgle, som chartets skema accepterer; skemaet afviser enhver anden, så en forkert stavet nøgle får installationen til at fejle i stedet for at blive ignoreret i stilhed.

# 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øgleforvalters offentlige age-modtager, den age1...- eller age1se1...-linje, de sendte til Dem. Her er hver nøgle, vi angav, og hvorfor.

global.imageRegistry er det registry, Deres noder henter fra. Chartet har ingen standardværdi; det opbygger hvert image som <this>/nexus/<service>@<digest>. For en tilsluttet installation er det registry.adverant.ai. Hvis De kopierede disse images ind i Deres eget registry, er det den pågældende vært.

global.domain er det domæne, de tre adresser hører under.

hosts.console, hosts.api og hosts.auth er installationens identitet: de tre navne, som personer og programmer bruger. Hvert af dem skal allerede kunne slås op i Domain Name System (DNS), hvilket forhåndskontrollen tjekkede.

edition og enterprise.enabled skal stemme overens: community med false eller enterprise med true. Chartet afviser alt andet, og det afviser en udgave, som dets image-lås ikke er lavet til.

tls.mode og tls.existingSecret vælger, hvordan den offentlige kant får sit certifikat. Med cert-manager ville De angive tls.clusterIssuer i stedet, og med none ingen af dem.

ingress.className angiver ingress-klassen. Lad den være uindstillet for at bruge klyngens standardklasse.

storage.className angiver storage-klassen for hvert datavolumen. Lad den være uindstillet for at bruge standarden.

networkPolicy.ingressNamespace er det namespace, Deres ingress-controller kører i. Standarden, kube-system, er korrekt for k3s' Traefik; vi angav den alligevel, så det fremgår tydeligt af filen.

networkPolicy.externalEgressCIDRs angiver adresseområder i Classless Inter-Domain Routing (CIDR)-notation uden for det namespace, som tjenesterne må tilgå, ud over DNS og Kubernetes' application programming interface (API)-server. Vores indeholder mail-relayets enkelte adresse; hvis listen er tom, kan intet uden for namespacet nås.

keys.installationName er det permanente navn, som nøglelageret udsteder installationsidentiteten under.

keys.custody.recipients oplister nøgleforvalternes offentlige age-modtagere. Nøgleforvaltnings-Jobbet krypterer hver unseal-andel og gendannelsesnøgle til hver af dem.

Nøgler, De kan få brug for, og nøgler, De skal lade være

Nøgle Hvornår den skal angives
networkPolicy.apiServerCIDRs Når chartet ikke kan læse API-serverens adresser fra kubernetes-Endpoints. Angiv dem som /32-områder
proxy.trustedCIDRs Når Deres ingress-controllers pods ikke er på k3s' 10.42.0.0/16
ai.localProvider.baseUrl Når organisationen kører sin egen OpenAI-kompatible modelserver til kunstig intelligens (AI) (kapitel 2.14, AI-udbydere og -modeller)
ai.installationHosts Når den pågældende modelserver ligger på private navne internt i installationen
dataTier.<store>.size Når et lager har brug for mere end sit standardvolumen
dataTier.<store>.mode external for et lager, De selv driver (kapitel 2.11, Variationer: eksterne lagre, TLS og ingress)
components.<service>.replicas, components.<service>.resources Når De opjusterer størrelsen på en tjeneste
auth.rateLimitPerMinute Når omfattende automatisering kræver mere end 5.000 forespørgsler i minuttet pr. person
schemaWait.timeoutSeconds Når en langsom disk får de første migreringer til at tage mere end 30 minutter

Lad istio.enabled stå på false; Nexus behøver intet service mesh. Lad telemetry.enabled stå på false; skemaet accepterer ingen anden værdi. Lad orchestrator.platformServiceUserId og probitas.flags være, som chartet indstiller dem.

Ingen legitimationsoplysninger er nogensinde en chart-værdi. Der er ingen nøgle til en modeludbyders API-nøgle, en mailadgangskode eller et pull-token. Tjenesterne genererer deres egne interne hemmeligheder ved installationen og beholder dem ved opgradering, og hver organisations modelnøgler lægges i dens egen nøglepulje fra konsollen efter den første kørsel.

Trin 5: Kør forhåndskontrol mod den endelige fil

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

Kørslen skal slutte med 0 failed. Kapitel 2.5, Forhåndskontrol med nexusctl, forklarer hver række. Hvis De har ændret noget siden sidste kørsel, selv en størrelse, skal De køre den igen.

Trin 6: Installér uden --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 De ikke oprettede namespacet i trin 3, skal De tilføje --create-namespace. Hvis De installerer fra en chart-fil, som De har downloadet og kontrolleret, skal De indsætte dens sti i stedet for oci://-referencen.

Tilføj ikke --wait. Chartets database-bootstrap kører som et post-install-hook, efter at udgivelsens egne ressourcer eksisterer, og det er dette hook, der giver hver tjeneste dens databaserolle og adgangskode. --wait ville tilbageholde installationen, indtil hvert Deployment er Available, og intet Deployment kan blive Available, før det hook, det venter på, har kørt. Tjenesterne sidder og får afvist deres databaselogins, og Helm venter på dem indtil timeout. Uden --wait venter Helm 4 stadig på hvert hook-Job i rækkefølge, og det er den ventetid, De ønsker.

Når det sidste hook er færdigt, udskriver Helm sin oversigt:

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

STATUS: deployed betyder, at hvert hook lykkedes. Det betyder endnu ikke, at hver tjeneste er klar til at betjene; det venter trin 7 på.

Hvad der kører, og i hvilken rækkefølge

Helm kører sine hooks efter vægt med den laveste først og venter på hvert enkelt før det næste. Hvert migrerings-Job har backoffLimit: 0: en mislykket migrering får installationen til at fejle og forsøges aldrig igen bag Deres ryg. Et Job, der lykkes, slettes; et Job, der fejler, bliver liggende med sin log, så De kan læse den.

Vægt Hook Hvad den gør
-30 Forudsætninger Hook-kontoen nexus-migrations, den hook-specifikke Secret nexus-migrations-env med de genererede databaselegitimationsoplysninger samt nøgleforvaltnings-Jobbets konto, rolle, konfiguration og certifikat
-20 nexus-db-bootstrap Opretter databaserne og rollerne, hvoraf ingen er superbruger, og ingen kan omgå sikkerhed på rækkeniveau (RLS); tilføjer udvidelserne, herunder PostGIS og pgvector; opretter udgivelsesprotokollen
-15 nexus-openbao-custody-init Initialiserer nøglelageret og dets unsealer, krypterer andelene og gendannelsesnøglerne til Deres nøgleforvaltere, tilbagekalder begge root-tokens og udsteder installationsidentiteten under keys.installationName
-12 nexus-graphrag-migrations Udlægger først graftjenestens skema, fordi logintjenestens skema henviser til objekter, den ejer
-10 nexus-auth-migrations Udlægger logintjenestens skema og dens to runtime-roller
-5 nexus-orchestrator-migrations, nexus-gateway-migrations, nexus-probitas-migrations Hver tjenestes eget skema; probitas kører efter auth, fordi den kontrollerer auths tabeller først
0 nexus-alpha-bff-migrations Klargør backend for frontend (BFF)-databasen og dens roller og anvender derefter dens migreringer

Hvert migrerings-hook slutter med at skrive én række i udgivelsesprotokollen, nexus_release.schema_applied: navnet på dets kæde og digestet for det image, der kørte det. Det skriver først denne række, efter at dets migreringskørsel er afsluttet uden fejl. Bootstrap-Jobbet udskriver db-bootstrap: done; SQL-migrerings-hooksene udskriver schema-ledger: recorded <chain> for this release's image som deres sidste linje. Konsollens eget migrerings-hook, nexus-alpha-bff-migrations, registrerer sin række på samme måde og udskriver derefter bff-migrate: done.

En vandret tidslinje fra venstre mod højre med teksten "helm install". På det øverste spor er der syv hook-bokse i rækkefø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 lille pil ned til en cylinder på et midterste spor med teksten "release ledger: nexus_release.schema_applied". På det nederste spor er der en lang bjælke, der starter til venstre med teksten "Deployments start, wait-for-schema holds each pod"; korte lodrette pile går fra den op til protokollen, og hver Deployments bjælke bliver udfyldt, når dens egen række i protokollen dukker op.
Rækkefølgen for en ny installation med hooks og workloads side om side.

Hvordan tjenesterne venter på deres skema

Deployments starter, så snart Helm opretter dem, mens hooks stadig kører. En tjeneste, der startede mod en database uden rolle, uden adgangskode eller uden skema, ville gå ned og genstarte, indtil disse hooks var færdige. Derfor har hver Deployment, der bruger databasen, en init-container, wait-for-schema, som i stedet holder pod'en tilbage.

Den læser udgivelsesprotokollen som nexus_ledger_reader, et login, der kun kan læse den ene tabel og intet andet, og venter, indtil protokollen viser dens kæder for denne udgivelses image-digests. Den forespørger for hver schemaWait.intervalSeconds (3 som standard), udskriver sin tilstand, når den ændrer sig, og ved hver tyvende forespørgsel, og giver op efter schemaWait.timeoutSeconds (1.800 som standard) med en fejl, der angiver tjenestens navn.

Udrulning 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 at følge en tjenestes ventetid, mens den finder sted, kan du læse dens init-containers log:

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 ventetiden er knyttet til image-digestet og ikke til et antal filer, venter pods ved en senere opgradering på den nye udgivelses rækker, og en pod, der genstarter efter en ændring kun i values, finder sin række med det samme.

Trin 7: Vent på hver workload

Vent på Deployments med en tidsgrænse:

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

Dernæst StatefulSets. De to nøglelagerservere opdateres kun, når du sletter deres pods, og kubectl rollout status afviser den opdateringsstrategi, så vent i stedet på antallet af klar-meldinger:

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 af dem udskriver condition met. På vores klynge tog begge ventetider tilsammen under fem minutter, efter at Helm returnerede.

Hvordan det ser ud, når alt er klar

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 syv StatefulSets, hver især klar. Ved siden af dem finder du tre CronJobs, nexus-keys-rotate-epoch, nexus-keys-run-schedule og nexus-keys-export-receipts, nøgletjenestens natlige vedligeholdelse. kubectl -n nexus get jobs bør ikke vise nogen hook-Jobs: De gennemførte blev slettet.

To ting er værd at gøre, før du forlader terminalen. Commit values-filen til det sted, hvor dit team opbevarer konfiguration; hver opgradering starter ud fra den. Og lad Secret-objektet nexus-generated være i fred. Chartet genererer de interne adgangskoder og nøgler én gang ved installationen, opbevarer dem der og indlæser dem igen ved hver opgradering, så hvis du sletter det, vil tjenesterne ikke kunne tilgå deres egne data.

Klar betyder, at platformen kører og er uovertaget. Åbn https://console.harrow.example, og du kommer til installationsprogrammet, ikke en loginsiden: Ingen kan logge ind, før nogen overtager installationen. Det er den første kørsel i kapitel 2.12, Den første kørsel.

Denne installation (Community)
Denne installation (Community)
En Community-installations egen side, når den er overtaget: den kørende version, motorens tilstand, diskforbrug, sikkerhedskopier og løftet om sikkerhedsrettelser, hvor Enterprise-delene vises som forsmag, der angiver, hvem der kan slå dem til.

Hvis dette fejler

De fleste fejl angiver selv årsagen. Læs meddelelsen, før du ændrer noget.

Hvad du ser Årsag Hvad du skal gøre
INSTALLATION_NAME_MISSING eller INSTALLATION_NAME_EXAMPLE keys.installationName er tom eller eksempelværdien Angiv dit eget permanente navn
KEYS_CUSTODIAN_MISSING eller KEYS_CUSTODIAN_EXAMPLE Ingen nøgleforvaltere eller kun eksemplet Angiv dine nøgleforvalteres egne modtagere
keys.installationName ... does not match ^[a-z][a-z0-9-]{0,62}$ Store bogstaver, punktummer eller et foranstillet ciffer Brug små bogstaver, cifre og bindestreger, startende med et bogstav
keys.custody.recipients: ... og en årsag En modtager er stavet forkert, er en privat nøgle eller har et format, som nøgleforvaltnings-Jobbet ikke kan kryptere til Bed nøgleforvalteren om vedkommendes modtager igen
hosts.console is required (the installation identity) En vært er ikke angivet Angiv alle tre værter
tls.existingSecret is required when tls.mode is existing Intet Secret-objekt navngivet Angiv det, eller skift tls.mode
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read Din konto kan ikke læse API-serverens adresser Angiv dem som /32-intervaller
global.imageRegistry is required Registret er ikke angivet Angiv det
Helm venter indtil sin timeout; nexus-auth logger password authentication failed --wait blev angivet Afinstaller, og installer igen uden --wait
Error: ... job failed, der nævner et hook En migrering mislykkedes kubectl -n nexus logs job/<hook-name>, og læs de sidste linjer
En pod sidder fast i Init Dens wait-for-schema venter stadig Læs dens log: Den nævner den kæde, den mangler
wait-for-schema: FAILED Kædens hook skrev aldrig sin række Find først fejlen for det pågældende hook
ImagePullBackOff Noden kan ikke hente fra global.imageRegistry Kontrollér, at noden kan nå registret og, for Enterprise, har pull-tokenet

Hvert hook, der venter på PostgreSQL, venter i en afgrænset tid og oplyser det, waiting for postgres (12/60), så en fastlåst database vises i hookets log inden for et minut.

Installationsvejen med nexusctl

nexusctl install udfører den samme installation, hvor kontrollerne omkring den køres for dig. Den bruger den samme values-fil:

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

Den kører forhåndskontrollen igen og stopper, hvis en kontrol er begyndt at fejle. Den verificerer chart-bundtets signatur mod udgivelsesnøglen. Derefter installerer den, venter gennem hooks og workloads og udskriver hvert trin med tidsforbruget. --edition community angiver udgaven på kommandolinjen såvel som i filen. --ca-bundle <file> tilføjer dine egne CA-certifikater, på samme måde som ved forhåndskontrollen. For at se de helm- og kubectl-handlinger, den ville køre, uden at køre dem, skal du tilføje --explain:

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

Når den er færdig, udskriver den overtagelsesadressen, en engangskode til overtagelse og installationens fingeraftryk:

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 tillader fem forsøg; fingeraftrykket er otte grupper på fire tegn, og browseren viser de samme otte grupper, så du kan sammenligne dem, før du overtager installationen.

Installerer
Installerer
Installationen kører i operatørens terminal. Hvert trin udskrives med sit tidsforbrug, og kørslen slutter med en engangskode og installationens fingeraftryk; ingen kan logge ind, før installationen er overtaget i en browser.

Overdragelse til første kørsel

Hvis du installerede med Helm, skal du selv oprette overtagelseskoden og angive den person, der skal være den første administrator:

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

Den kører nøgletjenestens egen kommando til overtagelseskode i nexus-keys-pod'en med din klyngeadgang og udskriver adressen, koden og fingeraftrykket som ovenfor. Koden virker i 30 minutter; kør den igen for at få en ny.

Herfra tager browseren over: Overtag installationen, opret den første administrator med en adgangsnøgle, og gennemgå de seks punkter, før nogen logger ind. Det er kapitel 2.12, Den første kørsel. Hvis du vil licensere Enterprise med det samme, skal du først læse kapitel 2.7, Installation af Enterprise og anvendelse af en licens, fordi licensen er et af disse seks punkter.