Version 1.0.0-alpha.1dernière version
Chapitre 2.5
Vérification préalable avec nexusctl
Chaque vérification effectuée par `nexusctl preflight`, ce que chacune lit et comment elle échoue, le rapport qu'elle affiche et enregistre, comment ce rapport parvient à la page de vérification préalable de la console, ainsi que chaque option.
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

Notre première vérification préalable chez Harrow Port Authority a échoué à quatre contrôles, et deux d'entre eux nous auraient coûté bien plus qu'un après-midi. Nous avions commencé le fichier de valeurs en copiant l'exemple du chart, et la vérification préalable a refusé à la fois le nom d'installation et le dépositaire de l'exemple. Personne ne détient la clé privée de ce dépositaire. Une installation scellée avec celle-ci ne pourra jamais être descellée après le redémarrage d'un nœud. La vérification préalable a détecté cela en quelques secondes, avant même qu'il n'y ait quoi que ce soit à perdre.
nexusctl preflight lit votre cluster et votre fichier de valeurs, affiche ce qu'il a trouvé, enregistre un rapport et ne modifie rien sur le cluster. Exécutez-le avant chaque installation et chaque mise à niveau. Ce chapitre couvre chaque contrôle effectué, le format du rapport, l'emplacement où il est enregistré ainsi que les options.
Exploitation
La vérification préalable a besoin de deux éléments : le contexte kube du cluster sur lequel vous allez effectuer l'installation et le fichier de valeurs que l'installation utilisera. Rédigez d'abord le fichier de valeurs ; le chapitre 2.6, Installation de Community sur Kubernetes, détaille chaque clé. Ensuite :
nexusctl preflight --context harrow-prod --values harrow-values.yamlIl lit le cluster via client-go uniquement avec des appels get et list. Si votre tls.mode est existing, créez l'espace de noms nexus et le Secret Transport Layer Security (TLS) avant de l'exécuter (chapitre 2.6, Installation de Community sur Kubernetes, étape 3), sinon le contrôle du certificat signalera le Secret comme manquant.
| Option | Ce qu'il fait | Défaut |
|---|---|---|
--context <name> |
Le contexte kube à vérifier. Obligatoire | aucun |
--values <file> |
Le fichier de valeurs que l'installation utilisera. Obligatoire | aucun |
--namespace <name> |
Où Nexus s'installe | nexus |
--release <version> |
La version en cours de vérification | la propre version du chart inclus |
--report-dir <dir> |
Où les deux fichiers de rapport sont enregistrés | le dossier actuel |
--record <mode> |
auto, always ou never : indique s'il faut transmettre le rapport au service de clés de cette installation, afin que sa page d'installation l'affiche |
auto |
--kubeconfig <file> |
Le kubeconfig à lire | KUBECONFIG, puis ~/.kube/config |
--ca-bundle <file> |
Vos propres certificats d'autorité de certification (CA), pour une chaîne à laquelle les contrôles doivent faire confiance | aucun |
--single-node |
Vérifier une machine pour une installation sur machine unique (chapitre 2.8, Installations sur machine unique) | désactivé |
La version minimale de Kubernetes requise pour cette version n'est pas codée en dur dans nexusctl. Il lit la limite inférieure du propre kubeVersion du chart qu'il contient, de sorte que le contrôle et helm install ne peuvent jamais être en désaccord.
Ce qu'affiche une exécution
Voici la première exécution de Harrow, telle qu'elle s'est affichée :
Adverant Nexus 1.0.0-alpha.1 · preflight · Tue 10 Nov 2026 08:40 · read-only
Failed first
FAIL Address (api) api.harrow.example → no record people reach Nexus by this name
fix add a DNS record for api.harrow.example that points at the ingress, then run preflight again
FAIL Address (auth) auth.harrow.example → no record people reach Nexus by this name
fix add a DNS record for auth.harrow.example that points at the ingress, then run preflight again
FAIL Key custodians the example custodian of the chart's values-community.yaml and values-enterprise.yaml (age1u63etg5v…) the key store seals its recovery keys to them; no one holds the example custodian's key
fix replace it in keys.custody.recipients in harrow-values.yaml with your custodians' own recipients: each custodian makes a key on their own machine with `age-keygen -o custodian.key` (the `# public key: age1...` line is the recipient), or `age-plugin-se keygen --access-control=any-biometry -o custodian.key` for a Secure Enclave key, keeps the identity file offline, and gives you only the recipient
FAIL Installation name nexus-example, the example name of the chart's values-community.yaml and values-enterprise.yaml the first key-store bootstrap mints the installation identity under it, permanently
fix set keys.installationName in harrow-values.yaml to this installation's own name
Warnings
warn Graphics nodes none the assistant will need a hosted model
fix add a node with a graphics card and its device plugin, or have the assistant use a hosted model
warn Certificate secret harrow-public-tls not found in nexus the public address needs it before people sign in
fix create the TLS secret harrow-public-tls in nexus before installing, or change tls.existingSecret in harrow-values.yaml
Passed
pass Kubernetes version 1.33.6+k3s1 needs 1.33 or later
pass Nodes ready 3 of 3
pass Storage class local-path (default)
pass Resources 24 cores, 93.9 GiB needs 2.1 cores, 6.7 GiB
pass Ingress class traefik (default)
pass Ingress ports traefik (LoadBalancer) on 80 and 443
pass Address (console) console.harrow.example → 10.20.4.10
────────────────────────────────────────────────────────────────────────────
7 passed · 2 warnings · 4 failed Install cannot continue until the failures pass.
Nothing was changed. Report saved to preflight-2026-11-10-0840.txt
Lorsque quelque chose échoue, les échecs apparaissent en premier, suivis des avertissements, puis des réussites. Chaque ligne indique le résultat, le nom du contrôle, ce qui a été trouvé et ce qui est requis ; chaque ligne qui n'a pas réussi comporte une ligne fix en dessous. Les deux dernières lignes sont le résumé et le fichier de rapport.
Nous avons corrigé les valeurs, ajouté les deux enregistrements Domain Name System (DNS), créé le Secret, puis relancé la commande :
Adverant Nexus 1.0.0-alpha.1 · preflight · Thu 12 Nov 2026 09:02 · read-only
Cluster
pass Kubernetes version 1.33.6+k3s1 needs 1.33 or later
pass Nodes ready 3 of 3
pass Storage class local-path (default)
pass Resources 24 cores, 93.9 GiB needs 2.1 cores, 6.7 GiB
warn Graphics nodes none the assistant will need a hosted model
fix add a node with a graphics card and its device plugin, or have the assistant use a hosted model
Network
pass Ingress class traefik (default)
pass Ingress ports traefik (LoadBalancer) on 80 and 443
pass Address (console) console.harrow.example → 10.20.4.10
pass Address (api) api.harrow.example → 10.20.4.10
pass Address (auth) auth.harrow.example → 10.20.4.10
pass Certificate ends 3 Nov 2027
Time and keys
pass Key custodians 3 custodians
pass Installation name harrow-port-authority
────────────────────────────────────────────────────────────────────────────
12 passed · 1 warning · 0 failed You can install. Warnings do not block; fix them when you can.
Report saved to preflight-2026-11-12-0902.txt · nothing was changed on the cluster
Une exécution sans échec répertorie les contrôles sous leurs trois rubriques : Cluster, Network (Réseau) et Time and keys (Heure et clés). Les avertissements ne sont jamais bloquants. Nous avons conservé l'avertissement relatif aux processeurs graphiques à dessein : sur ce cluster pilote connecté, l'assistant de Harrow utilisait un modèle hébergé avec la propre clé du port.
Codes de sortie
| Code | Signification |
|---|---|
0 |
L'installation peut se poursuivre. Les avertissements ne sont pas bloquants |
1 |
L'installation est bloquée : au moins un contrôle a échoué |
2 |
La vérification préalable n'a pas pu s'exécuter : le kubeconfig, le contexte, le fichier de valeurs ou l'interface de programmation d'application (API) du cluster n'ont pas pu être lus, ou une option était incorrecte |
Les scripts doivent lire le code de sortie, pas le texte. Le nôtre exécute la vérification préalable comme première étape de chaque mise à niveau et s'arrête sur toute valeur autre que 0.
Exécutez le nexusctl de la version vers laquelle vous migrez, et non celui avec lequel vous avez effectué l'installation. Les exigences proviennent du chart qu'il embarque ; une version plus récente peut donc relever le seuil minimal de Kubernetes ou demander plus de mémoire, et seul son propre nexusctl le sait. --release modifie la version nommée dans le rapport ; il ne change pas le chart dont les règles sont appliquées. Chez Harrow, nous conservons le nexusctl de chaque version à côté de son chart dans le registre des changements, afin qu'un retour en arrière soit vérifié par l'outil qui lui correspond.
Chaque vérification
Il y a onze contrôles. Dix d'entre eux produisent une ligne chacun ; le contrôle d'adresse produit une ligne par hôte, de sorte qu'une exécution complète comporte treize lignes. Neuf contrôles doivent réussir, et un manquement constitue un échec. Deux contrôles, les nœuds graphiques et le certificat, devraient réussir, et un manquement génère un avertissement. La dernière colonne correspond au texte de l'exigence que chaque ligne reporte dans le rapport ; le terme CPU y désigne l'unité centrale de traitement.
| ID du contrôle | Section | Doit réussir | Exigence affichée |
|---|---|---|---|
kubernetes-version |
cluster | oui | Kubernetes 1.33 ou version ultérieure |
nodes-ready |
cluster | oui | Chaque nœud est prêt |
storage-class |
cluster | oui | Une classe de stockage pour les données |
resources |
cluster | oui | Suffisamment de CPU et de mémoire pour la version |
graphics-nodes |
cluster | non | Nœuds graphiques |
ingress-class |
network | oui | Une classe d'ingress pour les trois adresses |
ingress-ports |
network | oui | Le contrôleur d'ingress ouvert sur les ports 80 et 443 |
address-console, address-api, address-auth |
network | oui | L'adresse console, api ou auth est résolue dans le DNS |
certificate |
network | non | Certificat valide pour encore 30 jours |
custodians |
time-and-keys | oui | Les personnes qui détiennent les clés de récupération de cette installation |
installation-name |
time-and-keys | oui | Le nom permanent propre à cette installation |
kubernetes-version
Lit la version du serveur d'API et la compare au seuil minimal du chart. Il trouve, par exemple, 1.33.6+k3s1. En dessous de 1.33, il échoue avec la solution upgrade the cluster to 1.33 or later. Si la chaîne de version ne peut pas être lue par nexusctl, il échoue plutôt que de deviner.
nodes-ready
Répertorie les nœuds et compte ceux dont la condition Ready est vraie, sous la forme 3 of 3. Tout nœud qui n'est pas prêt est nommé, et la solution vous indique de le ramener à l'état Ready et de lire ses conditions. Un cluster sans aucun nœud échoue en suggérant que le contexte pointe peut-être vers le mauvais cluster.
storage-class
Si vos valeurs définissent storage.className, le contrôle recherche cette classe et échoue avec <name> does not exist lorsqu'elle est manquante. Si ce n'est pas le cas, il recherche une classe marquée par défaut et la signale comme local-path (default). Sans classe par défaut, il échoue avec none marked default, et la colonne des besoins explique pourquoi cela est important : the database cannot claim a disk. Si deux classes sont marquées par défaut, le cluster attribue la plus récente à une nouvelle demande, c'est donc celle-ci qui est signalée.
resources
Calcule ce que la version demande à partir du chart et de vos valeurs, puis additionne les cœurs d'unité centrale de traitement (CPU) et la mémoire allouables de chaque nœud qui est à l'état Ready, non isolé (cordoned), et qui ne porte aucune teinte (taint) NoSchedule ou NoExecute. Les pods du chart ne portent aucune tolérance ; un nœud teinté ne peut donc pas les exécuter et n'est pas pris en compte. Un cluster insuffisant échoue en indiquant le manque exact, tel que add nodes with 1 more core and 2.5 GiB more memory, or lower the sizes under components and dataTier in harrow-values.yaml. Les besoins sont arrondis à l'unité supérieure et les ressources disponibles à l'unité inférieure, de sorte que le contrôle ne vous surestime jamais.
graphics-nodes
Recherche un nœud à l'état Ready doté d'une unité de traitement graphique (GPU) qu'il peut allouer, nvidia.com/gpu. S'il n'y en a aucun, il émet un avertissement : the assistant will need a hosted model. La vérification préalable traite cela comme un conseil et ne bloque jamais l'installation pour cette raison, car l'assistant peut répondre via un modèle d'intelligence artificielle (IA) hébergé à la place. Le chapitre 2.14, Fournisseurs et modèles d'IA, couvre les deux approches.
ingress-class
Si ingress.className est défini, le contrôle recherche cette classe. Sinon, il recherche exactement une classe marquée par défaut. Deux classes marquées par défaut entraînent également un échec, car le serveur d'API refuse alors un Ingress sans classe. Le contrôle est ignoré, et sa ligne omise, lorsque ingress.enabled est défini sur false.
ingress-ports
Recherche dans l'espace de noms nommé par networkPolicy.ingressNamespace (par défaut kube-system, où k3s exécute Traefik) un Service LoadBalancer ou NodePort qui expose à la fois les ports 80 et 443. La politique réseau du chart autorise uniquement cet espace de noms à atteindre les trois Services publics ; un contrôleur d'ingress situé ailleurs ne pourrait donc pas servir Nexus, même s'il était en écoute. La solution indique les deux issues possibles : exposer le contrôleur à cet endroit, ou définir networkPolicy.ingressNamespace sur l'emplacement où il s'exécute. Ignoré lorsque ingress.enabled est défini sur false.
address
Recherche hosts.console, hosts.api et hosts.auth depuis votre poste de travail, à raison de cinq secondes chacun, et affiche une ligne par hôte. Un hôte sans enregistrement échoue avec <host> → no record. Un hôte non défini échoue avec hosts.<key> is not set. Lorsqu'un nom possède plusieurs adresses, la ligne affiche la première, IPv4 avant IPv6, et indique combien il y en a d'autres.
certificate
S'exécute uniquement lorsque tls.mode est défini sur existing et que tls.existingSecret nomme un Secret ; avec cert-manager ou none, il n'y a aucun certificat vous appartenant à lire, et la ligne est omise. Il lit tls.crt depuis le Secret dans l'espace de noms d'installation et rien d'autre. Un certificat valide pour 30 jours ou plus réussit avec ends 3 Nov 2027. Un certificat expirant plus tôt émet l'avertissement ends in 9 days ; un certificat déjà expiré émet l'avertissement ended 4 days ago. Un Secret manquant, ou ne contenant aucun certificat, émet un avertissement accompagné de la solution.
custodians
Lit keys.custody.recipients. S'il n'y en a aucun, il échoue avec le code KEYS_CUSTODIAN_MISSING. Si l'un des destinataires est le dépositaire d'exemple provenant des propres fichiers de valeurs du chart, il échoue avec KEYS_CUSTODIAN_EXAMPLE, car personne ne détient cette clé et les clés de récupération de l'installation ne seraient scellées pour personne. Une réussite affiche le nombre, tel que 3 custodians.
installation-name
Lit keys.installationName. S'il n'est pas défini, il échoue avec INSTALLATION_NAME_MISSING. S'il est défini sur le nom d'exemple provenant des fichiers de valeurs du chart, il échoue avec INSTALLATION_NAME_EXAMPLE. Une réussite affiche le nom. La colonne des besoins explique pourquoi ce paramètre est plus important que la plupart des autres : the first key-store bootstrap mints the installation identity under it, permanently.
Les deux derniers contrôles signalent exactement les codes avec lesquels le chart lui-même refuse une installation. La vérification préalable vous en informe simplement en premier, avant que Helm n'ait créé quoi que ce soit.
Les fichiers de rapport
Chaque exécution enregistre deux fichiers dans --report-dir, nommés d'après l'heure d'exécution : preflight-2026-11-12-0902.txt, contenant les lignes telles qu'affichées sans codes de couleur, et preflight-2026-11-12-0902.json, contenant la même exécution dans un format fixe lisible par un programme. La sortie du terminal et les lignes enregistrées proviennent de la même liste, elles ne diffèrent donc jamais.
Le rapport JSON suit le schéma nexus.preflight/v1 :
| Champ | Contenu |
|---|---|
schema |
Exactement nexus.preflight/v1 |
tool |
Un objet : name (nexusctl) et version |
release |
La version vérifiée |
ran_at |
Le moment de l'exécution, en temps universel coordonné (UTC) |
context |
Le nom du contexte kube |
values |
Le nom de base du fichier de valeurs uniquement |
read_only |
Toujours true |
checks |
Une entrée par ligne : id, section, name, requirement, must_pass, outcome (pass, warn ou fail), found, needs, fix, et en cas de manquement dû à une cause machine, code |
counts |
passed, warnings et failed |
can_install |
true lorsque rien n'a échoué |
report_file |
Le nom du fichier .txt |
transcript |
Un objet : title (nexusctl preflight) et lines, chaque ligne avec son kind (prompt, ok, warn, bad, note, out ou blank), ses text et at, et parfois marks |
Le rapport est conçu pour être affiché avant que quiconque ne se connecte ; il ne contient donc aucun nom d'utilisateur, aucun nom d'hôte de poste de travail, aucun chemin de fichier, aucun jeton et aucun élément provenant de votre kubeconfig. values est un nom de base et context est le nom du contexte. Si le rapport d'une exécution venait à enfreindre l'une de ces règles, nexusctl refuserait de l'afficher, de l'enregistrer ou de le transmettre, et l'indiquerait. Un rapport fait au maximum 256 KiB, avec au plus 64 contrôles et 512 caractères dans un même champ de texte.
Comment le rapport parvient à la console
La seule écriture effectuée par la vérification préalable est le rapport final, transmis au service de clés de l'installation, nexus-keys, afin que le programme d'installation de la console puisse l'afficher sur sa page de vérification préalable avant que quiconque n'ait revendiqué l'installation. --record décide s'il faut tenter l'opération :
--record |
Ce qui se passe |
|---|---|
auto |
Transmet le rapport uniquement lorsque l'espace de noms comporte un Deployment nexus-keys |
always |
Insiste ; la vérification préalable se termine avec le code 2 s'il n'y a rien à quoi le transmettre |
never |
Ne le transmet pas |
Ainsi, une exécution avant la première installation n'a rien à quoi transmettre le rapport et le conserve sur votre poste de travail. Une exécution après l'installation et avant la revendication l'enregistre.
La transmission utilise votre propre accès au cluster. nexusctl exécute /app/nexus-keys preflight-record dans le conteneur keys d'un pod nexus-keys prêt et passe le rapport sur l'entrée standard. C'est l'équivalent de :
kubectl exec -i -n nexus -c keys deploy/nexus-keys -- /app/nexus-keys preflight-record < preflight-2026-11-12-0902.jsonLe service de clés vérifie le rapport selon les mêmes règles que celles appliquées par nexusctl et ne conserve que le plus récent. Lorsqu'il est transmis, nexusctl affiche une ligne supplémentaire pour l'indiquer, et le fichier JSON enregistré reçoit un note qui consigne la transmission.
Le programme d'installation de la console le lit depuis la route publique GET /v1/installation/preflight du service de clés. Cette route ne répond que tant que l'installation n'est pas revendiquée : avant qu'un rapport ne soit enregistré, elle répond 404 RECORD_NOT_FOUND, et une fois que quelqu'un a revendiqué l'installation, elle répond ROUTE_NOT_FOUND définitivement, exactement comme le fait la route de revendication. Un rapport transmis après la revendication est refusé avec INSTALLATION_CLAIMED.
Sur la console, une exécution comportant des échecs apparaît sous le titre « La vérification préalable ne peut pas continuer » : le nombre d'échecs, d'avertissements et de réussites, puis chaque contrôle regroupé sous « Doit réussir » et « Devrait réussir », avec ceux qui n'ont pas réussi en premier et les valeurs trouvées à côté de chacun. Une exécution sans échec n'affiche pas cette page ; la console passe directement à la revendication (chapitre 2.12, La première exécution).
Accès requis pour l'exécution
La vérification préalable s'exécute sous votre identité, avec votre kubeconfig. Le compte doit pouvoir lire :
- les nœuds, pour les contrôles de version, de disponibilité, de ressources et de processeurs graphiques ;
- les classes de stockage et les classes d'ingress ;
- les Services dans l'espace de noms d'ingress ;
- le Secret TLS dans l'espace de noms d'installation, lorsque le contrôle du certificat s'exécute.
Lorsqu'une lecture est refusée, la ligne indique could not read <what> (the cluster refused), et la solution précise quel accès en lecture accorder. Le texte n'inclut jamais l'adresse du serveur ni son propre message d'erreur, car le rapport peut être affiché avant la connexion. La transmission nécessite également pods/exec sur les pods nexus-keys ; sans cela, auto enregistre les fichiers et affiche un avertissement, et always se termine avec le code 2.
Lorsque la vérification préalable elle-même ne peut pas s'exécuter
Le code de sortie 2 signifie qu'aucun rapport n'a été généré. Le message sur la sortie d'erreur standard en indique la raison :
| Message | Que faire |
|---|---|
--context is required: the kube context to check |
Ajoutez --context |
--values is required: the values file the install will use |
Ajoutez --values |
could not read the values file harrow-values.yaml |
Vérifiez le chemin et les permissions du fichier |
preflight takes flags only |
Supprimez l'argument superflu |
the report breaks its contract and was not printed, saved or handed over |
Un champ aurait contenu une information privée ; signalez-le à Adverant avec les options de l'exécution |
--record always: there is no nexus-keys Deployment in the namespace nexus to hand the report to |
Effectuez d'abord l'installation, ou utilisez --record auto |
could not hand the report to this installation |
Vérifiez vos droits d'accès pour exécuter une commande (exec) dans nexus-keys |
Un cluster dont l'API est injoignable se termine également avec le code 2. Corrigez le kubeconfig ou le réseau, puis relancez la commande.
Une fois que la vérification préalable se termine avec 0 failed, passez au chapitre 2.6, Installation de Community sur Kubernetes, pour installer Community, ou au chapitre 2.7, Installation d'Enterprise et application d'une licence, pour Enterprise.

