AccediPrenota un briefing

Capitolo 2.3

Pianificare un'installazione

Di cosa ha bisogno un'installazione Kubernetes di Nexus prima di digitare qualsiasi comando, quali sono le sue dimensioni e le due decisioni irreversibili: il nome dell'installazione e i custodi delle chiavi. Si conclude con il foglio di lavoro di pianificazione compilato da Harrow Port Authority.

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

16 minuti di lettura

Quando abbiamo installato Nexus presso la Harrow Port Authority, l'esecuzione dei comandi ha richiesto un pomeriggio. La pianificazione ha richiesto una settimana, e gran parte di quella settimana è stata dedicata a due questioni che non hanno nulla a che fare con Kubernetes: come avremmo chiamato l'installazione e quali persone avrebbero custodito le sue chiavi di ripristino. Entrambe le risposte sono permanenti. Tutto il resto in questo capitolo può essere modificato in seguito con un file values e un helm upgrade.

Sono Tomás Reilly, il platform engineer presso Harrow. Harrow gestisce due installazioni. Questo capitolo pianifica quella connessa nella nostra rete aziendale, dove abbiamo prima condotto il progetto pilota di Community. La rete operativa del porto, che non ha instradamento verso Internet, ha ricevuto la propria installazione in seguito; il capitolo 2.10, Installazione air-gapped, la illustra. Questo capitolo è ciò che avrei voluto avere la prima mattina: il cluster che Nexus si aspetta, i nomi a cui risponde, quante risorse richiede ai nodi e le decisioni da concordare con il responsabile IT prima dell'installazione. Si chiude con il foglio di lavoro che Aoife Brennan, la nostra responsabile IT, ha approvato prima che iniziassimo. Il capitolo 2.4, Ottenimento e verifica di una release, tratta il recupero e il controllo della release, mentre il capitolo 2.5, Preflight con nexusctl, verifica il cluster rispetto a tutto quanto riportato qui.

Requisiti del cluster

Nexus si installa come un unico chart Helm, nexus, versione 1.0.0-alpha.1. Il chart contiene i servizi di piattaforma e il relativo livello dati, e rifiuta di installarsi su un cluster privo degli elementi indicati di seguito.

Requisito Cosa si aspetta Nexus Perché
Kubernetes 1.33 o successivo. Testato su k3s v1.33.6+k3s1 Il kubeVersion del chart è >=1.33.0-0, e helm install lo impone
cert-manager v1.21.3, installato prima di Nexus Il chart crea la propria autorità di certificazione (CA) locale e i certificati che i suoi servizi utilizzano per comunicare tra loro
Helm v4 (abbiamo utilizzato v4.3.1) Per impostazione predefinita, Helm 4 attende i Job hook del chart, da cui dipende l'installazione
Una storage class Una contrassegnata come predefinita, oppure una indicata in storage.className Ogni archivio dati richiede un volume persistente
Una ingress class Una contrassegnata come predefinita, oppure una indicata in ingress.className I tre indirizzi pubblici sono semplici Ingress networking.k8s.io/v1
Porte 80 e 443 Aperte sull'ingress controller, come Service di tipo LoadBalancer o NodePort Gli utenti raggiungono Nexus attraverso l'ingress controller
Architettura Nodi linux/amd64 o linux/arm64 Ogni immagine è compilata per entrambi

Due elementi sono assenti da quella tabella di proposito. Nexus non necessita di alcun service mesh: il mutual TLS (mTLS, Transport Layer Security bidirezionale) tra i servizi proviene dalla CA locale del chart tramite cert-manager. Il chart ha una chiave istio.enabled impostata per default su false, ed è opportuno lasciarla così. Nexus non necessita nemmeno di un proprio motore di policy di ammissione.

Sulla propria workstation saranno necessari kubectl, Helm v4, cosign v3 per la verifica delle firme, age per la creazione delle chiavi dei custodi e nexusctl, l'interfaccia a riga di comando (CLI) per l'operatore di Nexus. Il capitolo 2.4, Ottenimento e verifica di una release, indica dove si trova ciascun download di Nexus.

Tre indirizzi

Ogni installazione risponde su tre nomi host. Il chart li definisce identità dell'installazione, e ogni servizio rifiuta di avviarsi senza di essi.

