Logga inBoka en genomgång

Kapitel 2.6

Installera Community på Kubernetes

En steg-för-steg-installation av Community-utgåvan med Helm, från cert-manager till att varje workload är redo, med values-filen förklarad nyckel för nyckel, varför --wait inte används, i vilken ordning chartets hooks körs samt installationsvägen via nexusctl som ett alternativ.

Denna sida har översatts av AI från det engelska originalet. Om något är oklart är den engelska sidan referensen. Läs denna sida på engelska

18 minuters läsning

Själva installationen är ett enda helm install. Allt runt omkring den finns där för att detta enda kommando ska fungera på första försöket: cert-manager före det, en values-fil som du har läst rad för rad och en väntan efteråt som vet vad den ska vänta på. På Harrow Port Authority installerade vi Community först, för en sex veckor lång pilot, på det k3s-kluster med tre noder som fanns i vårt planeringsunderlag. Releasen körde på ungefär tjugo minuter, och ingen kunde logga in förrän vi gjorde anspråk på den, vilket är precis som det ska vara.

Det här kapitlet förutsätter att du redan har gjort tre saker: arbetat igenom planeringsunderlaget (kapitel 2.3, Planera en installation), hämtat och kontrollerat releasen (kapitel 2.4, Hämta och verifiera en release) samt kört förkontrollen (kapitel 2.5, Förkontroll med nexusctl). Om någon av dessa punkter fortfarande är ogjord, gå tillbaka. Installationen avvisar de flesta misstag vid namn, men några få, som en nyckelförvaltare vars nyckel du redan har tappat bort, kan den inte se.

Steg 1: bekräfta era verktyg och er kontext

  1. Kontrollera att Helm är version 4.

    helm version

    Installationen förlitar sig på att Helm 4 som standard väntar på chartets hook-Jobs. Vi använde v4.3.1.

  2. Peka kubectl mot klustret i ditt planeringsunderlag och bekräfta det.

    kubectl config use-context harrow-prod
    kubectl get nodes

    Varje nod ska visa Ready. Förkontrollen kontrollerade redan detta, men en nod kan falla bort mellan förkontrollen och installationen, och det går snabbare att se det här.

Steg 2: installera cert-manager först

Chartet skapar sin egen lokala certifikatutfärdare (CA) med cert-manager, och varje tjänst kommunicerar med de andra med certifikat som den utfärdar: en självsignerad Issuer, ett tioårigt lokalt CA-certifikat och kortlivade certifikat för tjänsterna. Därför måste cert-manager köra före Nexus. Releasen kräver v1.21.3, och den behöver inte trust-manager.

  1. Installera cert-manager från dess eget chart, med dess anpassade resurser:

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

    <cert-manager-chart> är chartet för cert-manager v1.21.3 från cert-manager-projektets egen release. Att vänta är rätt här; det är cert-managers egen installation, utan hooks som är beroende av något annat.

  2. Vänta på dess webhook, som varje certifikatbegäran går igenom:

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

Steg 3: skapa namnrymden och TLS-Secret

Med tls.mode: existing förväntar sig chartet ditt certifikat som en Kubernetes Secret i namnrymden före installationen. Transport Layer Security (TLS) för alla tre adresser kommer från denna enda Secret, så dess certifikat måste namnge alla tre värdar.

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

harrow-public.crt är certifikatet, med dess kedja, och harrow-public.key är dess privata nyckel. Om du valde tls.mode: cert-manager eller none i kapitel 2.3, Planera en installation, hoppar du över denna Secret; du kan ändå skapa namnrymden nu, eller låta Helm göra det med --create-namespace i steg 6.

Steg 4: skriv values-filen

Det här är Harrows values-fil för piloten. Varje nyckel i den är en nyckel som chartets schema accepterar; schemat avvisar alla andra, så en felstavad nyckel gör att installationen misslyckas i stället för att tyst ignoreras.

