AccediPrenota un briefing

Capitolo 2.6

Installare Community su Kubernetes

Un'installazione passo dopo passo dell'edizione Community con Helm, da cert-manager fino a quando ogni workload è pronto, con il file values spiegato chiave per chiave, il motivo per cui non si usa --wait, l'ordine di esecuzione degli hook del chart e il percorso di installazione alternativo tramite nexusctl.

Questa pagina è stata tradotta dall'IA a partire dall'originale in inglese. In caso di dubbi, fa fede la pagina in inglese. Legga questa pagina in inglese

18 minuti di lettura

L'installazione in sé è un singolo helm install. Tutto ciò che la circonda serve a far sì che quell'unico comando funzioni al primo colpo: cert-manager prima, un file values letto riga per riga e un'attesa successiva che sa cosa aspettare. Presso la Harrow Port Authority abbiamo installato prima la versione Community, per un progetto pilota di sei settimane, sul cluster k3s a tre nodi del nostro foglio di lavoro di pianificazione. La release era attiva in circa venti minuti e nessuno ha potuto accedere finché non l'abbiamo rivendicata, proprio come deve essere.

Questo capitolo presuppone che abbiate già fatto tre cose: compilato il foglio di lavoro di pianificazione (capitolo 2.3, Pianificazione di un'installazione), scaricato e verificato la release (capitolo 2.4, Ottenimento e verifica di una release) ed eseguito il preflight (capitolo 2.5, Preflight con nexusctl). Se uno di questi punti è ancora in sospeso, tornate indietro. L'installazione rifiuta la maggior parte degli errori indicandoli per nome, ma alcuni, come un custode di cui avete già perso la chiave, non può vederli.

Passaggio 1: confermare gli strumenti e il contesto

  1. Verificare che Helm sia alla versione 4.

    helm version

    L'installazione si basa sul fatto che Helm 4 attende per impostazione predefinita i Job degli hook del chart. Noi abbiamo usato la versione v4.3.1.

  2. Puntare kubectl al cluster indicato sul foglio di lavoro e confermare.

    kubectl config use-context harrow-prod
    kubectl get nodes

    Ogni nodo dovrebbe indicare Ready. Il preflight lo ha già verificato, ma un nodo può disconnettersi tra il preflight e l'installazione, ed è più rapido accorgersene qui.

Passaggio 2: installare prima cert-manager

Il chart crea la propria autorità di certificazione (CA) locale con cert-manager e ogni servizio comunica con gli altri tramite i certificati che essa emette: un Issuer autofirmato, un certificato CA locale di dieci anni e certificati a breve scadenza per i servizi. Pertanto, cert-manager deve essere in esecuzione prima di Nexus. La release richiede la versione v1.21.3 e non necessita di trust-manager.

  1. Installare cert-manager dal suo chart, con le relative risorse personalizzate:

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

    <cert-manager-chart> è il chart di cert-manager v1.21.3 proveniente dalla release ufficiale del progetto cert-manager. Qui è corretto attendere; si tratta dell'installazione stessa di cert-manager, senza hook che dipendano da altro.

  2. Attendere il suo webhook, attraverso il quale passa ogni richiesta di certificato:

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

Passaggio 3: creare il namespace e il Secret TLS

Con tls.mode: existing, il chart si aspetta il certificato come Secret di Kubernetes nel namespace prima dell'installazione. Il Transport Layer Security (TLS) per tutti e tre gli indirizzi proviene da questo unico Secret, quindi il suo certificato deve includere i nomi di tutti e tre gli host.

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

harrow-public.crt è il certificato, con la sua catena, e harrow-public.key la sua chiave privata. Se avete scelto tls.mode: cert-manager o none nel capitolo 2.3, Pianificazione di un'installazione, saltate il Secret; potete comunque creare il namespace ora, oppure lasciare che lo faccia Helm con --create-namespace al passaggio 6.

Passaggio 4: scrivere il file values

Questo è il file values di Harrow per il progetto pilota. Ogni chiave presente è accettata dallo schema del chart; lo schema rifiuta qualsiasi altra chiave, quindi una chiave scritta male fa fallire l'installazione invece di essere ignorata silenziosamente.

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

Ogni <recipient-...> è il destinatario age pubblico di un custode, la riga age1... o age1se1... che vi ha inviato. Ecco tutte le chiavi che abbiamo impostato e perché.

global.imageRegistry è il registro da cui i nodi eseguono il pull. Il chart non ha un valore predefinito; costruisce ogni immagine come <this>/nexus/<service>@<digest>. Per un'installazione connessa, è registry.adverant.ai. Se avete copiato le immagini nel vostro registro, è quell'host.

global.domain è il dominio sotto cui si trovano i tre indirizzi.

hosts.console, hosts.api e hosts.auth costituiscono l'identità dell'installazione: i tre nomi che le persone e i programmi utilizzano. Ciascuno deve già essere risolto nel Domain Name System (DNS), aspetto che il preflight ha verificato.

edition e enterprise.enabled devono concordare: community con false, oppure enterprise con true. Il chart rifiuta qualsiasi altra combinazione e rifiuta un'edizione per la quale il blocco delle immagini non è stato creato.

tls.mode e tls.existingSecret determinano il modo in cui l'edge pubblico ottiene il suo certificato. Con cert-manager impostereste invece tls.clusterIssuer, e con none nessuno dei due.

ingress.className indica il nome della classe di ingress. Lasciarlo non impostato per usare la classe predefinita del cluster.

storage.className indica il nome della classe di archiviazione per ogni volume di dati. Lasciarlo non impostato per usare quella predefinita.

networkPolicy.ingressNamespace è il namespace in cui viene eseguito l'ingress controller. Il valore predefinito, kube-system, è corretto per Traefik di k3s; lo abbiamo impostato comunque in modo che sia esplicito nel file.

networkPolicy.externalEgressCIDRs elenca gli intervalli di indirizzi, in notazione Classless Inter-Domain Routing (CIDR), esterni al namespace che i servizi possono raggiungere, oltre al DNS e al server dell'interfaccia di programmazione delle applicazioni (API) di Kubernetes. Il nostro contiene il singolo indirizzo del mail relay; se l'elenco è vuoto, nulla all'esterno del namespace è raggiungibile.

keys.installationName è il nome permanente sotto il quale il key store conia l'identità dell'installazione.

keys.custody.recipients elenca i destinatari age pubblici dei custodi. Il Job di custodia crittografa ogni frammento di sblocco (unseal share) e chiave di ripristino per ciascuno di essi.

Chiavi che potrebbero servire e chiavi da non toccare

Chiave Quando impostarla
networkPolicy.apiServerCIDRs Quando il chart non riesce a leggere gli indirizzi dell'API server dagli Endpoint kubernetes. Indicarli come intervalli /32
proxy.trustedCIDRs Quando i pod dell'ingress controller non si trovano su 10.42.0.0/16 di k3s
ai.localProvider.baseUrl Quando l'organizzazione gestisce un proprio server di modelli di intelligenza artificiale (IA) compatibile con OpenAI (capitolo 2.14, Fornitori e modelli di IA)
ai.installationHosts Quando tale server di modelli risiede su nomi privati all'interno dell'installazione
dataTier.<store>.size Quando uno store necessita di più spazio rispetto al volume predefinito
dataTier.<store>.mode external per uno store gestito autonomamente (capitolo 2.11, Variazioni: store esterni, TLS e ingress)
components.<service>.replicas, components.<service>.resources Quando si aumenta la dimensione di un servizio
auth.rateLimitPerMinute Quando un'automazione intensiva richiede più di 5,000 richieste al minuto per persona
schemaWait.timeoutSeconds Quando un disco lento fa sì che le prime migrazioni richiedano più di 30 minuti

Lasciate istio.enabled su false; Nexus non necessita di service mesh. Lasciate telemetry.enabled su false; lo schema non accetta altri valori. Lasciate orchestrator.platformServiceUserId e probitas.flags così come sono impostati dal chart.

Nessuna credenziale è mai un valore del chart. Non esiste alcuna chiave per la chiave API di un fornitore di modelli, per la password della posta o per un token di pull. I servizi generano i propri segreti interni al momento dell'installazione e li mantengono durante l'aggiornamento, mentre le chiavi dei modelli di ciascuna organizzazione vengono inserite nel relativo pool di chiavi dalla console dopo il primo avvio.

Passaggio 5: eseguire preflight sul file finale

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

L'esecuzione deve terminare con 0 failed. Il Capitolo 2.5, Preflight con nexusctl, spiega ogni riga. Se avete modificato qualcosa dall'ultima esecuzione, anche solo una dimensione, eseguitelo di nuovo.

Passaggio 6: installare, senza --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

Se non avete creato il namespace al passaggio 3, aggiungete --create-namespace. Se state installando da un file chart che avete scaricato e verificato, inserite il suo percorso al posto del riferimento oci://.

Non aggiungete --wait. Il bootstrap del database del chart viene eseguito come hook post-installazione, dopo che le risorse della release stessa esistono, ed è proprio quell'hook a fornire a ciascun servizio il ruolo e la password del database. --wait bloccherebbe l'installazione finché ogni Deployment non risultasse Available, e nessun Deployment può diventare Available prima che l'hook che sta attendendo sia stato eseguito. I servizi rimangono in attesa rifiutando gli accessi al database, e Helm li attende fino al timeout. Senza --wait, Helm 4 attende comunque ogni Job degli hook, in ordine, ed è proprio questa l'attesa desiderata.

Quando l'ultimo hook ha terminato, Helm stampa il suo riepilogo:

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

STATUS: deployed significa che ogni hook è andato a buon fine. Non significa ancora che ogni servizio stia erogando; il passaggio 7 attende proprio questo.

Cosa viene eseguito e in quale ordine

Helm esegue gli hook in base al peso, partendo dal più basso, e attende il completamento di ciascuno prima di passare al successivo. Ogni Job di migrazione ha backoffLimit: 0: una migrazione fallita fa fallire l'installazione e non viene mai ritentata a vostra insaputa. Un Job che va a buon fine viene eliminato; un Job che fallisce rimane, con il suo log, affinché possiate leggerlo.

Peso Hook Cosa fa
-30 Prerequisiti L'account dell'hook nexus-migrations, il Secret riservato agli hook nexus-migrations-env con le credenziali del database generate, e l'account, il ruolo, la configurazione e il certificato del Job di custodia
-20 nexus-db-bootstrap Crea i database e i ruoli, nessuno dei quali è superuser e nessuno è in grado di aggirare la sicurezza a livello di riga (RLS); aggiunge le estensioni, tra cui PostGIS e pgvector; crea il registro della release
-15 nexus-openbao-custody-init Inizializza il key store e il suo unsealer, crittografa i frammenti e le chiavi di ripristino per i custodi, revoca entrambi i token di root e conia l'identità dell'installazione sotto keys.installationName
-12 nexus-graphrag-migrations Imposta per primo lo schema del servizio a grafo, poiché lo schema del servizio di accesso fa riferimento a oggetti di sua proprietà
-10 nexus-auth-migrations Imposta lo schema del servizio di accesso e i suoi due ruoli di runtime
-5 nexus-orchestrator-migrations, nexus-gateway-migrations, nexus-probitas-migrations Lo schema proprio di ciascun servizio; probitas viene eseguito dopo auth perché controlla prima le tabelle di auth
0 nexus-alpha-bff-migrations Esegue il provisioning del database backend for frontend (BFF) e dei suoi ruoli, quindi applica le relative migrazioni

Ogni hook di migrazione termina scrivendo una riga nel registro della release, nexus_release.schema_applied: il nome della sua catena e il digest dell'immagine che l'ha eseguita. Scrive quella riga solo dopo che il suo esecutore di migrazione ha terminato senza errori. Il Job di bootstrap stampa db-bootstrap: done; gli hook di migrazione SQL stampano schema-ledger: recorded <chain> for this release's image come ultima riga. L'hook di migrazione della console stessa, nexus-alpha-bff-migrations, registra la propria riga allo stesso modo e poi stampa bff-migrate: done.

Una linea temporale orizzontale che scorre da sinistra a destra, etichettata "helm install". Sulla traccia superiore, sette riquadri di hook in ordine: "-30 prerequisites", "-20 db-bootstrap", "-15 custody init", "-12 graphrag migrations", "-10 auth migrations", "-5 orchestrator, gateway, probitas migrations", "0 BFF migrations". Ogni riquadro di migrazione ha una piccola freccia rivolta verso il basso che punta a un cilindro su una traccia centrale etichettata "release ledger: nexus_release.schema_applied". Sulla traccia inferiore, una lunga barra che parte da sinistra etichettata "Deployments start, wait-for-schema holds each pod"; da essa salgono brevi frecce verticali verso il registro, e la barra di ciascun Deployment diventa piena quando appare la relativa riga nel registro.
L'ordine di una nuova installazione, con gli hook e i carichi di lavoro affiancati.

Come i servizi attendono il proprio schema

I Deployment si avviano non appena Helm li crea, mentre gli hook sono ancora in esecuzione. Un servizio che si avviasse su un database privo di ruolo, password o schema andrebbe in crash e si riavvierebbe fino al termine degli hook. Pertanto, ogni Deployment che utilizza il database include un init container, wait-for-schema, che invece trattiene il pod.

Legge il registro della release come nexus_ledger_reader, un login che può leggere solo quella tabella e nient'altro, e attende finché il registro non mostra le sue catene per i digest delle immagini di questa release. Esegue il polling ogni schemaWait.intervalSeconds (3 per impostazione predefinita), stampa il proprio stato quando cambia e a ogni ventesimo polling, e rinuncia dopo schemaWait.timeoutSeconds (1,800 per impostazione predefinita) con un errore che indica il nome del servizio.

Deployment Attende
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

Per osservare in tempo reale l'attesa di un servizio, leggere il log del suo init container:

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

Poiché l'attesa è basata sul digest dell'immagine e non sul conteggio dei file, i pod di un aggiornamento successivo attendono le righe della nuova release, mentre un pod che si riavvia dopo una modifica dei soli valori trova immediatamente la propria riga.

Passaggio 7: attendere che ogni workload sia pronto

Attendere i Deployment, con un limite di tempo:

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

Poi gli StatefulSet. I due server del key-store si aggiornano solo quando si eliminano i relativi pod, e kubectl rollout status rifiuta tale strategia di aggiornamento, quindi occorre attendere invece il conteggio dei pod pronti:

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

Ciascuno stampa condition met. Sul nostro cluster entrambe le attese insieme hanno richiesto meno di cinque minuti dopo la conclusione di Helm.

Come appare uno stato pronto

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

Dieci Deployment e sette StatefulSet, tutti pronti. Accanto ad essi troverete tre CronJob, nexus-keys-rotate-epoch, nexus-keys-run-schedule e nexus-keys-export-receipts, che costituiscono la manutenzione notturna del servizio chiavi. kubectl -n nexus get jobs dovrebbe elencare zero Job di hook: quelli andati a buon fine sono stati eliminati.

Vale la pena fare due cose prima di lasciare il terminale. Eseguite il commit del file values ovunque il vostro team conservi la configurazione; ogni aggiornamento parte da lì. E non toccate il Secret nexus-generated. Il chart genera le password e le chiavi interne una sola volta, all'installazione, le conserva lì e le rilegge a ogni aggiornamento, quindi eliminarlo impedirebbe ai servizi di raggiungere i propri dati.

Pronto significa che la piattaforma è in esecuzione e non rivendicata. Aprite https://console.harrow.example e raggiungerete il programma di installazione, non una pagina di accesso: nessuno può accedere finché qualcuno non rivendica l'installazione. Questo è il primo avvio, trattato nel capitolo 2.12, Il primo avvio.

Questa installazione (Community)
Questa installazione (Community)
La pagina di un'installazione Community una volta rivendicata: la versione in esecuzione, lo stato dei motori, l'uso del disco, i backup e la garanzia di correzione di sicurezza, con le funzionalità Enterprise mostrate come anteprime che indicano chi può attivarle.

Se l'operazione fallisce

La maggior parte degli errori si identifica da sé. Leggete il messaggio prima di modificare qualsiasi cosa.

Cosa si vede Causa Cosa fare
INSTALLATION_NAME_MISSING o INSTALLATION_NAME_EXAMPLE keys.installationName è vuoto o contiene il valore di esempio Impostare il proprio nome permanente
KEYS_CUSTODIAN_MISSING o KEYS_CUSTODIAN_EXAMPLE Nessun custode, oppure è presente quello di esempio Impostare i destinatari effettivi dei propri custodi
keys.installationName ... does not match ^[a-z][a-z0-9-]{0,62}$ Lettere maiuscole, punti o una cifra iniziale Usare lettere minuscole, cifre e trattini, iniziando con una lettera
keys.custody.recipients: ... e una motivazione Un destinatario contiene un errore di battitura, è una chiave privata o è in un formato per il quale il Job di custodia non può crittografare Chiedere nuovamente il destinatario al custode
hosts.console is required (the installation identity) Un host non è impostato Impostare tutti e tre gli host
tls.existingSecret is required when tls.mode is existing Nessun nome di Secret indicato Impostarlo o modificare tls.mode
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read L'account non riesce a leggere gli indirizzi dell'API server Indicarli come intervalli /32
global.imageRegistry is required Il registro non è impostato Impostarlo
Helm resta in attesa fino al timeout; nexus-auth registra password authentication failed È stato specificato --wait Disinstallare e installare nuovamente senza --wait
Error: ... job failed che indica il nome di un hook Una migrazione è fallita kubectl -n nexus logs job/<hook-name> e leggere le ultime righe
Un pod bloccato in Init Il suo wait-for-schema è ancora in attesa Leggere il suo log: indica la catena mancante
wait-for-schema: FAILED L'hook della catena non ha mai scritto la propria riga Individuare prima l'errore di quell'hook
ImagePullBackOff Il nodo non riesce a eseguire il pull da global.imageRegistry Verificare che il nodo possa raggiungere il registro e, per Enterprise, che disponga del token di pull

Ogni hook che attende PostgreSQL lo fa per un tempo limitato e lo dichiara, waiting for postgres (12/60), quindi un database bloccato si manifesta nel log dell'hook entro un minuto.

Il percorso di installazione con nexusctl

nexusctl install esegue la stessa installazione, effettuando al posto vostro i controlli preliminari e successivi. Accetta lo stesso file values:

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

Esegue nuovamente il preflight e si ferma se un controllo inizia a dare esito negativo. Verifica la firma del bundle del chart rispetto alla chiave della release. Quindi installa, attende il completamento degli hook e dei carichi di lavoro e stampa ogni passaggio indicando il tempo impiegato. --edition community dichiara l'edizione sia sulla riga di comando sia nel file. --ca-bundle <file> aggiunge i vostri certificati CA, proprio come per il preflight. Per vedere le operazioni helm e kubectl che eseguirebbe, senza eseguirle realmente, aggiungete --explain:

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

Al termine, stampa l'indirizzo di rivendicazione, un codice di rivendicazione monouso e l'impronta digitale (fingerprint) dell'installazione:

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>

Il codice è composto da tre gruppi e consente cinque tentativi; l'impronta digitale è composta da otto gruppi di quattro caratteri, e il browser mostra gli stessi otto gruppi affinché possiate confrontarli prima di rivendicare l'installazione.

Installazione in corso
Installazione in corso
L'installazione in esecuzione nel terminale dell'operatore. Ogni passaggio viene stampato con il relativo tempo di esecuzione, e il processo termina con un codice monouso e l'impronta digitale dell'installazione; nessuno può accedere finché l'installazione non viene rivendicata in un browser.

Passaggio di consegne al primo avvio

Se avete installato con Helm, generate autonomamente il codice di rivendicazione, indicando la persona che sarà il primo amministratore:

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

Questo comando esegue il comando del codice di rivendicazione proprio del servizio chiavi nel pod nexus-keys utilizzando il vostro accesso al cluster, e stampa l'indirizzo, il codice e l'impronta digitale come mostrato sopra. Il codice è valido per 30 minuti; eseguitelo di nuovo per ottenerne uno nuovo.

Da qui in poi si prosegue nel browser: rivendicate l'installazione, create il primo amministratore con una passkey e completate i sei passaggi prima che chiunque possa accedere. Tutto questo si trova nel capitolo 2.12, Il primo avvio. Se intendete applicare subito la licenza Enterprise, leggete prima il capitolo 2.7, Installazione di Enterprise e applicazione di una licenza, poiché la licenza è uno di quei sei passaggi.