ConnexionPlanifier un briefing

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

16 minutes de lecture

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.yaml

Il 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.

Avant d'installer
Avant d'installer
La vérification préalable dans le terminal de l'opérateur, avec les décomptes à côté. Notez que chaque avertissement affiche sa solution juste en dessous, et que l'exécution indique clairement qu'elle n'a rien modifié sur le cluster.

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.json

Le 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).

La vérification préalable ne peut pas continuer
La vérification préalable ne peut pas continuer
La page de la console pour une exécution de vérification préalable qui ne peut pas continuer. Les contrôles ayant échoué apparaissent en premier, chacun nommé clairement avec ce qui a été trouvé, et l'installation reste bloquée jusqu'à ce qu'ils réussissent.
Trois colonnes. À gauche, « Poste de travail de l'opérateur » : un encadré « nexusctl preflight --context --values » avec deux sorties en dessous, « preflight-<time>.txt » et « preflight-<time>.json ». Au milieu, « L'installation, non revendiquée » : un encadré « nexus-keys » avec l'étiquette « preflight-record, dernier rapport uniquement ». Une flèche allant de l'encadré de gauche vers nexus-keys porte l'étiquette « exécution sur le pod avec votre propre accès au cluster (--record auto ou always) ». À droite, « Navigateur, avant la connexion » : un encadré « Programme d'installation de la console, La vérification préalable ne peut pas continuer ». Une flèche allant de nexus-keys vers celui-ci porte l'étiquette « GET /v1/installation/preflight ». Sous l'encadré du milieu, une petite note indique « après la revendication : ROUTE_NOT_FOUND ».
Le parcours d'un rapport de vérification préalable, du poste de travail de l'opérateur jusqu'au navigateur.

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.