# 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>"

Varje <recipient-...> är en nyckelförvaltares publika age-mottagare, den age1...- eller age1se1...-rad som de skickade till dig. Här är varje nyckel vi angav, och varför.

global.imageRegistry är registret som dina noder hämtar från. Chartet har inget standardvärde; det bygger varje avbildning som <this>/nexus/<service>@<digest>. För en uppkopplad installation är det registry.adverant.ai. Om du kopierade avbildningarna till ditt eget register är det den värden.

global.domain är domänen som de tre adresserna ligger under.

hosts.console, hosts.api och hosts.auth är installationens identitet: de tre namn som människor och program använder. Var och en måste redan gå att slå upp i Domain Name System (DNS), vilket förkontrollen kontrollerade.

edition och enterprise.enabled måste stämma överens: community med false, eller enterprise med true. Chartet avvisar allt annat, och det avvisar en utgåva som dess avbildningslås inte skapades för.

tls.mode och tls.existingSecret väljer hur den publika kanten får sitt certifikat. Med cert-manager anger du tls.clusterIssuer i stället, och med none ingendera.

ingress.className namnger ingress-klassen. Lämna den oangiven för att använda klustrets standardklass.

storage.className namnger lagringsklassen för varje datavolym. Lämna den oangiven för att använda standardklassen.

networkPolicy.ingressNamespace är namnrymden som din ingress-controller körs i. Standardvärdet, kube-system, är rätt för Traefik i k3s; vi angav det ändå så att det står uttryckligen i filen.

networkPolicy.externalEgressCIDRs listar adressintervall, i Classless Inter-Domain Routing-notation (CIDR), utanför namnrymden som tjänsterna får nå, utöver DNS och Kubernetes-servern för applikationsprogrammeringsgränssnitt (API). Vår innehåller e-postreläets enda adress; om listan är tom kan ingenting utanför namnrymden nås.

keys.installationName är det permanenta namn som nyckellagret utfärdar installationsidentiteten under.

keys.custody.recipients listar nyckelförvaltarnas publika age-mottagare. Custody-Job krypterar varje upplåsningsandel och återställningsnyckel till var och en av dem.

Nycklar du kan behöva och nycklar du ska låta bli

Nyckel När den ska anges
networkPolicy.apiServerCIDRs När chartet inte kan läsa API-serverns adresser från kubernetes Endpoints. Ange dem som /32-intervall
proxy.trustedCIDRs När din ingress-controllers poddar inte ligger på 10.42.0.0/16 i k3s
ai.localProvider.baseUrl När organisationen kör sin egen OpenAI-kompatibla modellserver för artificiell intelligens (AI) (kapitel 2.14, AI-leverantörer och modeller)
ai.installationHosts När den modellservern ligger på privata namn inuti installationen
dataTier.<store>.size När ett lager behöver mer än sin standardvolym
dataTier.<store>.mode external för ett lager du kör själv (kapitel 2.11, Variationer: externa lager, TLS och ingress)
components.<service>.replicas, components.<service>.resources När du skalar upp en tjänst
auth.rateLimitPerMinute När tung automatisering kräver mer än 5 000 anrop i minuten per person
schemaWait.timeoutSeconds När en långsam disk gör att de första migreringarna tar mer än 30 minuter

Lämna istio.enabled som false; Nexus behöver inget service mesh. Lämna telemetry.enabled som false; schemat accepterar inget annat värde. Lämna orchestrator.platformServiceUserId och probitas.flags som chartet anger dem.

Inga inloggningsuppgifter är någonsin ett chart-värde. Det finns ingen nyckel för en modelleverantörs API-nyckel, ett e-postlösenord eller en pull-token. Tjänsterna genererar sina egna interna hemligheter vid installationen och behåller dem vid uppgradering, och varje organisations modellnycklar läggs in i dess egen nyckelpool från konsolen efter första körningen.

