ConnexionPlanifier un briefing

Chapitre 2.15

Jour 2 : exploiter Nexus

Les tâches courantes d'exploitation d'une installation après la première semaine. Ce chapitre commence par le déverrouillage du magasin de clés après un redémarrage et se termine par la désinstallation.

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

18 minutes de lecture

La première fois qu'une panne de courant est survenue dans la salle des serveurs de Harrow Port Authority, tout a redémarré sauf les composants qui nécessitaient des clés. Les pods étaient à l'état Running et la console se chargeait. Personne ne pouvait ouvrir de fichier. Tomás Reilly avait lu des articles à ce sujet, et il lui a pourtant fallu vingt minutes pour se rappeler pourquoi. Le déverrouilleur du magasin de clés démarre verrouillé après chaque redémarrage de son nœud, et seul un dépositaire peut l'ouvrir.

Ce chapitre suit la routine de l'opérateur après la première semaine, du magasin de clés et de ses dépositaires jusqu'à la désinstallation. Chaque verbe nexusctl présenté ici accepte --explain, qui affiche les opérations kubectl et helm qu'il exécuterait sans les lancer réellement. Utilisez-le la première fois que vous exécutez une commande sur un cluster de production.

Garde du magasin de clés

Une installation comporte deux serveurs OpenBao dans son espace de noms. Le magasin de clés, openbao, détient toutes les clés utilisées par Nexus. Le déverrouilleur, openbao-unsealer, est un second serveur OpenBao de petite taille dont le seul rôle est de déverrouiller le magasin de clés. Le magasin de clés se déverrouille lui-même grâce à la clé de transit du déverrouilleur ; le déverrouilleur est verrouillé selon le schéma de Shamir, sous forme de 5 fragments dont 3 suffisent à le déverrouiller.

Lors de la première installation, un Job de garde initialise les deux serveurs au sein du cluster. Il chiffre les fragments du déverrouilleur ainsi que les clés de récupération du magasin de clés dans sa propre mémoire à destination de chaque dépositaire nommé dans keys.custody.recipients, et ne stocke que le texte chiffré (les Secrets openbao-unseal-shares-encrypted et openbao-recovery-keys-encrypted). Il révoque les deux jetons racine au cours du même Job. Le lot de chaque dépositaire contient suffisamment de fragments pour effectuer le déverrouillage de manière autonome ; un seul dépositaire suffit donc après un redémarrage.

Après le redémarrage d'un nœud

Après tout redémarrage du nœud sur lequel s'exécute le déverrouilleur (coupure de courant, redémarrage de la machine, redémarrage de l'environnement d'exécution de conteneurs), le déverrouilleur démarre verrouillé. Tant qu'un dépositaire ne l'a pas déverrouillé, le magasin de clés reste lui aussi verrouillé, et rien de ce qui nécessite une clé ne fonctionne. La console répond toujours et les utilisateurs peuvent toujours se connecter, mais toute action nécessitant une clé du magasin de clés reste en attente : l'ouverture d'un contenu chiffré, une réclamation, ou la vérification d'un composant compilé.

Interrogez directement OpenBao, à l'intérieur de chaque pod. Voici pour le déverrouilleur :

kubectl -n nexus exec openbao-unsealer-0 -c openbao -- \
  bao status -format=json -address=https://127.0.0.1:8200 \
  -ca-cert=/openbao/tls/ca.crt -tls-server-name=openbao-unsealer
echo "exit $?"

Exécutez la même commande sur openbao-0 avec -tls-server-name=openbao pour le magasin de clés. bao status renvoie le code de sortie 0 lorsque le serveur est déverrouillé, 2 lorsqu'il est verrouillé et 1 lorsqu'il n'a pas pu répondre. Un code de sortie 1 ne permet de tirer aucune conclusion, car le pod n'est peut-être pas encore démarré. Attendez une minute et recommencez. Si le déverrouilleur est déverrouillé et que le magasin de clés est toujours verrouillé, le magasin de clés est en train de se déverrouiller lui-même et vous n'avez rien à faire.

