Version 1.0.0-alpha.1dernière version
Chapitre 2.6
Installer l'édition Community sur Kubernetes
Une installation étape par étape de l'édition Community avec Helm, de cert-manager jusqu'à ce que chaque charge de travail soit prête, avec le fichier values expliqué clé par clé, la raison de l'absence de --wait, l'ordre d'exécution des hooks du chart, et la méthode d'installation via nexusctl comme alternative.
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

L'installation elle-même se résume à un seul helm install. Tout ce qui l'entoure est là pour que cette unique commande fonctionne du premier coup : cert-manager en amont, un fichier de valeurs que vous avez lu ligne par ligne, et une attente en aval qui sait exactement quoi attendre. Chez Harrow Port Authority, nous avons d'abord installé l'édition Community, pour un pilote de six semaines, sur le cluster k3s à trois nœuds défini dans notre fiche de planification. La version était opérationnelle en une vingtaine de minutes, et personne ne pouvait se connecter tant que nous ne l'avions pas revendiquée, comme il se doit.
Ce chapitre suppose que vous avez déjà accompli trois choses : rempli la fiche de planification (chapitre 2.3, Planifier une installation), récupéré et vérifié la version (chapitre 2.4, Obtenir et vérifier une version), et exécuté les vérifications préalables (chapitre 2.5, Vérifications préalables avec nexusctl). Si l'une de ces étapes est encore en suspens, revenez en arrière. L'installation refuse la plupart des erreurs en les nommant, mais elle ne peut pas en détecter certaines, comme un dépositaire dont vous auriez déjà perdu la clé.
Étape 1 : confirmer vos outils et votre contexte
Vérifiez que Helm est en version 4.
helm versionL'installation repose sur le fait que Helm 4 attend par défaut la fin des Jobs de hook du chart. Nous avons utilisé la v4.3.1.
Pointez
kubectlvers le cluster de votre fiche de planification et confirmez.kubectl config use-context harrow-prod kubectl get nodesChaque nœud doit afficher
Ready. Les vérifications préalables l'ont déjà contrôlé, mais un nœud peut tomber entre cette étape et l'installation, et il est plus rapide de le constater ici.
Étape 2 : installer d'abord cert-manager
Le chart crée sa propre autorité de certification (CA) locale avec cert-manager, et chaque service communique avec les autres au moyen des certificats qu'elle émet : un Issuer auto-signé, un certificat de CA locale valable dix ans et des certificats à courte durée de vie pour les services. Par conséquent, cert-manager doit fonctionner avant Nexus. La version requiert la v1.21.3 et ne nécessite pas trust-manager.
Installez cert-manager à partir de son propre chart, avec ses ressources personnalisées :
helm install cert-manager <cert-manager-chart> -n cert-manager --create-namespace \ --set crds.enabled=true --wait --timeout 10m<cert-manager-chart>est le chart cert-manager v1.21.3 issu de la version officielle du projet cert-manager. L'attente est appropriée ici ; il s'agit de l'installation propre à cert-manager, sans hooks dépendant d'autre chose.Attendez son webhook, par lequel transite chaque demande de certificat :
kubectl -n cert-manager rollout status deploy/cert-manager-webhook --timeout=300sdeployment "cert-manager-webhook" successfully rolled out
Étape 3 : créer l'espace de noms et le Secret TLS
Avec tls.mode: existing, le chart s'attend à trouver votre certificat sous forme de Secret Kubernetes dans l'espace de noms avant l'installation. La sécurité de la couche de transport (TLS) pour les trois adresses provient de cet unique Secret ; son certificat doit donc mentionner les trois hôtes.
kubectl create namespace nexus
kubectl -n nexus create secret tls harrow-public-tls \
--cert=harrow-public.crt --key=harrow-public.keyharrow-public.crt est le certificat, avec sa chaîne, et harrow-public.key sa clé privée. Si vous avez choisi tls.mode: cert-manager ou none au chapitre 2.3, Planifier une installation, ignorez le Secret ; vous pouvez tout de même créer l'espace de noms maintenant, ou laisser Helm le faire avec --create-namespace à l'étape 6.
Étape 4 : rédiger le fichier values
Voici le fichier de valeurs de Harrow pour le pilote. Chaque clé qu'il contient est acceptée par le schéma du chart ; le schéma refuse toute autre clé, de sorte qu'une faute de frappe fait échouer l'installation au lieu d'être ignorée silencieusement.
# 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>"Chaque <recipient-...> correspond au destinataire public age d'un dépositaire, c'est-à-dire la ligne age1... ou age1se1... qu'il vous a envoyée. Voici chaque clé que nous avons définie, et pourquoi.
global.imageRegistry est le registre depuis lequel vos nœuds récupèrent les images. Le chart n'a pas de valeur par défaut ; il construit chaque nom d'image sous la forme <this>/nexus/<service>@<digest>. Pour une installation connectée, il s'agit de registry.adverant.ai. Si vous avez copié les images dans votre propre registre, il s'agit de cet hôte.
global.domain est le domaine sous lequel se trouvent les trois adresses.
hosts.console, hosts.api et hosts.auth constituent l'identité de l'installation : les trois noms qu'utilisent les personnes et les programmes. Chacun doit déjà être résolu dans le système de noms de domaine (DNS), ce que les vérifications préalables ont contrôlé.
edition et enterprise.enabled doivent concorder : community avec false, ou enterprise avec true. Le chart refuse toute autre combinaison, et il refuse une édition pour laquelle son fichier de verrouillage des images n'a pas été conçu.
tls.mode et tls.existingSecret déterminent la façon dont la bordure publique obtient son certificat. Avec cert-manager, vous définiriez plutôt tls.clusterIssuer, et avec none, aucun des deux.
ingress.className nomme la classe d'ingress. Ne la définissez pas pour utiliser la classe par défaut du cluster.
storage.className nomme la classe de stockage pour chaque volume de données. Ne la définissez pas pour utiliser la valeur par défaut.
networkPolicy.ingressNamespace est l'espace de noms dans lequel s'exécute votre contrôleur d'ingress. La valeur par défaut, kube-system, convient au Traefik de k3s ; nous l'avons tout de même définie pour que le fichier l'indique explicitement.
networkPolicy.externalEgressCIDRs répertorie les plages d'adresses, en notation CIDR (Classless Inter-Domain Routing), situées en dehors de l'espace de noms et que les services sont autorisés à joindre, au-delà du DNS et du serveur d'interface de programmation d'application (API) de Kubernetes. La nôtre contient l'adresse unique du relais de messagerie ; si la liste est vide, rien en dehors de l'espace de noms n'est joignable.
keys.installationName est le nom permanent sous lequel le magasin de clés émet l'identité de l'installation.
keys.custody.recipients répertorie les destinataires publics age des dépositaires. Le Job de garde chiffre chaque part de déverrouillage et chaque clé de récupération pour chacun d'entre eux.
Clés dont vous pourriez avoir besoin et clés à ne pas modifier
| Clé | Quand la définir |
|---|---|
networkPolicy.apiServerCIDRs |
Lorsque le chart ne peut pas lire les adresses du serveur d'API à partir des Endpoints kubernetes. Indiquez-les sous forme de plages /32 |
proxy.trustedCIDRs |
Lorsque les pods de votre contrôleur d'ingress ne se trouvent pas dans la plage d'adresses 10.42.0.0/16 de k3s |
ai.localProvider.baseUrl |
Lorsque l'organisation exécute son propre serveur de modèles d'intelligence artificielle (IA) compatible avec OpenAI (chapitre 2.14, Fournisseurs et modèles d'IA) |
ai.installationHosts |
Lorsque ce serveur de modèles utilise des noms privés à l'intérieur de l'installation |
dataTier.<store>.size |
Lorsqu'un magasin de données a besoin de plus d'espace que son volume par défaut |
dataTier.<store>.mode |
external pour un magasin de données que vous gérez vous-même (chapitre 2.11, Variantes : magasins externes, TLS et ingress) |
components.<service>.replicas, components.<service>.resources |
Lorsque vous augmentez le dimensionnement d'un service |
auth.rateLimitPerMinute |
Lorsqu'une automatisation intensive nécessite plus de 5 000 requêtes par minute et par personne |
schemaWait.timeoutSeconds |
Lorsqu'un disque lent fait durer les premières migrations plus de 30 minutes |
Laissez istio.enabled à false ; Nexus n'a pas besoin de maillage de services. Laissez telemetry.enabled à false ; le schéma n'accepte aucune autre valeur. Laissez orchestrator.platformServiceUserId et probitas.flags tels que le chart les définit.
Aucun identifiant n'est jamais passé comme valeur du chart. Il n'existe aucune clé pour la clé d'API d'un fournisseur de modèles, un mot de passe de messagerie ou un jeton de récupération d'image. Les services génèrent leurs propres secrets internes lors de l'installation et les conservent lors des mises à niveau, et les clés de modèles de chaque organisation sont ajoutées à son propre pool de clés depuis la console après la première exécution.
Étape 5 : exécuter la vérification préalable sur le fichier final
nexusctl preflight --context harrow-prod --values harrow-values.yamlL'exécution doit se terminer par 0 failed. Le chapitre 2.5, Vérifications préalables avec nexusctl, explique chaque ligne. Si vous avez modifié quoi que ce soit depuis la dernière exécution, même un dimensionnement, relancez-la.
Étape 6 : installer, sans --wait
helm install nexus oci://registry.adverant.ai/nexus/charts/nexus --version 1.0.0-alpha.1 \
--namespace nexus -f harrow-values.yaml --timeout 45mSi vous n'avez pas créé l'espace de noms à l'étape 3, ajoutez --create-namespace. Si vous effectuez l'installation à partir d'un fichier de chart que vous avez téléchargé et vérifié, indiquez son chemin à la place de la référence oci://.
N'ajoutez pas --wait. L'initialisation de la base de données du chart s'exécute sous forme de hook post-installation, une fois que les ressources propres à la version existent, et c'est ce hook qui attribue à chaque service son rôle et son mot de passe de base de données. --wait bloquerait l'installation jusqu'à ce que chaque Deployment soit à l'état Available, or aucun Deployment ne peut devenir Available avant l'exécution du hook qu'il attend. Les services restent bloqués en voyant leurs connexions à la base de données refusées, et Helm les attend jusqu'à l'expiration du délai. Sans --wait, Helm 4 attend tout de même chaque Job de hook, dans l'ordre, et c'est bien cette attente qu'il vous faut.
Lorsque le dernier hook est terminé, Helm affiche son résumé :
NAME: nexus
NAMESPACE: nexus
STATUS: deployed
REVISION: 1
STATUS: deployed signifie que chaque hook a réussi. Cela ne signifie pas encore que chaque service est prêt à répondre ; l'étape 7 s'en assure.
Ce qui s'exécute, et dans quel ordre
Helm exécute les hooks par poids, du plus faible au plus élevé, et attend la fin de chacun avant de passer au suivant. Chaque Job de migration possède backoffLimit: 0 : une migration qui échoue fait échouer l'installation et n'est jamais relancée à votre insu. Un Job qui réussit est supprimé ; un Job qui échoue est conservé, avec son journal, pour que vous puissiez le consulter.
| Poids | Hook | Ce qu'il fait |
|---|---|---|
| -30 | Prérequis | Le compte de hook nexus-migrations, le Secret réservé aux hooks nexus-migrations-env contenant les identifiants de base de données générés, ainsi que le compte, le rôle, la configuration et le certificat du Job de garde |
| -20 | nexus-db-bootstrap |
Crée les bases de données et les rôles, dont aucun n'est superutilisateur ni ne peut contourner la sécurité au niveau des lignes (RLS) ; ajoute les extensions, parmi lesquelles PostGIS et pgvector ; crée le registre des versions |
| -15 | nexus-openbao-custody-init |
Initialise le magasin de clés et son service de déverrouillage, chiffre les parts et les clés de récupération pour vos dépositaires, révoque les deux jetons racine et émet l'identité de l'installation sous keys.installationName |
| -12 | nexus-graphrag-migrations |
Pose d'abord le schéma du service de graphe, car le schéma du service de connexion fait référence à des objets qu'il possède |
| -10 | nexus-auth-migrations |
Pose le schéma du service de connexion ainsi que ses deux rôles d'exécution |
| -5 | nexus-orchestrator-migrations, nexus-gateway-migrations, nexus-probitas-migrations |
Le schéma propre à chaque service ; probitas s'exécute après auth car il vérifie d'abord les tables d'auth |
| 0 | nexus-alpha-bff-migrations |
Provisionne la base de données du backend for frontend (BFF) et ses rôles, puis applique ses migrations |
Chaque hook de migration se termine en écrivant une ligne dans le registre des versions, nexus_release.schema_applied : le nom de sa chaîne et le condensat (digest) de l'image qui l'a exécutée. Il n'écrit cette ligne qu'une fois que son exécuteur de migration a terminé sans erreur. Le Job d'initialisation affiche db-bootstrap: done ; les hooks de migration SQL affichent schema-ledger: recorded <chain> for this release's image en dernière ligne. Le hook de migration propre à la console, nexus-alpha-bff-migrations, enregistre sa ligne de la même manière, puis affiche bff-migrate: done.
Comment les services attendent leur schéma
Les Deployments démarrent dès que Helm les crée, pendant que les hooks sont encore en cours d'exécution. Un service qui démarrerait face à une base de données sans rôle, sans mot de passe ou sans schéma planterait et redémarrerait en boucle jusqu'à la fin des hooks. C'est pourquoi chaque Deployment qui utilise la base de données comporte un conteneur d'initialisation, wait-for-schema, qui retient le pod à la place.
Il lit le registre des versions en tant que nexus_ledger_reader, un identifiant de connexion qui ne peut lire que cette unique table et rien d'autre, et attend que le registre affiche ses chaînes pour les condensats d'images de cette version. Il interroge la table toutes les schemaWait.intervalSeconds (3 par défaut), affiche son état lorsqu'il change et toutes les vingt interrogations, et abandonne après schemaWait.timeoutSeconds (1 800 par défaut) avec un échec qui nomme le service.
| Déploiement | Attend |
|---|---|
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 |
Pour observer l'attente d'un service en temps réel, consultez le journal de son conteneur d'initialisation :
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
Comme l'attente est indexée sur le condensat de l'image et non sur un nombre de fichiers, les pods d'une mise à niveau ultérieure attendent les lignes de la nouvelle version, et un pod qui redémarre après une modification portant uniquement sur les valeurs trouve sa ligne immédiatement.
Étape 7 : attendre que chaque charge de travail soit prête
Attendez les Deployments, avec un délai maximal :
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
Puis les StatefulSets. Les deux serveurs du magasin de clés ne se mettent à jour que lorsque vous supprimez leurs pods, et kubectl rollout status refuse cette stratégie de mise à jour ; attendez donc plutôt le nombre de pods prêts :
for s in $(kubectl -n nexus get statefulset -o name); do
kubectl -n nexus wait "$s" --for=jsonpath='{.status.readyReplicas}'=1 --timeout=900s
doneChacun affiche condition met. Sur notre cluster, les deux attentes cumulées ont pris moins de cinq minutes après la fin de l'exécution de Helm.
À quoi ressemble un état prêt
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
Dix Deployments et sept StatefulSets, tous prêts. À leurs côtés, vous trouverez trois CronJobs, nexus-keys-rotate-epoch, nexus-keys-run-schedule et nexus-keys-export-receipts, chargés de la maintenance nocturne du service de clés. kubectl -n nexus get jobs ne devrait lister aucun Job de hook : ceux qui ont réussi ont été supprimés.
Deux choses méritent d'être faites avant de quitter le terminal. Enregistrez (commit) le fichier de valeurs à l'endroit où votre équipe conserve la configuration ; chaque mise à niveau repart de ce fichier. Et ne touchez pas au Secret nexus-generated. Le chart génère les mots de passe et les clés internes une seule fois, lors de l'installation, les y conserve et les relit à chaque mise à niveau ; le supprimer empêcherait donc les services d'accéder à leurs propres données.
« Prêt » signifie que la plateforme fonctionne et n'est pas encore revendiquée. Ouvrez https://console.harrow.example et vous arriverez sur l'installateur, et non sur une page de connexion : personne ne peut se connecter tant que quelqu'un n'a pas revendiqué l'installation. C'est l'objet de la première exécution, au chapitre 2.12, La première exécution.
En cas d'échec
La plupart des échecs s'identifient d'eux-mêmes. Lisez le message avant de modifier quoi que ce soit.
| Ce que vous voyez | Cause | Que faire |
|---|---|---|
INSTALLATION_NAME_MISSING ou INSTALLATION_NAME_EXAMPLE |
keys.installationName est vide ou contient la valeur d'exemple |
Définissez votre propre nom permanent |
KEYS_CUSTODIAN_MISSING ou KEYS_CUSTODIAN_EXAMPLE |
Aucun dépositaire, ou celui de l'exemple | Définissez les destinataires propres à vos dépositaires |
keys.installationName ... does not match ^[a-z][a-z0-9-]{0,62}$ |
Majuscules, points ou chiffre en première position | Utilisez des lettres minuscules, des chiffres et des traits d'union, en commençant par une lettre |
keys.custody.recipients: ... et un motif |
Un destinataire comporte une faute de frappe, est une clé privée ou a un format pour lequel le Job de garde ne peut pas chiffrer | Redemandez son destinataire au dépositaire |
hosts.console is required (the installation identity) |
Un hôte n'est pas défini | Définissez les trois hôtes |
tls.existingSecret is required when tls.mode is existing |
Aucun Secret nommé | Définissez-le, ou modifiez tls.mode |
networkPolicy.apiServerCIDRs is empty and the kubernetes Endpoints could not be read |
Votre compte ne peut pas lire les adresses du serveur d'API | Indiquez-les sous forme de plages /32 |
global.imageRegistry is required |
Le registre n'est pas défini | Définissez-le |
Helm attend jusqu'à l'expiration de son délai ; nexus-auth journalise password authentication failed |
--wait a été passé en argument |
Désinstallez et réinstallez sans --wait |
Error: ... job failed nommant un hook |
Une migration a échoué | kubectl -n nexus logs job/<hook-name> et lisez ses dernières lignes |
Un pod bloqué à l'état Init |
Son wait-for-schema est toujours en attente |
Lisez son journal : il nomme la chaîne qui lui manque |
wait-for-schema: FAILED |
Le hook de la chaîne n'a jamais écrit sa ligne | Trouvez d'abord la cause de l'échec de ce hook |
ImagePullBackOff |
Le nœud ne parvient pas à récupérer l'image depuis global.imageRegistry |
Vérifiez que le nœud peut joindre le registre et, pour l'édition Enterprise, qu'il dispose du jeton de récupération |
Chaque hook qui attend PostgreSQL le fait pendant une durée limitée et l'indique, waiting for postgres (12/60), de sorte qu'une base de données bloquée apparaît dans le journal du hook en moins d'une minute.
La méthode d'installation via nexusctl
nexusctl install effectue la même installation, en exécutant pour vous les vérifications qui l'entourent. Il prend le même fichier de valeurs :
nexusctl install --context harrow-prod --values harrow-values.yamlIl relance les vérifications préalables et s'arrête si l'un des contrôles se met à échouer. Il vérifie la signature de l'archive du chart à l'aide de la clé de la version. Ensuite, il procède à l'installation, attend la fin des hooks et des charges de travail, et affiche chaque étape avec sa durée. --edition community indique l'édition sur la ligne de commande en plus du fichier. --ca-bundle <file> ajoute vos propres certificats de CA, tout comme pour les vérifications préalables. Pour voir les opérations helm et kubectl qu'il exécuterait, sans les lancer réellement, ajoutez --explain :
nexusctl install --context harrow-prod --values harrow-values.yaml --explainLorsqu'il a terminé, il affiche l'adresse de revendication, un code de revendication à usage unique et l'empreinte de l'installation :
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>
Le code comporte trois groupes et autorise cinq tentatives ; l'empreinte est composée de huit groupes de quatre caractères, et le navigateur affiche ces mêmes huit groupes afin que vous puissiez les comparer avant de revendiquer l'installation.
Passage de relais vers le premier lancement
Si vous avez effectué l'installation avec Helm, générez vous-même le code de revendication, en nommant la personne qui sera le premier administrateur :
nexusctl claim-code --administrator aoife.brennan@harrow.exampleCette commande exécute la commande de code de revendication propre au service de clés dans le pod nexus-keys à l'aide de votre accès au cluster, et affiche l'adresse, le code et l'empreinte comme ci-dessus. Le code est valable 30 minutes ; relancez la commande pour en obtenir un nouveau.
À partir de là, tout se passe dans le navigateur : revendiquez l'installation, créez le premier administrateur avec une clé d'accès (passkey) et effectuez les six étapes requises avant que quiconque ne se connecte. C'est l'objet du chapitre 2.12, La première exécution. Si vous comptez activer une licence Enterprise immédiatement, lisez d'abord le chapitre 2.7, Installer Enterprise et appliquer une licence, car la licence fait partie de ces six étapes.