Steg 5: kör förkontrollen mot den slutliga filen

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

Körningen måste avslutas med 0 failed. Kapitel 2.5, Förkontroll med nexusctl, förklarar varje rad. Om du har ändrat något sedan den senaste körningen, även en storlek, kör den igen.

Steg 6: installera, utan --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

Om du inte skapade namnrymden i steg 3, lägg till --create-namespace. Om du installerar från en chart-fil som du har laddat ner och kontrollerat, ange dess sökväg i stället för oci://-referensen.

Lägg inte till --wait. Chartets databas-bootstrap körs som en post-install-hook, efter att releasens egna resurser har skapats, och det är den hooken som ger varje tjänst dess databasroll och lösenord. --wait skulle hålla kvar installationen tills varje Deployment är Available, och ingen Deployment kan bli Available innan den hook som den väntar på har körts. Tjänsterna blir stående och får sina databasinloggningar avvisade, och Helm väntar på dem tills tidsgränsen löper ut. Utan --wait väntar Helm 4 ändå på varje hook-Job, i ordning, och det är den väntan du vill ha.

När den sista hooken är klar skriver Helm ut sin sammanfattning:

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

STATUS: deployed betyder att varje hook lyckades. Det betyder ännu inte att varje tjänst betjänar anrop; steg 7 väntar på det.

Vad som körs, och i vilken ordning

Helm kör hookarna efter vikt, lägst först, och väntar på var och en före nästa. Varje migrerings-Job har backoffLimit: 0: en misslyckad migrering gör att installationen misslyckas och försöks aldrig igen bakom din rygg. Ett Job som lyckas tas bort; ett Job som misslyckas blir kvar, med sin logg, så att du kan läsa den.

Vikt Hook Vad den gör
-30 Förutsättningar Hook-kontot nexus-migrations, den hook-exklusiva Secreten nexus-migrations-env med de genererade databasuppgifterna samt custody-Jobets konto, roll, konfiguration och certifikat
-20 nexus-db-bootstrap Skapar databaserna och rollerna, där ingen av dem är superanvändare och ingen kan kringgå säkerhet på radnivå (RLS); lägger till tilläggen, däribland PostGIS och pgvector; skapar releaseliggarna
-15 nexus-openbao-custody-init Initierar nyckellagret och dess upplåsare, krypterar andelarna och återställningsnycklarna till dina nyckelförvaltare, återkallar båda rot-tokens och utfärdar installationsidentiteten under keys.installationName
-12 nexus-graphrag-migrations Lägger ut graftjänstens schema först, eftersom inloggningstjänstens schema refererar till objekt som den äger
-10 nexus-auth-migrations Lägger ut inloggningstjänstens schema och dess två körtidsroller
-5 nexus-orchestrator-migrations, nexus-gateway-migrations, nexus-probitas-migrations Varje tjänsts eget schema; probitas körs efter auth eftersom den kontrollerar auths tabeller först
0 nexus-alpha-bff-migrations Provisionerar databasen för backend for frontend (BFF) och dess roller, och tillämpar sedan dess migreringar

Varje migrerings-hook avslutas med att skriva en rad i releaseliggarna, nexus_release.schema_applied: namnet på dess kedja och kontrollsumman (digest) för den avbildning som körde den. Den skriver den raden först efter att dess migreringskörare har slutförts utan fel. Bootstrap-Jobet skriver ut db-bootstrap: done; SQL-migreringshookarna skriver ut schema-ledger: recorded <chain> for this release's image som sin sista rad. Konsolens egen migrerings-hook, nexus-alpha-bff-migrations, registrerar sin rad på samma sätt och skriver sedan ut bff-migrate: done.