Chiave dei valori Nome presso Harrow Cosa risponde a quell'indirizzo
hosts.console console.harrow.example La console, l'applicazione web a cui gli utenti accedono
hosts.api api.harrow.example Il gateway, che espone l'interfaccia di programmazione delle applicazioni (API) e instrada ogni richiesta di intelligenza artificiale (IA)
hosts.auth auth.harrow.example Il servizio di accesso, nexus-auth

global.domain contiene il dominio sotto cui si trovano i tre host, harrow.example nel nostro caso. Ciascun host è un nome completo a sé stante e può trovarsi sotto qualsiasi dominio sotto il proprio controllo. Noi li abbiamo mantenuti tutti e tre sotto un unico dominio affinché un solo certificato potesse coprirli.

Creare un record del Domain Name System (DNS) per ciascuno dei tre nomi, che punti all'indirizzo del proprio ingress controller. Farlo prima del preflight. nexusctl preflight cerca ciascun nome dalla workstation e interrompe l'installazione se uno di essi è privo di record, poiché un utente non può raggiungere un nome che non viene risolto.

A sinistra, tre nomi DNS: console.harrow.example, api.harrow.example e auth.harrow.example, ciascuno con una freccia che entra in un riquadro etichettato "ingress controller, ports 80 and 443". Da quel riquadro, tre frecce conducono a un riquadro più grande etichettato "namespace nexus": la freccia della console verso "nexus-alpha :3000", la freccia dell'api verso "nexus-gateway :9092" e la freccia di auth verso "nexus-auth :9101". Un bordo tratteggiato attorno al namespace è etichettato "default deny; only the ingress namespace may reach these three".
Come i tre nomi pubblici raggiungono i servizi retrostanti.

Scegliere dove terminare TLS

La chiave tls.mode del chart stabilisce chi detiene i certificati per i tre indirizzi pubblici. Vi sono tre opzioni, ed è possibile passare dall'una all'altra in seguito tramite un aggiornamento.

tls.mode Cosa si fornisce Cosa fa il chart
existing (il valore predefinito) Un Secret TLS di Kubernetes nel namespace nexus, indicato in tls.existingSecret Tutti e tre gli Ingress utilizzano quell'unico Secret
cert-manager Un ClusterIssuer gestito dall'utente, indicato in tls.clusterIssuer Annota ciascun Ingress affinché cert-manager emetta nexus-console-tls, nexus-api-tls e nexus-auth-tls
none Un componente davanti al cluster che termina TLS, come il proprio load balancer Genera gli Ingress senza alcuna sezione TLS

Con existing, un unico certificato serve tutti e tre gli host, pertanto deve indicarli tutti e tre, come tre Subject Alternative Name oppure come wildcard per il proprio dominio. Noi abbiamo utilizzato un certificato della CA interna di Harrow. Il preflight legge il Secret prima dell'installazione ed emette un avviso quando il certificato scade entro 30 giorni.

Con cert-manager e un emittente ACME (Automatic Certificate Management Environment), il chart non aggiunge alcun reindirizzamento proprio, cosicché una richiesta /.well-known/acme-challenge/ sulla porta 80 raggiunge il solver intatta. Non aggiungere sull'ingress controller un reindirizzamento da HTTP a HTTPS che venga eseguito prima del percorso di challenge; un certificato che non riesce a rinnovarsi cessa di funzionare silenziosamente, settimane dopo.

Qualunque cosa si scelga per il perimetro pubblico, i servizi all'interno del namespace comunicano sempre tramite TLS utilizzando la CA locale del chart. Questa parte non è opzionale, ed è il motivo per cui cert-manager è un prerequisito anche quando tls.mode è impostato su existing o none.

Cosa esce dal cluster e cosa no

Il chart genera una network policy di tipo default-deny per il namespace nexus. Oltre a ciò, sono consentiti solo i seguenti flussi:

  • traffico tra i pod di Nexus all'interno del namespace;
  • ricerche DNS verso il servizio DNS del cluster;
  • l'API server di Kubernetes, per i pochi servizi che verificano i token dei carichi di lavoro;
  • il namespace dell'ingress controller, verso i tre Service pubblici;
  • qualsiasi intervallo CIDR (Classless Inter-Domain Routing) elencato in networkPolicy.externalEgressCIDRs.

