Versione 1.0.0-alpha.1ultima
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

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
Verificare che Helm sia alla versione 4.
helm versionL'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.
Puntare
kubectlal cluster indicato sul foglio di lavoro e confermare.kubectl config use-context harrow-prod kubectl get nodesOgni 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.
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.Attendere il suo webhook, attraverso il quale passa ogni richiesta di certificato:
kubectl -n cert-manager rollout status deploy/cert-manager-webhook --timeout=300sdeployment "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.keyharrow-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.yamlL'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 45mSe 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.
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-schemawait-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=900sdeployment.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
doneCiascuno 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,statefulsetNAME 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.
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.yamlEsegue 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 --explainAl 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.
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.exampleQuesto 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.