En horisontell tidslinje som löper från vänster till höger, märkt "helm install". På det övre spåret finns sju hook-rutor i ordning: "-30 prerequisites", "-20 db-bootstrap", "-15 custody init", "-12 graphrag migrations", "-10 auth migrations", "-5 orchestrator, gateway, probitas migrations", "0 BFF migrations". Varje migreringsruta har en liten pil nedåt till en cylinder på ett mellanspår märkt "release ledger: nexus_release.schema_applied". På det nedre spåret finns en lång stapel som börjar till vänster märkt "Deployments start, wait-for-schema holds each pod"; korta vertikala pilar går upp från den till liggaren, och varje Deployments stapel blir heldragen när dess egen rad i liggaren dyker upp.
Ordningen för en nyinstallation, med hookarna och arbetslasterna sida vid sida.

Hur tjänsterna väntar på sitt schema

Deployments startar så snart Helm skapar dem, medan hookarna fortfarande körs. En tjänst som startade mot en databas utan roll, lösenord eller schema skulle krascha och starta om tills hookarna var klara. Därför har varje Deployment som använder databasen en init-container, wait-for-schema, som i stället håller tillbaka podden.

Den läser releaseliggaren som nexus_ledger_reader, en inloggning som kan läsa just den tabellen och ingenting annat, och väntar tills liggaren visar sina kedjor för den här releasens avbildnings-digests. Den kontrollerar var schemaWait.intervalSeconds (3 som standard), skriver ut sitt tillstånd när det ändras och vid var tjugonde kontroll, och ger upp efter schemaWait.timeoutSeconds (1 800 som standard) med ett fel som namnger tjänsten.

Driftsättning Väntar 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

För att följa en tjänsts väntan medan den pågår, läs dess init-containers logg:

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

Eftersom väntan styrs av avbildningens digest, inte av ett antal filer, väntar poddarna vid en senare uppgradering på den nya releasens rader, och en podd som startar om efter en ändring i enbart values-filen hittar sin rad direkt.

Steg 7: vänta på varje workload

Vänta på Deployments, med en tidsgräns:

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

Sedan StatefulSets. De två nyckellagerservrarna uppdateras endast när du tar bort deras poddar, och kubectl rollout status avvisar den uppdateringsstrategin, så vänta på antalet redo i stället:

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

Var och en skriver ut condition met. På vårt kluster tog båda väntetiderna tillsammans under fem minuter efter att Helm returnerat.

Hur redo 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

Tio Deployments och sju StatefulSets, var och en redo. Bredvid dem hittar du tre CronJobs, nexus-keys-rotate-epoch, nexus-keys-run-schedule och nexus-keys-export-receipts, nyckeltjänstens nattliga underhåll. kubectl -n nexus get jobs ska inte lista några hook-Jobs: de som lyckades togs bort.

Två saker är värda att göra innan du lämnar terminalen. Checka in values-filen där ditt team lagrar konfiguration; varje uppgradering utgår från den. Och låt Secreten nexus-generated vara ifred. Chartet genererar de interna lösenorden och nycklarna en gång, vid installationen, behåller dem där och läser tillbaka dem vid varje uppgradering, så om du tar bort den kan tjänsterna inte längre nå sina egna data.

Redo betyder att plattformen körs och att ingen har gjort anspråk på den. Öppna https://console.harrow.example så kommer du till installationsprogrammet, inte en inloggningssida: ingen kan logga in förrän någon gör anspråk på installationen. Det är den första körningen, i kapitel 2.12, Den första körningen.

Denna installation (Community)
Denna installation (Community)
En Community-installations egen sida när anspråk har gjorts på den: versionen som körs, motorhälsa, diskanvändning, säkerhetskopior och löftet om säkerhetsfixar, där Enterprise-delarna visas som förhandsvisningar som anger vem som kan aktivera dem.

Om detta misslyckas

De flesta fel namnger sig själva. Läs meddelandet innan du ändrar något.