Quest'ultimo elenco è vuoto per impostazione predefinita. Se si utilizzerà un mail relay o un model server esterno al cluster, il relativo intervallo va inserito lì. La telemetria è disattivata e rimane disattivata: lo schema accetta solo telemetry.enabled: false, e anche l'invio dei dati di utilizzo degli archivi dati stessi è disattivato.

Il chart legge gli indirizzi dell'API server dal cluster al momento dell'installazione. Se il proprio account non può leggere gli Endpoints kubernetes nel namespace default, specificarli manualmente in networkPolicy.apiServerCIDRs, come intervalli /32. proxy.trustedCIDRs indica la rete dei pod su cui risiede l'ingress controller, in modo che nexus-auth sappia di quale intestazione X-Forwarded-For fidarsi. Il valore predefinito, 10.42.0.0/16, è la rete dei pod di k3s.

Dimensionamento

Le richieste predefinite del chart ammontano in totale a circa 2.05 core di unità di elaborazione centrale (CPU) e 6.7 GiB di memoria. Questo è ciò che lo scheduler riserva; i limiti sono più elevati e gli archivi dati si espandono fino a raggiungerli man mano che si aggiungono utenti e file.

Componente CPU richiesta Memoria richiesta
Nove servizi di piattaforma (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) 1.1 core 2.6 GiB
Il servizio chiavi, nexus-keys 0.05 core 64 MiB
PostgreSQL 0.25 core 1 GiB
Neo4j 0.25 core 2 GiB
Valkey, Qdrant e l'object store insieme 0.25 core 640 MiB
I due server OpenBao del key store 0.15 core 384 MiB

I volumi predefiniti ammontano in totale a 142 GiB:

Archivio Chiave dei valori Dimensione predefinita
PostgreSQL 16 con PostGIS 3 e pgvector 0.8 dataTier.postgres.size 50Gi
Object store (SeaweedFS) dataTier.objectStore.size 50Gi
Neo4j 5.26 Community Edition dataTier.neo4j.size 20Gi
Qdrant dataTier.qdrant.size 10Gi
Valkey dataTier.valkey.size 5Gi
Il key store e il relativo unsealer keys.openbao.storage.keystore, keys.openbao.storage.unsealer 5Gi e 1Gi
Ricevute del servizio chiavi keys.receiptsStorage 1Gi

Per un nodo singolo, prevedere 8 vCPU, 32 GiB di memoria ad accesso casuale (RAM) e un'unità a stato solido (SSD) da 250 GB. Per una valutazione, saranno sufficienti 4 vCPU, 16 GiB e 200 GB. L'immagine disco dell'installer rifiuta una macchina con meno di 16 GiB di memoria (vedere il capitolo 2.9, L'immagine disco dell'installer), e consiglierei di considerarlo come il requisito minimo ovunque.

I nodi grafici sono facoltativi. Senza un nodo dotato di unità di elaborazione grafica (GPU), l'assistente risponde tramite un modello in hosting, utilizzando la chiave propria dell'organizzazione. Il preflight segnala ciò come un avviso, mai come un errore. Il capitolo 2.14, Provider e modelli di IA, illustra entrambe le modalità.

Ciascun archivio può anche essere eseguito all'esterno del cluster: impostare dataTier.<store>.mode su external e indicare il relativo host e un Secret. Un PostgreSQL esterno necessita di un account superuser per il bootstrap dell'installazione e di un certificato che Nexus possa verificare. Il capitolo 2.11, Varianti: archivi esterni, TLS e ingress, tratta questo argomento. Se li si mantiene nel cluster, collocarli su una storage class supportata da dischi reali. Il database è il componente di cui si sentirà maggiormente la mancanza in caso di guasto del disco locale di un nodo.

Il nome dell'installazione è permanente

keys.installationName è il nome con cui gli operatori identificano questa installazione. Deve corrispondere a ^[a-z][a-z0-9-]{0,62}$: una lettera minuscola, seguita da un massimo di 62 lettere minuscole, cifre o trattini.

La prima volta che il key store si avvia, genera l'identità dell'installazione con questo nome, e tale identità è fissata in modo definitivo. Una licenza di Adverant viene emessa per quell'identità, pertanto una licenza creata per un'installazione viene rifiutata su un'altra con LICENCE_OTHER_INSTALLATION. Rinominare significherebbe una nuova installazione, una nuova identità e nuove licenze.