À gauche : une icône de personne intitulée « Dépositaire, avec sa propre identité age ». Une flèche pointe vers la droite dans un encadré « unseal.sh sur la machine du dépositaire (un déchiffrement) ». De là, une flèche intitulée « kubectl port-forward, Transport Layer Security (TLS) vérifié auprès de l'autorité de certification (CA) du déverrouilleur » entre dans un encadré « openbao-unsealer (Shamir 5 fragments, 3 quelconques) ». Depuis le déverrouilleur, une deuxième flèche intitulée « clé de transit, automatique » entre dans un encadré « openbao, le magasin de clés ». Depuis le magasin de clés, un éventail de flèches pointe vers de petits encadrés « nexus-keys », « nexus-auth », « les autres services ». Une note sous le dépositaire : « l'identité ne quitte jamais cette machine ».
Ce que fait un dépositaire après le redémarrage d'un nœud.

Déverrouillage

Le chart fournit unseal.sh, dans son dossier files/custody/, strictement identique octet par octet dans chaque version. Un dépositaire l'exécute sur sa propre machine. Le script lit le Secret chiffré, le déchiffre une fois avec l'identité du dépositaire (une identité Secure Enclave demande Touch ID une seule fois), soumet les fragments au déverrouilleur et confirme qu'il est déverrouillé. Aucun fragment n'est jamais écrit dans un fichier ni passé en ligne de commande.

Harrow l'exécute en mode direct, via une redirection de port :

kubectl -n nexus get secret openbao-unsealer-tls -o jsonpath='{.data.ca\.crt}' | base64 -d > unsealer-ca.crt
kubectl -n nexus port-forward pod/openbao-unsealer-0 28200:8200 &

AGE_IDENTITY=<path-to-your-custodian-identity> \
OPENBAO_NS=nexus \
UNSEAL_ADDR=https://127.0.0.1:28200 \
UNSEAL_CACERT=unsealer-ca.crt \
UNSEAL_RESOLVE=openbao-unsealer.<namespace>.svc \
UNSEAL_SECRET_JSON_CMD='kubectl -n nexus get secret openbao-unseal-shares-encrypted -o json' \
bash unseal.sh