Vad ni ser Orsak Vad du ska göra
INSTALLATION_NAME_MISSING eller INSTALLATION_NAME_EXAMPLE keys.installationName är tom eller innehåller exempelvärdet Ange ditt eget permanenta namn
KEYS_CUSTODIAN_MISSING eller KEYS_CUSTODIAN_EXAMPLE Inga nyckelförvaltare, eller exempelvärdet Ange dina nyckelförvaltares egna mottagare
keys.installationName ... does not match ^[a-z][a-z0-9-]{0,62}$ Versaler, punkter eller en inledande siffra Använd gemener, siffror och bindestreck, och börja med en bokstav
keys.custody.recipients: ... och en orsak En mottagare är felstavad, är en privat nyckel eller har ett format som custody-Jobet inte kan kryptera till Be nyckelförvaltaren om mottagaren igen
hosts.console is required (the installation identity) En värd är inte angiven Ange alla tre värdar
tls.existingSecret is required when tls.mode is existing Ingen Secret namngiven Ange den, eller ändra tls.mode
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read Ditt konto kan inte läsa API-serverns adresser Ange dem som /32-intervall
global.imageRegistry is required Registret är inte angivet Ange det
Helm väntar tills tidsgränsen löper ut; nexus-auth loggar password authentication failed --wait angavs Avinstallera och installera igen utan --wait
Error: ... job failed som namnger en hook En migrering misslyckades kubectl -n nexus logs job/<hook-name> och läs dess sista rader
En podd har fastnat i Init Dess wait-for-schema väntar fortfarande Läs dess logg: den namnger den kedja som saknas
wait-for-schema: FAILED Kedjans hook skrev aldrig sin rad Hitta felet i den hooken först
ImagePullBackOff Noden kan inte hämta från global.imageRegistry Kontrollera att noden kan nå registret och, för Enterprise, har pull-token

Varje hook som väntar på PostgreSQL väntar en begränsad tid och meddelar detta, waiting for postgres (12/60), så en databas som har fastnat syns i hookens logg inom en minut.

Installationsvägen med nexusctl

nexusctl install gör samma installation, med kontrollerna runt omkring den körda åt dig. Den tar samma values-fil:

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

Den kör förkontrollen igen och stannar om någon kontroll har börjat misslyckas. Den verifierar chart-paketets signatur mot releasenyckeln. Sedan installerar den, väntar igenom hookarna och arbetslasterna och skriver ut varje steg med hur lång tid det tog. --edition community anger utgåvan på kommandoraden såväl som i filen. --ca-bundle <file> lägger till dina egna CA-certifikat, på samma sätt som för förkontrollen. För att se de helm- och kubectl-operationer den skulle köra, utan att köra dem, lägg till --explain:

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

När den är klar skriver den ut adressen för anspråk, en engångskod för anspråk och installationens fingeravtryck:

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 och tillåter fem försök; fingeravtrycket består av åtta grupper om fyra tecken, och webbläsaren visar samma åtta grupper så att du kan jämföra dem innan du gör anspråk.

Installerar
Installerar
Installationen körs i operatörens terminal. Varje steg skrivs ut med sin tidsåtgång, och körningen avslutas med en engångskod och installationens fingeravtryck; ingen kan logga in förrän anspråk har gjorts på installationen i en webbläsare.

Överlämning till den första körningen

Om du installerade med Helm skapar du anspråkskoden själv och anger den person som ska bli den första administratören:

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

Den kör nyckeltjänstens eget kommando för anspråkskod i nexus-keys-podden med din klusteråtkomst, och skriver ut adressen, koden och fingeravtrycket som ovan. Koden fungerar i 30 minuter; kör kommandot igen för att få en ny.

Härifrån tar webbläsaren över: gör anspråk på installationen, skapa den första administratören med en passkey och gå igenom de sex punkterna innan någon loggar in. Det är kapitel 2.12, Den första körningen. Om du ska licensiera Enterprise direkt, läs kapitel 2.7, Installera Enterprise och tillämpa en licens, först, eftersom licensen är en av dessa sex punkter.