Il chart non prevede un valore predefinito per il nome. Rifiuta un'installazione priva di nome (INSTALLATION_NAME_MISSING) e rifiuta il nome di esempio presente nei propri file values di esempio (INSTALLATION_NAME_EXAMPLE). Il preflight segnala entrambi i casi prima ancora di arrivare a quel punto.

Presso Harrow abbiamo dedicato a questo aspetto più tempo di quanto vorrei ammettere. Abbiamo scelto harrow-port-authority: indica l'organizzazione, non dice nulla sul cluster su cui è in esecuzione e rimarrà valido anche quando l'hardware verrà sostituito. Evitare nomi come prod-k3s-2 che descrivono le macchine attuali.

Custodia delle chiavi

Nexus conserva le chiavi di ogni organizzazione nel proprio key store, all'interno del cluster. Non è necessario gestirlo quotidianamente, ma occorre decidere, prima dell'installazione, chi potrà ripristinarlo dopo un riavvio. Questa è la decisione che comporta i costi maggiori in caso di errore.

Il key store è costituito da due server OpenBao. Quello principale, openbao, conserva le chiavi ed esegue autonomamente l'unseal tramite un secondo server più piccolo, openbao-unsealer. L'unsealer è sigillato con lo schema di Shamir: cinque frammenti (share), tre qualsiasi dei quali lo aprono. Al momento dell'installazione, un Job di custodia inizializza entrambi i server all'interno del cluster. Nella memoria di quel Job, cifra i frammenti dell'unsealer e le chiavi di ripristino del key store per ciascun custode indicato, memorizza solo il testo cifrato (nei Secret openbao-unseal-shares-encrypted e openbao-recovery-keys-encrypted) e revoca entrambi i root token prima di terminare. Nessun frammento in chiaro raggiunge mai un disco o un log.

Dopo qualsiasi riavvio del nodo dell'unsealer, l'unsealer si avvia sigillato. Il key store lo attende e nulla che richieda una chiave funziona finché un custode non ne esegue l'unseal. Ciò richiede un'unica decifratura con la chiave privata del custode stesso. La procedura è descritta nel capitolo 2.15, Giorno due: gestione operativa di Nexus.

Creazione di una chiave di custodia

Un custode è identificato dalla metà pubblica di una chiave age, denominata destinatario (recipient). Ciascun custode crea la propria chiave sulla propria macchina e fornisce solo il destinatario:

age-keygen -o custodian.key

La riga # public key: del file è il destinatario, che inizia con age1. Un custode con un Mac può invece conservare la chiave nel Secure Enclave del Mac, in modo che la metà privata non lasci mai il chip e ogni utilizzo richieda l'impronta digitale:

age-plugin-se keygen --access-control=any-biometry -o custodian.key

Quel destinatario inizia con age1se1. Il Job di custodia cifra per cinque formati di destinatario: age1 (X25519), age1tag1 e age1tagpq1 (tag), age1pq1 (ibrido post-quantistico) e age1se1 (Secure Enclave). Rifiuta qualsiasi altro formato di plugin, come age1yubikey1; specificare invece quella chiave in uno dei formati accettati.

Il chart verifica ciascun destinatario durante la generazione dei manifest. Un destinatario digitato in modo errato non supera il checksum bech32 e viene rifiutato, in modo che nulla venga mai sigillato con una chiave che nessuno possiede. Se qualcuno incolla per errore una chiave privata nell'elenco, il chart la rifiuta senza stamparla nell'output. Anche il destinatario di esempio presente nei file values del chart stesso viene rifiutato (KEYS_CUSTODIAN_EXAMPLE); nessuno ne possiede la metà privata.

Quanti custodi

Ogni frammento è cifrato per ogni custode, pertanto un singolo custode può eseguire l'unseal da solo. Avere più custodi significa disporre di più modi per effettuare il ripristino e di più persone che possono agire autonomamente. Presso Harrow ne abbiamo scelti tre: Aoife, io e una chiave Secure Enclave su un laptop di riserva custodito nella cassaforte del porto. Due è il minimo che accetterei. Uno rappresenta un singolo punto di vulnerabilità che, prima o poi, si troverà in ferie proprio quando un nodo si riavvia.

Scegliere l'edizione

edition è community o enterprise, e enterprise.enabled deve concordare con esso. Il chart rifiuta una mancata corrispondenza e rifiuta qualsiasi edizione che non sia una delle due.