<path-to-your-custodian-identity> est le fichier d'identité age du dépositaire, la moitié privée de l'un des destinataires figurant dans keys.custody.recipients. UNSEAL_RESOLVE est le nom porté par le certificat du déverrouilleur (<namespace> est l'espace de noms dans lequel Nexus est installé, nexus par défaut), de sorte que TLS est vérifié auprès de la propre autorité de certification (CA) du déverrouilleur même si la connexion est établie vers 127.0.0.1. Le script ne désactive jamais la vérification du certificat.

Code de sortie Dernière ligne Signification
0 UNSEALED nexus/openbao-unsealer-0 Déverrouillé. S'il l'était déjà, rien n'a été envoyé
1 STILL-SEALED … Toujours verrouillé, ou un appel de déverrouillage a échoué
2 UNSEAL-REFUSED … Un prérequis est manquant, nommé dans le message
3 UNSEAL-REFUSED … Cette identité ne peut pas déchiffrer les fragments, elle n'est donc pas dépositaire de cette installation. Rien n'a été envoyé

En moins d'une minute, le magasin de clés suit de lui-même. Vérifiez avec kubectl -n nexus get deploy,statefulset que tout est de nouveau prêt.

Les dépositaires sont choisis avant l'installation, et chacun génère sa propre clé sur sa propre machine. Le chart ne voit jamais que la moitié publique :

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

La première commande crée une identité age ordinaire ; son destinataire correspond à la ligne # public key: age1... dans le fichier. La seconde en crée une conservée dans la Secure Enclave d'un Mac, avec un destinataire commençant par age1se1. L'un ou l'autre destinataire est renseigné dans keys.custody.recipients. Le fichier d'identité reste auprès de son dépositaire, hors ligne.

Sauvegarde et restauration

La page Sauvegarde et restauration affiche chaque magasin avec sa dernière sauvegarde et la dernière fois qu'une restauration de celui-ci a été réellement testée. Une sauvegarde n'est prouvée qu'une fois restaurée ; la page assure donc le suivi des deux. Six magasins sont sauvegardés. La base de données principale contient les utilisateurs et les paramètres, les tâches ainsi que le journal d'audit. À ses côtés se trouvent le graphe de connaissances et l'index de recherche, puis le magasin de fichiers et le magasin de mémoire. Les clés constituent le sixième, verrouillées et conservées à l'écart des données. Les sauvegardes sont envoyées vers votre propre espace de stockage, chiffrées avec vos propres clés, et Adverant ne peut pas les lire. Lorsqu'un magasin n'a pas fait l'objet d'un test de restauration dans le délai fixé par votre règle, la page affiche le bandeau RESTORE_TEST_OVERDUE accompagné d'un bouton Tester maintenant. Un test de restauration s'exécute dans un espace séparé sans que personne ne le remarque.

Les deux mêmes actions sont disponibles en ligne de commande :

nexusctl backup now
nexusctl backup verify

backup now effectue une sauvegarde de tous les magasins simultanément. backup verify vérifie la dernière sauvegarde. Exécutez ces deux commandes avant toute modification qui vous préoccupe.

Sauvegarde et restauration
Sauvegarde et restauration
Chaque magasin avec sa dernière sauvegarde et sa dernière restauration testée. L'index de recherche est en retard pour un test, et le bandeau propose d'en lancer un maintenant.

Pour restaurer, vous indiquez le nom de la sauvegarde :

nexusctl restore --from <backup-id>

<backup-id> provient de la liste figurant sur la page Sauvegarde et restauration. Une restauration nécessite l'approbation d'une seconde personne, et pendant son exécution, la barre de progression l'affiche avec l'heure de début et le nom de la personne qui l'a approuvée. Tout le monde est en lecture seule pendant la restauration, ce qui est différent d'un blocage d'accès : les utilisateurs peuvent se connecter et consulter les données. Les tâches ne démarrent pas (les planifications patientent et rattrapent leur retard ensuite), et la recherche redevient disponible lorsque l'index de recherche est rétabli. Tout ce qui a été écrit après la prise de la sauvegarde est perdu ; le rapport de restauration en dresse donc la liste par propriétaire afin que chacun puisse refaire ses modifications.

Restauration en cours
Restauration en cours
Une restauration en cours. Les magasins reviennent dans l'ordre, les utilisateurs sont en lecture seule jusqu'à ce que le dernier soit rétabli, et un avis sur chaque page indique le moment où le retour à la normale est prévu.

Conservez un élément supplémentaire avec vos sauvegardes : le Secret nexus-generated situé dans l'espace de noms nexus. Le chart crée les mots de passe générés et les clés de chiffrement de l'installation lors de la première installation et les relit depuis ce Secret à chaque mise à niveau. Les données scellées sous EXTERNAL_KEY_ENCRYPTION_KEY ne s'ouvrent qu'avec cette clé. Stockez une copie du Secret à l'endroit où vous conservez vos éléments les plus sensibles, car quiconque le détient détient ces clés.

Mises à niveau

Tomás effectue la mise à niveau en deux étapes. D'abord, il demande ce qui va changer :

nexusctl upgrade plan --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

Le plan dresse la liste des nouveautés de la version, de toute modification de la structure de la base de données, et indique si l'opération peut être annulée. Ensuite, il l'applique :

nexusctl upgrade apply --bundle nexus-alpha-1.0.0-alpha.2-enterprise.tar

L'application commence par effectuer une sauvegarde et exécute les vérifications préalables. Elle déplace ensuite les moteurs par vagues, et chaque vague attend que la précédente ait été saine pendant 10 minutes. La page Mise à niveau affiche la progression de chaque vague ainsi que l'état de santé de l'installation pendant ce temps. Elle indique également jusqu'à quand la possibilité de retour en arrière reste ouverte ; après cette date, revenir en arrière nécessite une restauration. Si une étape échoue, Nexus ramène chaque moteur à la version précédente et les vérifie. L'avis UPGRADE_ROLLED_BACK nomme alors l'étape qui a échoué et précise que les données n'ont pas été modifiées. Le correctif est présenté avant le bouton Réessayer, et le lot d'assistance est accessible en un clic.

Pour une installation sans connexion extérieure, le lot arrive sur un support physique. L'importation depuis un support vérifie la signature de la version à l'aide de la clé de publication Adverant installée sur l'installation et s'assure que les versions évoluent uniquement vers l'avant. Les fichiers signés par un tiers sont refusés avec MEDIA_SIGNATURE_INVALID : rien n'est chargé, et la version en cours continue de fonctionner.

Mise à niveau
Mise à niveau
Une mise à niveau en cours. Une sauvegarde a d'abord été effectuée, la deuxième des trois vagues est en cours, et le retour en arrière reste ouvert jusqu'à une date indiquée.
La mise à niveau a échoué et a été annulée
La mise à niveau a échoué et a été annulée
Une vague a échoué car un volume a manqué d'espace. Chaque moteur est revenu à la version précédente avec les données intactes, et le correctif est indiqué avant le bouton Réessayer.

Ce qui se passe en coulisses

nexusctl upgrade apply exécute helm upgrade sur le chart. Si vous effectuez la mise à niveau avec Helm vous-même, les mêmes règles s'appliquent :

helm upgrade nexus oci://registry.adverant.ai/nexus/charts/nexus --version <version> -n nexus -f harrow-values.yaml
kubectl -n nexus wait --for=condition=Available deploy --all --timeout=900s

Le schéma évolue avant le déploiement des nouveaux pods. Les migrations du chart sont des hooks de pré-mise à niveau qui s'exécutent dans l'ordre : d'abord l'amorçage de la base de données, puis les migrations de chaque service, puis celles du backend for frontend (BFF) de la console. Le Job de garde s'exécute également, et sur une installation déjà initialisée, il le confirme et ne modifie rien. Chaque Job de hook a une limite de nouvelles tentatives (backoff limit) fixée à 0, de sorte qu'une migration qui échoue arrête la mise à niveau et n'est jamais relancée silencieusement : lisez son journal avec kubectl -n nexus logs job/<hook-job> avant de réessayer.

Le pod de chaque service patiente dans un conteneur d'initialisation, wait-for-schema, jusqu'à ce que le registre des versions indique que ses migrations ont été appliquées pour l'image de la nouvelle version. Après un retour en arrière, ou une mise à niveau qui n'a modifié que des valeurs, un pod redémarré trouve sa ligne et démarre immédiatement.

Avant la mise à niveau

Trois points des notes de version méritent d'être anticipés :

  1. Effectuez la mise à niveau pendant une période calme. Lors de la première mise à niveau d'une installation créée à partir d'un chart antérieur, la tâche d'amorçage retire les anciens droits de table par défaut, et chaque service récupère les siens via sa propre migration. Tant que cette migration n'a pas été exécutée, un service ne peut pas utiliser ses tables. L'interruption dure quelques secondes. Si ces secondes comptent, réduisez d'abord les services à zéro réplica, puis augmentez à nouveau leur nombre de réplicas une fois les tâches de migration terminées.
  2. Attribuez une organisation à chaque clé d'interface de programmation d'application (API). Une clé sans organisation est refusée avec 403 TOKEN_ORG_MISSING par chaque service qui vérifie les clés via nexus-auth, y compris nexus-graphrag. Avant la mise à niveau, attribuez une organisation à chacune de ces clés ou émettez une nouvelle clé. Les anciennes clés bcrypt continuent de fonctionner jusqu'à leur date de révocation définitive.
  3. Purgez ensuite les clés d'API mises en cache. Jusqu'à une heure d'entrées de clés en cache portent le mauvais nom d'application tant que vous ne l'avez pas fait. Exécutez ceci sur le cache de nexus-auth, le Valkey de l'installation (nexus-valkey, mot de passe dans le Secret nexus-generated sous VALKEY_PASSWORD) :
pw=$(kubectl -n nexus get secret nexus-generated -o jsonpath='{.data.VALKEY_PASSWORD}' | base64 -d)
kubectl -n nexus exec nexus-valkey-0 -- sh -c \
  'valkey-cli -a "$1" --scan --pattern "apikey:prefix:*" | xargs -r valkey-cli -a "$1" del' _ "$pw"

Cela vaut pour le magasin par défaut interne au cluster. Avec dataTier.valkey.mode: external, ce pod n'existe pas : exécutez le même balayage et la même suppression sur votre propre hôte Valkey, avec le mot de passe issu du Secret nommé dans dataTier.valkey.external.existingSecret.

Retour arrière

Pendant la fenêtre qu'affiche la page Mise à niveau, le bouton Revenir en arrière ramène chaque moteur à la version précédente. Après cette fenêtre, revenir en arrière implique de restaurer la sauvegarde effectuée au début de la mise à niveau.

Deux valeurs ne doivent jamais changer lors d'une mise à niveau ou d'un retour en arrière.

keys.installationName est permanent. Le premier amorçage du magasin de clés crée l'identité de l'installation sous cette valeur, et c'est cette identité qui figure sur votre licence. Utilisez exactement la même valeur dans chaque fichier de valeurs que vous appliquez à cette installation.

Le Secret nexus-generated doit rester tel quel. À chaque mise à niveau, le chart y lit EXTERNAL_KEY_ENCRYPTION_KEY et vérifie son format. Une valeur qui n'est ni l'encodage base64 de 32 octets ni la clé brute de 32 octets d'une installation plus ancienne arrête le rendu avec EXTERNAL_KEY_ENCRYPTION_KEY_INVALID, et le chart n'affiche jamais la valeur. Cela signifie que quelqu'un a modifié ou remplacé le Secret. Remettez en place la clé sous laquelle les données de cette installation sont scellées, encodée en base64 sur 32 octets (printf %s "$OLD" | base64), et relancez la mise à niveau. Une nouvelle clé aléatoire rendrait illisible tout ce qui a été scellé sous l'ancienne.

Mise à l'échelle

Chaque composant dispose d'un interrupteur et d'une taille dans le fichier de valeurs. Les composants requis ne peuvent pas être désactivés : le chart les exécute quoi qu'indique leur interrupteur. Les autres peuvent se voir attribuer davantage de réplicas et de ressources.

# harrow-values.yaml (Helm values): scaling
components:
  gateway:
    replicas: 2
    resources: { requests: { cpu: 400m, memory: 1Gi }, limits: { memory: 3Gi } }
  graphrag:
    replicas: 2
  workflows:
    replicas: 2
workflows:
  concurrency: "8"
dataTier:
  qdrant:
    resources: { requests: { cpu: 200m, memory: 512Mi }, limits: { memory: 4Gi } }

Appliquez-le avec helm upgrade comme ci-dessus. Les volumes sont dimensionnés sous dataTier.<store>.size ; vérifiez que votre classe de stockage permet d'agrandir un volume avant d'en augmenter la taille. La page État de l'installation affiche sous forme de graphiques le taux d'occupation des processeurs et de la mémoire du cluster, ainsi que la marge restante pour chacun. Agrandissez en premier celui qui vient à manquer.

Archives de support

Lorsque Harrow a besoin de l'aide d'Adverant, Tomás crée un lot d'assistance :

nexusctl support-bundle --out harrow-support-4471.tar.gz

La page Lot d'assistance de la console génère le même fichier. Elle collecte les journaux des moteurs des dernières 24 heures ainsi que les détails sur l'état de santé et la version. Les paramètres y sont inclus sans leurs secrets, accompagnés des rapports de vérification préalable et d'installation. Avant que quoi que ce soit ne soit écrit, le caviardage remplace les noms et les secrets par des valeurs substitutives, et vous consultez un aperçu de ce qui sortira exactement. Le contenu propre aux utilisateurs n'est jamais collecté. Le lot est transmis à Adverant soit par téléversement sur la page Assistance et lots d'assistance de votre compte, soit sous forme de fichier transporté sur un support physique. Seuls les ingénieurs d'assistance nommés sur la demande peuvent l'ouvrir, et il est effacé au bout de 30 jours.

Lot d'assistance
Lot d'assistance
Création d'un lot d'assistance. L'aperçu du caviardage montre ce qui est masqué avant que quoi que ce soit ne sorte, et seuls les ingénieurs nommés peuvent l'ouvrir.

Exportation de preuves

Les auditeurs et votre propre équipe de conformité demandent souvent la preuve que la plateforme se comporte comme décrit. nexusctl evidence export la produit :

nexusctl evidence export --out harrow-evidence-2027-01

En parallèle des enregistrements qu'elle exporte, la commande exécute les sondes d'acceptation de la plateforme : le routeur d'intelligence artificielle (IA) est joignable et répond, une tâche UNO est distribuée et se termine, et une lecture inter-organisations est refusée. Leurs résultats se trouvent dans probes.json dans le dossier de sortie.

État en un coup d'œil

nexusctl status --json indique si l'installation est saine et dans quel état se trouve chaque composant. Elle rapporte également l'état de la licence avec sa date d'expiration, l'édition et la version en cours d'exécution. Chaque composant compilé est listé avec son condensat et sa signature. C'est la commande à intégrer derrière votre propre système de supervision.

Désinstallation

nexusctl uninstall --profile <profile-file>

<profile-file> est le profil de déploiement du cluster, le même fichier que vous avez passé à nexusctl handoff --profile <profile-file> --out <dir> si votre équipe plateforme gère le cluster. Le transfert rédige, à l'intention de cette équipe, une liste en langage clair de ce que Nexus attend du cluster ainsi que les manifestes permettant d'y répondre. La désinstallation supprime les espaces de noms Nexus et rien d'autre, et elle conserve vos sauvegardes. L'identité de l'installation disparaît avec elle. Une installation ultérieure sur le même cluster constitue une nouvelle installation dotée d'une nouvelle identité ; sa réclamation est donc une nouvelle réclamation et sa licence une nouvelle licence.

Les pages Cette installation

Les opérateurs de l'installation disposent de leur propre groupe dans le menu, Cette installation, et c'est sur ses pages que se déroule l'essentiel de ce chapitre dans la console. Un membre qui ouvre l'une d'elles voit la page Vous n'êtes pas administrateur, qui indique qui est habilité à agir.

Page À quoi elle sert
La licence et ce qu'elle débloque La licence et ses groupes de fonctionnalités (chapitre 2.13, Licences)
Si la licence expire L'échelle d'expiration expliquée clairement, avec les dates de cette licence
Composants compilés Chaque module sous licence avec sa vérification de signature nocturne
Relevé d'utilisation pour Adverant Les compteurs annuels, lisibles avant leur envoi
Versions et mises à niveau Chaque version installée, par qui et quand
Mise à niveau La mise à niveau par étapes et le retour en arrière
Sauvegarde et restauration Chaque magasin, sa dernière sauvegarde et sa dernière restauration testée
État de l'installation Nœuds, capacité et coût de fonctionnement, avec avertissements
Clés et effacement La clé de chaque organisation, et Effacer avec un motif et une seconde personne
Incidents Problèmes ouverts et résolus, avec les mesures prises
Retrait prochain Fonctionnalités en cours de désactivation, avec dates, exportation et remplacement
Statut Chaque composant de Nexus actuellement et sur 30 jours, en termes accessibles à tous
Lot d'assistance Ce qui est envoyé à Adverant, et comment

Deux de ces pages méritent une précision. La page Composants compilés vérifie chaque nuit chaque module sous licence par rapport à la signature d'Adverant. Une copie modifiée d'un module est refusée et n'est jamais chargée, tandis que la copie signée continue de s'exécuter, et la page comptabilise les refus par mois afin qu'une copie altérée ne puisse pas passer inaperçue. La page Statut est rédigée de manière à pouvoir être lue par n'importe quel membre de l'organisation. Elle présente chaque composant de Nexus actuellement et sur les 30 derniers jours sous forme de bande quotidienne, avec les maintenances planifiées et les incidents récents, et un opérateur peut ajouter un incident ou une fenêtre de maintenance depuis cette même page.

Une installation Community comporte une seule page, Cette installation (Community), indiquant sa version, son état de santé et ses mises à jour. Les pages Enterprise y apparaissent sous forme d'aperçus qui indiquent qui peut les activer.