Version 1.0.0-alpha.1dernière version
Chapitre 2.3
Planifier une installation
Ce qu'une installation Kubernetes de Nexus requiert avant même de saisir une commande, son dimensionnement, et les deux décisions irréversibles : le nom de l'installation et les dépositaires des clés. Ce chapitre se termine par la fiche de planification remplie de Harrow Port Authority.
Cette page a été traduite par l'IA à partir de l'original en anglais. En cas de doute, la page en anglais fait foi. Lire cette page en anglais

Lorsque nous avons installé Nexus chez Harrow Port Authority, l'exécution des commandes a pris un après-midi. La planification a pris une semaine, dont la majeure partie a été consacrée à deux questions qui n'ont rien à voir avec Kubernetes : comment nous allions nommer l'installation, et quelles personnes détiendraient ses clés de récupération. Ces deux réponses sont permanentes. Tout le reste dans ce chapitre peut être modifié ultérieurement avec un fichier de valeurs et un helm upgrade.
Je suis Tomás Reilly, l'ingénieur plateforme chez Harrow. Harrow exploite deux installations. Ce chapitre planifie l'installation connectée sur notre réseau d'entreprise, où nous avons d'abord testé l'édition Community en pilote. Le réseau d'exploitation du port, qui n'a aucun accès à Internet, a reçu sa propre installation plus tard ; le chapitre 2.10, Installation en environnement isolé (air-gap), la couvre. Ce chapitre rassemble ce que j'aurais aimé avoir dès le premier matin : le cluster attendu par Nexus, les noms auxquels il répond, les ressources qu'il demande à vos nœuds et les décisions à arrêter avec votre directeur informatique avant l'installation. Il se termine par la fiche de travail qu'Aoife Brennan, notre directrice informatique, a validée avant que nous commencions. Le chapitre 2.4, Obtenir et vérifier une version, traite de la récupération et de la vérification de la version, et le chapitre 2.5, Vérifications préalables avec nexusctl, contrôle votre cluster par rapport à tout ce qui est décrit ici.
Prérequis du cluster
Nexus s'installe sous la forme d'un unique chart Helm, nexus, version 1.0.0-alpha.1. Ce chart contient les services de la plateforme ainsi que leur couche de données, et il refuse de s'installer sur un cluster auquel il manque les éléments ci-dessous.
| Prérequis | Ce qu'attend Nexus | Pourquoi |
|---|---|---|
| Kubernetes | 1.33 ou version ultérieure. Testé sur k3s v1.33.6+k3s1 |
Le kubeVersion du chart est >=1.33.0-0, et helm install l'impose |
| cert-manager | v1.21.3, installé avant Nexus |
Le chart crée sa propre autorité de certification (CA) locale ainsi que les certificats que ses services utilisent pour communiquer entre eux |
| Helm | v4 (nous avons utilisé v4.3.1) | Helm 4 attend par défaut la fin des Jobs de hook du chart, ce dont dépend l'installation |
| Une classe de stockage | Une classe marquée par défaut, ou une que vous nommez dans storage.className |
Chaque magasin de données réclame un volume persistant |
| Une classe d'ingress | Une classe marquée par défaut, ou une que vous nommez dans ingress.className |
Les trois adresses publiques sont de simples Ingress networking.k8s.io/v1 |
| Ports 80 et 443 | Ouverts sur le contrôleur d'ingress, en tant que Service LoadBalancer ou NodePort | Les utilisateurs accèdent à Nexus via le contrôleur d'ingress |
| Architecture | Nœuds linux/amd64 ou linux/arm64 |
Chaque image est compilée pour les deux architectures |
Deux éléments sont volontairement absents de ce tableau. Nexus n'a besoin d'aucun maillage de services (service mesh) : le TLS mutuel (mTLS, Transport Layer Security bidirectionnel) entre les services provient de la CA locale du chart via cert-manager. Le chart possède une clé istio.enabled définie par défaut sur false, et vous devriez la laisser ainsi. Nexus n'a pas non plus besoin de son propre moteur de politiques d'admission.
Sur votre poste de travail, vous aurez besoin de kubectl, de Helm v4, de cosign v3 pour vérifier les signatures, de age pour créer les clés des dépositaires, et de nexusctl, l'interface en ligne de commande (CLI) de l'opérateur Nexus. Le chapitre 2.4, Obtenir et vérifier une version, indique où se trouve chaque téléchargement Nexus.
Trois adresses
Chaque installation répond sur trois noms d'hôte. Le chart les appelle l'identité de l'installation, et chaque service refuse de démarrer sans eux.
| Clé des valeurs | Nom chez Harrow | Ce qui y répond |
|---|---|---|
hosts.console |
console.harrow.example |
La console, l'application web à laquelle les utilisateurs se connectent |
hosts.api |
api.harrow.example |
La passerelle, qui sert l'interface de programmation d'application (API) et achemine chaque requête d'intelligence artificielle (IA) |
hosts.auth |
auth.harrow.example |
Le service de connexion, nexus-auth |
global.domain contient le domaine sous lequel se trouvent les trois hôtes, harrow.example pour nous. Chaque hôte est un nom complet à part entière et peut se trouver sous n'importe quel domaine que vous contrôlez. Nous avons gardé les trois sous un même domaine afin qu'un seul certificat puisse les couvrir.
Créez un enregistrement dans le système de noms de domaine (DNS) pour chacun des trois, pointant vers l'adresse de votre contrôleur d'ingress. Faites-le avant les vérifications préalables. nexusctl preflight recherche chaque nom depuis votre poste de travail et fait échouer l'installation si l'un d'eux n'a pas d'enregistrement, car un utilisateur ne peut pas joindre un nom qui ne peut pas être résolu.
Choisir où se termine le TLS
La clé tls.mode du chart détermine qui détient les certificats pour les trois adresses publiques. Il existe trois choix, et vous pourrez passer de l'un à l'autre ultérieurement lors d'une mise à niveau.
tls.mode |
Vous fournissez | Ce que fait le chart |
|---|---|---|
existing (par défaut) |
Un Secret TLS Kubernetes dans l'espace de noms nexus, nommé dans tls.existingSecret |
Les trois Ingress utilisent cet unique Secret |
cert-manager |
Un ClusterIssuer que vous exploitez, nommé dans tls.clusterIssuer |
Annote chaque Ingress pour que cert-manager émette nexus-console-tls, nexus-api-tls et nexus-auth-tls |
none |
Un équipement en amont du cluster qui assure la terminaison TLS, tel que votre propre répartiteur de charge | Génère les Ingress sans section TLS |
Avec existing, un seul certificat sert les trois hôtes ; il doit donc mentionner les trois, soit sous forme de trois noms alternatifs du sujet (SAN), soit sous forme d'un certificat générique (wildcard) pour votre domaine. Nous avons utilisé un certificat de la CA interne de Harrow. Les vérifications préalables lisent le Secret avant l'installation et émettent un avertissement si son certificat expire dans moins de 30 jours.
Avec cert-manager et un émetteur ACME (Automatic Certificate Management Environment), le chart n'ajoute aucune redirection propre, de sorte qu'une requête /.well-known/acme-challenge/ sur le port 80 atteint le solveur intacte. N'ajoutez pas sur votre contrôleur d'ingress de redirection HTTP vers HTTPS qui s'exécuterait avant le chemin du défi ; un certificat qui ne peut pas être renouvelé échoue silencieusement, des semaines plus tard.
Quel que soit votre choix pour la périphérie publique, les services à l'intérieur de l'espace de noms communiquent toujours via TLS à partir de la CA locale du chart. Cette partie n'est pas optionnelle, et c'est pourquoi cert-manager est un prérequis même lorsque tls.mode est défini sur existing ou none.
Ce qui sort du cluster, et ce qui n'en sort pas
Le chart génère une politique réseau de refus par défaut pour l'espace de noms nexus. Après cela, seuls les flux suivants sont autorisés :
- le trafic entre les pods Nexus à l'intérieur de l'espace de noms ;
- les requêtes DNS vers le service DNS du cluster ;
- le serveur d'API Kubernetes, pour les quelques services qui vérifient les jetons des charges de travail ;
- l'espace de noms du contrôleur d'ingress, vers les trois Services publics ;
- toutes les plages CIDR (Classless Inter-Domain Routing) que vous listez dans
networkPolicy.externalEgressCIDRs.
Cette dernière liste est vide par défaut. Si vous prévoyez d'utiliser un relais de messagerie ou un serveur de modèles en dehors du cluster, sa plage doit y figurer. La télémétrie est désactivée et le reste : le schéma n'accepte que telemetry.enabled: false, et les rapports d'utilisation propres aux magasins de données sont également désactivés.
Le chart lit les adresses du serveur d'API depuis le cluster lors de l'installation. Si votre compte ne peut pas lire les Endpoints kubernetes dans l'espace de noms default, indiquez-les vous-même dans networkPolicy.apiServerCIDRs, sous forme de plages /32. proxy.trustedCIDRs désigne le réseau de pods sur lequel se trouve votre contrôleur d'ingress, afin que nexus-auth sache à quel en-tête X-Forwarded-For se fier. La valeur par défaut, 10.42.0.0/16, correspond au réseau de pods de k3s.
Dimensionnement
Les requêtes de ressources par défaut du chart totalisent environ 2.05 cœurs de processeur (CPU) et 6.7 GiB de mémoire. C'est ce que réserve l'ordonnanceur ; les limites sont plus élevées, et les magasins de données s'y développent au fur et à mesure que vous ajoutez des utilisateurs et des fichiers.
| Composant | CPU demandé | Mémoire demandée |
|---|---|---|
| Neuf services de plateforme (console, backend for frontend (BFF), auth, orchestrator, workflows, gateway, graphrag, probitas, skills engine) | 1.1 cores | 2.6 GiB |
Le service de clés, nexus-keys |
0.05 cores | 64 MiB |
| PostgreSQL | 0.25 cores | 1 GiB |
| Neo4j | 0.25 cores | 2 GiB |
| Valkey, Qdrant et le stockage objet ensemble | 0.25 cores | 640 MiB |
| Les deux serveurs OpenBao du magasin de clés | 0.15 cores | 384 MiB |
Les volumes par défaut totalisent 142 GiB :
| Magasin | Clé des valeurs | Taille par défaut |
|---|---|---|
| PostgreSQL 16 avec PostGIS 3 et pgvector 0.8 | dataTier.postgres.size |
50Gi |
| Stockage objet (SeaweedFS) | dataTier.objectStore.size |
50Gi |
| Neo4j 5.26 Community Edition | dataTier.neo4j.size |
20Gi |
| Qdrant | dataTier.qdrant.size |
10Gi |
| Valkey | dataTier.valkey.size |
5Gi |
| Le magasin de clés et son service de déverrouillage (unsealer) | keys.openbao.storage.keystore, keys.openbao.storage.unsealer |
5Gi et 1Gi |
| Reçus du service de clés | keys.receiptsStorage |
1Gi |
Pour un nœud unique, prévoyez 8 vCPU, 32 GiB de mémoire vive (RAM) et un disque SSD (solid-state drive) de 250 GB. Pour une évaluation, 4 vCPU, 16 GiB et 200 GB suffiront. L'image disque de l'installateur refuse une machine disposant de moins de 16 GiB de mémoire (voir le chapitre 2.9, L'image disque de l'installateur), et je considérerais cela comme le seuil minimal partout.
Les nœuds graphiques sont facultatifs. Sans nœud offrant un processeur graphique (GPU), l'assistant répond via un modèle hébergé, en utilisant la propre clé de l'organisation. Les vérifications préalables signalent cela comme un avertissement, jamais comme un échec. Le chapitre 2.14, Fournisseurs et modèles d'IA, couvre les deux approches.
Chaque magasin peut également fonctionner en dehors du cluster : définissez dataTier.<store>.mode sur external et indiquez son hôte ainsi qu'un Secret. Un PostgreSQL externe nécessite un compte superutilisateur pour l'amorçage de l'installation et un certificat que Nexus peut vérifier. Le chapitre 2.11, Variantes : magasins externes, TLS et ingress, couvre ce sujet. Si vous les conservez dans le cluster, placez-les sur une classe de stockage reposant sur de vrais disques. La base de données est l'élément qui vous manquera le plus si le disque local d'un nœud tombe en panne.
Le nom de l'installation est permanent
keys.installationName est le nom que les opérateurs donnent à cette installation. Il doit correspondre à ^[a-z][a-z0-9-]{0,62}$ : une lettre minuscule, suivie d'un maximum de 62 lettres minuscules, chiffres ou traits d'union.
La première fois que le magasin de clés démarre, il forge l'identité de l'installation sous ce nom, et cette identité est figée définitivement. Une licence d'Adverant est émise pour cette identité, de sorte qu'une licence créée pour une installation est refusée sur une autre avec LICENCE_OTHER_INSTALLATION. Renommer impliquerait une nouvelle installation, une nouvelle identité et de nouvelles licences.
Le chart n'a pas de valeur par défaut pour le nom. Il refuse une installation sans nom (INSTALLATION_NAME_MISSING) et refuse le nom d'exemple provenant de ses propres fichiers de valeurs d'exemple (INSTALLATION_NAME_EXAMPLE). Les vérifications préalables signalent les deux cas avant que vous n'alliez aussi loin.
Chez Harrow, nous avons passé plus de temps là-dessus que je ne voudrais l'admettre. Nous avons opté pour harrow-port-authority : il nomme l'organisation, ne dit rien sur le cluster sur lequel il tourne, et restera valable lorsque le matériel sera remplacé. Évitez les noms comme prod-k3s-2 qui décrivent les machines d'aujourd'hui.
Garde des clés
Nexus conserve les clés de chaque organisation dans son propre magasin de clés, à l'intérieur du cluster. Vous n'avez pas à le gérer au quotidien, mais vous devez décider, avant l'installation, qui pourra le rétablir après un redémarrage. C'est la décision qui coûte le plus cher si vous vous trompez.
Le magasin de clés est composé de deux serveurs OpenBao. Le serveur principal, openbao, détient les clés et se déverrouille via un second serveur plus petit, openbao-unsealer. Ce service de déverrouillage (unsealer) est scellé avec le schéma de Shamir : cinq parts, dont trois quelconques suffisent à l'ouvrir. Lorsque vous installez, un Job de garde initialise les deux serveurs à l'intérieur du cluster. Dans la mémoire de ce Job, il chiffre les parts du service de déverrouillage et les clés de récupération du magasin de clés pour chaque dépositaire que vous nommez, ne stocke que le texte chiffré (dans les Secrets openbao-unseal-shares-encrypted et openbao-recovery-keys-encrypted), et révoque les deux jetons root avant de se terminer. Aucune part en clair n'atteint jamais un disque ou un journal.
Après tout redémarrage du nœud du service de déverrouillage, celui-ci démarre à l'état scellé. Le magasin de clés l'attend, et rien de ce qui nécessite une clé ne fonctionne tant qu'un dépositaire ne l'a pas déverrouillé. Cela ne demande qu'un seul déchiffrement avec la clé privée du dépositaire. La procédure figure au chapitre 2.15, Jour 2 : exploiter Nexus.
Créer une clé de dépositaire
Un dépositaire est désigné par la moitié publique d'une clé age, appelée son destinataire (recipient). Chaque dépositaire crée sa propre clé sur sa propre machine et ne vous remet que le destinataire :
age-keygen -o custodian.keyLa ligne # public key: du fichier est le destinataire, commençant par age1. Un dépositaire disposant d'un Mac peut conserver la clé dans la Secure Enclave du Mac à la place, de sorte que la moitié privée ne quitte jamais la puce et que chaque utilisation demande une empreinte digitale :
age-plugin-se keygen --access-control=any-biometry -o custodian.keyCe destinataire commence par age1se1. Le Job de garde chiffre vers cinq formes de destinataires : age1 (X25519), age1tag1 et age1tagpq1 (tag), age1pq1 (hybride post-quantique) et age1se1 (Secure Enclave). Il refuse toute autre forme de plugin, telle que age1yubikey1 ; nommez plutôt cette clé dans l'une des formes acceptées.
Le chart vérifie chaque destinataire lors du rendu. Un destinataire mal saisi échoue à sa somme de contrôle bech32 et est refusé, de sorte que rien n'est jamais scellé avec une clé que personne ne détient. Si quelqu'un colle par erreur une clé privée dans la liste, le chart la refuse sans la réafficher. Le destinataire d'exemple figurant dans les fichiers de valeurs du chart est également refusé (KEYS_CUSTODIAN_EXAMPLE) ; personne ne détient sa moitié privée.
Combien de dépositaires
Chaque part est chiffrée pour chaque dépositaire, de sorte qu'un seul dépositaire peut déverrouiller l'ensemble de manière autonome. Plus il y a de dépositaires, plus il y a de moyens de récupération et plus il y a de personnes pouvant agir seules. Nous en avons choisi trois chez Harrow : Aoife, moi-même, et une clé Secure Enclave sur un ordinateur portable de secours conservé dans le coffre-fort du port. Deux est le minimum que j'accepterais. Un seul constitue un point de défaillance unique qui sera, tôt ou tard, en congé lorsqu'un nœud redémarrera.
Choisir l'édition
edition vaut community ou enterprise, et enterprise.enabled doit concorder avec elle. Le chart refuse toute incohérence, et il refuse toute édition qui n'est pas l'une des deux.
L'édition détermine également quelles images vous installez. Chaque paquet de chart contient un verrou d'images (images lock), la liste de chaque image par condensat (digest), pour une édition donnée. Une installation Community ne prend que les images Community. Une installation Enterprise prend le verrou Enterprise, qui comprend les images Community plus les versions Enterprise, et les télécharge avec un jeton de tirage (pull token) issu de votre compte Adverant. Le chapitre 2.4, Obtenir et vérifier une version, explique le verrou, et le chapitre 2.2, Les éditions sous le capot, explique ce que contient chaque édition.
Vous n'avez pas à décider définitivement. Une installation Community passe à Enterprise sur place, en conservant ses utilisateurs, ses fichiers et son historique ; le chapitre 2.7, Installer Enterprise et appliquer une licence, montre comment procéder. Nous avons exécuté Community pour le pilote chez Harrow et avons migré six semaines plus tard.
La licence ne fait jamais partie de ce plan. Ce n'est ni une valeur du chart ni un fichier monté : vous l'importez après l'installation, via la console, nexusctl ou l'API.
Choisir la forme de livraison
| Format | Quand il convient | Chapitre |
|---|---|---|
Chart Helm depuis registry.adverant.ai |
Votre propre cluster Kubernetes, avec un accès au registre | 2.6 et 2.7 |
nexusctl install |
Le même cluster, avec les vérifications préalables et le contrôle de signature exécutés pour vous | 2.6 |
nexusctl install --single-node |
Une seule machine, où nexusctl configure également le cluster |
2.8 |
| L'image disque de l'installateur | Un serveur nu ou une machine virtuelle (VM) que vous préférez ne pas préparer manuellement | 2.9 |
| L'archive hors ligne | Aucun accès vers l'extérieur ; les images et le chart arrivent sur un disque | 2.10 |
Le chart est le même sous toutes les formes. Ce qui change, c'est qui crée le cluster et d'où proviennent les images.
La fiche de planification
Voici celle de Harrow, telle qu'Aoife l'a validée. Copiez les deux colonnes de gauche et remplissez celle de droite pour votre propre installation.
| Décision | Clé des valeurs ou commande | Harrow Port Authority |
|---|---|---|
| Kubernetes et version | (lu par les vérifications préalables) | k3s v1.33.6+k3s1, trois nœuds |
| Contexte Kube pour l'installation | --context |
harrow-prod |
| Espace de noms | --namespace |
nexus |
| Édition | edition, enterprise.enabled |
community pour le pilote, puis enterprise |
| Registre d'images | global.imageRegistry |
registry.adverant.ai |
| Domaine | global.domain |
harrow.example |
| Adresse de la console | hosts.console |
console.harrow.example |
| Adresse de l'API | hosts.api |
api.harrow.example |
| Adresse de connexion | hosts.auth |
auth.harrow.example |
| TLS en périphérie | tls.mode, tls.existingSecret |
existing, Secret harrow-public-tls issu de la CA interne de Harrow |
| Classe d'ingress | ingress.className |
traefik |
| Espace de noms d'ingress | networkPolicy.ingressNamespace |
kube-system |
| Classe de stockage | storage.className |
local-path |
| Magasins de données | dataTier.<store>.mode |
Tous sur in-cluster, tailles par défaut |
| Plages sortantes | networkPolicy.externalEgressCIDRs |
Uniquement la plage du relais de messagerie |
| Nom de l'installation (permanent) | keys.installationName |
harrow-port-authority |
| Dépositaires (permanents dans les faits) | keys.custody.recipients |
Trois : Aoife Brennan, Tomás Reilly, l'ordinateur portable du coffre (age1se1) |
| Nœuds graphiques | (lu par les vérifications préalables) | Aucun pour le pilote connecté ; modèle hébergé avec la propre clé de Harrow |
| Premier administrateur | nexusctl claim-code --administrator |
aoife.brennan@harrow.example |
Deux lignes de cette fiche sont irréversibles : le nom de l'installation, et les dépositaires au sens où les perdre tous fait perdre le magasin de clés. Faites valider ces deux points par une personne habilitée à donner son accord. Tout le reste n'est qu'une modification de valeurs.
Une fois la fiche de travail remplie, passez au chapitre 2.4, Obtenir et vérifier une version, et récupérez la version.