L'edizione stabilisce anche quali immagini vengono installate. Ciascun pacchetto del chart contiene un images lock, ovvero l'elenco di ogni immagine identificata tramite digest, per una specifica edizione. Un'installazione Community utilizza solo immagini Community. Un'installazione Enterprise utilizza il lock Enterprise, costituito dalle immagini Community più le build Enterprise, ed esegue il pull tramite un pull token del proprio account Adverant. Il capitolo 2.4, Ottenimento e verifica di una release, illustra il funzionamento del lock, mentre il capitolo 2.2, Le edizioni dietro le quinte, spiega cosa contiene ciascuna edizione.

Non è necessario prendere una decisione definitiva. Un'installazione Community passa a Enterprise sul posto, mantenendo utenti, file e cronologia; il capitolo 2.7, Installazione di Enterprise e applicazione di una licenza, mostra come fare. Noi abbiamo utilizzato Community per il progetto pilota presso Harrow e siamo passati a Enterprise sei settimane dopo.

La licenza non fa mai parte di questo piano. Non è un valore del chart né un file montato: la si importa dopo l'installazione, tramite la console, nexusctl o l'API.

Scegliere la forma di distribuzione

Formato Quando è indicato Capitolo
Chart Helm da registry.adverant.ai Il proprio cluster Kubernetes, con un instradamento verso il registry 2.6 e 2.7
nexusctl install Lo stesso cluster, con l'esecuzione automatica del preflight e della verifica della firma 2.6
nexusctl install --single-node Una singola macchina, in cui nexusctl configura anche il cluster 2.8
L'immagine disco dell'installer Un server bare-metal o una macchina virtuale (VM) che si preferisce non preparare manualmente 2.9
Il bundle offline Nessun instradamento verso l'esterno; le immagini e il chart vengono forniti su disco 2.10

Il chart è lo stesso in ogni formato. Ciò che cambia è chi crea il cluster e da dove provengono le immagini.

Ottenere la release
Ottenere la release
Questa è la pagina delle release nell'account Adverant. Si notino l'indicazione chiara di ciò che garantisce una release alpha, la dimensione e la firma accanto a ogni file e i comandi offline per verificare un download.

Il foglio di lavoro per la pianificazione

Questo è quello di Harrow, così come approvato da Aoife. Copiare le due colonne di sinistra e compilare quella di destra per la propria installazione.

Decisione Chiave dei valori o comando Harrow Port Authority
Kubernetes e versione (letto dal preflight) k3s v1.33.6+k3s1, tre nodi
Contesto Kube per l'installazione --context harrow-prod
Namespace --namespace nexus
Edizione edition, enterprise.enabled community per il progetto pilota, poi enterprise
Registry delle immagini global.imageRegistry registry.adverant.ai
Dominio global.domain harrow.example
Indirizzo della console hosts.console console.harrow.example
Indirizzo dell'API hosts.api api.harrow.example
Indirizzo di accesso hosts.auth auth.harrow.example
TLS sul perimetro tls.mode, tls.existingSecret existing, Secret harrow-public-tls dalla CA interna di Harrow
Ingress class ingress.className traefik
Namespace dell'ingress networkPolicy.ingressNamespace kube-system
Storage class storage.className local-path
Archivi dati dataTier.<store>.mode Tutti in-cluster, dimensioni predefinite
Intervalli in uscita networkPolicy.externalEgressCIDRs Solo l'intervallo del mail relay
Nome dell'installazione (permanente) keys.installationName harrow-port-authority
Custodi (di fatto permanenti) keys.custody.recipients Tre: Aoife Brennan, Tomás Reilly, il laptop in cassaforte (age1se1)
Nodi grafici (letto dal preflight) Nessuno per il progetto pilota connesso; modello in hosting con la chiave propria di Harrow
Primo amministratore nexusctl claim-code --administrator aoife.brennan@harrow.example

Due righe di quel foglio sono irreversibili: il nome dell'installazione e i custodi, nel senso che perderli tutti comporta la perdita del key store. Fare approvare queste due voci da chi ha l'autorità per dare il consenso. Tutto il resto è una semplice modifica dei valori.

Una volta completato il foglio di lavoro, passare al capitolo 2.4, Ottenimento e verifica di una release, e scaricare la release.