Déploiement et mises à jour

Le parc se déploie avec colmena 🡕 : une commande construit et applique la configuration sur un ou plusieurs hôtes, à distance, depuis le poste admin.

Appliquer une configuration

just apply <cible> [action]    # alias : a

• cible = nom d’hôte, motif ('*'), liste (a,b) ou tag colmena (@server).
• action = switch (défaut), boot, test ou build.

Commande	Pour quoi
just apply <cible>	Construire + activer sur la (les) cible(s)
just apply-local	Appliquer sur la machine courante (alias al)
just apply-verbose <cible>	Idem apply en mode trace (alias av)

Construire sur la cible

apply construit sur l’hôte cible (--build-on-target) : le poste admin n’a pas besoin de la puissance ni de l’architecture des machines déployées.

Déployer en sécurité

Monter en confiance par l’action : chaque étape est moins risquée que la suivante.

just apply <hôte> build      # télécharge + compile : 100 % sûr, rien n'est activé
just apply <hôte> test       # active sans switcher : ni génération, ni boot
just apply <hôte>            # switch : active et crée une nouvelle génération

Progresser du cœur vers la périphérie : déployez les nœuds dans cet ordre, pour ne jamais vous couper l’accès à un nœud par celui qui le précède.

Pourquoi cet ordre

La connectivité d’un hôte distant dépend de sa passerelle, qui dépend du VPN coordonné par le HCS. Déployer un maillon avant son support peut rendre les suivants injoignables.

Mettre à jour

Le système est figé par les flakes. Mettre à jour = rafraîchir les entrées, puis redéployer.

just update-flake     # met à jour dnf/ + racine, commit les locks
just apply '*'        # déploie la mise à jour

Toujours tester avant

Avant un déploiement large, validez localement : just check, puis just apply <hôte-pilote> sur un hôte témoin.

Mettre à jour le parc avec fleet-update

fleet-update enchaîne toute la mise à jour en une commande : flakes, construction de tous les hôtes, publication des fermetures sur le parc, test par vagues (les hôtes dont dépend le réseau d’abord), puis activation définitive des hôtes validés.

L’IA au travail

L’IA analyse, agit sur les services, corrige le code et propose des améliorations : voir Analyse par l’IA, Réparer un service, Réparer par le code et Suggestions d’amélioration.

Lancer

just fleet-update [options]

La recette choisit l’outil à lancer, dans cet ordre :

Situation	Outil lancé
Co-développement (src/dnf-fleet-update/ présent)	Les sources, avec bun
Module darkone.admin.fleet-update actif	La commande fleet-update installée
Autre cas	nix run .#fleet-update, selon le flake.lock du projet

Prérequis

• Arbres git propres : projet, et dnf/ en co-développement.
• var/deployments/ ignoré par git : règle /var/* du boilerplate.

Le déroulé d’un lancement

1. Mise à jour : nix flake update du projet puis de dnf/ (co-développement), just clean, un commit par dépôt.
2. Sélection : hôtes, profils et zones lus dans var/generated/, filtrés par --on ; zone courante déduite de l’IP locale ; un builder élu par hôte.
3. Construction : tous les hôtes sélectionnés, joignables ou non, chacun sur son builder. Présence sondée par la connexion SSH de déploiement, qui joint aussi un hôte en déplacement.
4. Publication : la fermeture de chaque hôte joignable est amenée dans son store, hors vagues, avant toute activation.
5. Test : switch-to-configuration test, une vague par profil ; la vague suivante démarre quand tous ses hôtes sont OK ou écartés.
6. Switch : tous les hôtes validés en test, d’un seul coup, hors ordre des vagues.

Pourquoi publier avant d’activer

Servir et activer sont deux besoins distincts. Une fois chaque hôte servi, une vague ne dépend plus que de ssh : une passerelle qui redémarre son réseau ne prive plus personne de son substituteur.

L’hôte tire d’abord (nix build --max-jobs 0, qui substitue sans jamais compiler sur place), et n’est poussé qu’en repli. Un tirage qui échoue est le cas ordinaire : un chemin tout frais n’est encore dans aucun cache.

Trois options raccourcissent ce déroulé :

Option	Effet
--build-only	S’arrête après la construction ; en interactif, propose de continuer
--skip-test	Pas de test : le switch se fait vague par vague, directement après la construction
--skip-switch	Pas de switch : le lancement s’arrête sur ce que le test a laissé en place

Précharger le parc sans rien activer

--skip-test --skip-switch construit et publie, puis s’arrête : chaque hôte détient sa fermeture (état ready) sans avoir rien activé. Un lancement suivant, ou un --resume, active alors sans plus rien copier. Pratique pour séparer une grosse descente de paquets d’une fenêtre d’intervention courte.

--build-only est l’autre extrême : rien ne sort de la machine de déploiement, la publication elle-même est écartée.

Pourquoi le switch n’est pas par vagues

Les vagues protègent une configuration non prouvée. Une fois le test réussi sur chaque hôte, il n’y a plus rien à protéger : le switch part en une fois, au plus --max-parallel hôtes activés simultanément. Avec --skip-test, rien n’a été prouvé : le switch reprend l’ordre des vagues.

Reprendre un lancement interrompu

--resume repart du dernier dossier de var/deployments/ : mise à jour sautée, vagues et options du lancement d’origine, et les hôtes qui restaient à faire (restants, hors ligne, en échec, ou seulement testés). Les constructions sont réutilisées si les révisions du projet et de dnf/ n’ont pas bougé et que les chemins sont encore dans le store ; sinon elles sont refaites. Rien à reprendre : code de sortie 2, aucun lancement.

Construction distribuée

La machine de déploiement ne doit pas être le goulot du parc. Chaque hôte est donc construit par le builder élu pour lui. L’élection est recalculée à chaque lancement depuis var/generated/, jamais déclarée : changer la topologie de déploiement ne doit pas reconstruire le parc.

Ordre	Builder retenu	Condition
1	L’hôte lui-même	Fonctionnalité auto-build ou roaming
2	L’hôte harmonia de sa zone	La zone en a un
3	L’hôte harmonia global	Il en existe un dans le parc
4	La machine de déploiement	Défaut

La règle tient en une phrase : un builder doit pouvoir servir ce qu’il construit. D’où le choix des hôtes harmonia, dont le /nix/store est déjà le cache de leur zone, sans rien à amorcer. Une passerelle sans harmonia ne convient pas : ses chemins ne sont dans aucun substituteur.

Le résultat reste chez le builder. C’est la publication qui l’amène ensuite aux hôtes de la zone, en LAN, par leur substituteur habituel.

Sources nixpkgs téléchargées par le builder

Chaque système embarque la source de nixpkgs (environ 200 Mio), nouvelle à chaque mise à jour et absente de tout cache. Avant de lui envoyer les dérivations, l’outil demande donc au builder de télécharger lui-même, depuis GitHub, les sources verrouillées dans flake.lock dont ses constructions ont besoin : elles ne passent plus par le lien montant de la machine de déploiement. Un builder qui ne joint pas github.com les reçoit poussées, comme avant, sans échec.

etc/config.yaml

    features: ["auto-build"]

Quand déclarer auto-build

Un hôte qui se construit lui-même ne reçoit plus aucune fermeture. C’est décisif pour un hôte isolé derrière une liaison lente qui embarque un gros paquet absent du cache public, et c’est la réponse pour un hôte d’une autre architecture.

Le choix se fait par hôte, jamais par zone : la RAM et le disque sont des propriétés de la machine. Contrepartie à peser : la clôture des dérivations, plusieurs centaines de Mio, monte vers lui à chaque lancement qui bouge nixpkgs. Ce sont les compteurs de copie du rapport qui tranchent le cas, pas l’intuition.

Repli automatique

Builder injoignable, en échec, ou d’une architecture incompatible avec sa cible → la construction revient sur la machine de déploiement. Aucun hôte n’échoue à cause d’une délégation, et le rapport nomme le builder qui a réellement construit.

L’option --no-distributed-build ramène tout au centre, quelle que soit l’élection. C’est une échappatoire de mise au point : la règle vient du parc, l’exception de la ligne de commande.

Une zone sans harmonia coûte cher

Sans cache de zone, il n’y a ni builder local ni source commune : chaque hôte se fait pousser sa fermeture, un par un, depuis la machine de déploiement. Le rapport liste ces zones et le nombre d’octets poussés le montre. Déclarez un harmonia sur un hôte de la zone.

Ordre des vagues et hôtes critiques

Les valeurs par défaut du parc se déclarent dans config.yaml :

etc/config.yaml

network:
  fleetUpdate:
    deploymentOrder: "hcs:gateway:server:[others]:laptop"
    criticalProfiles: "hcs:gateway:server"

Clé	Rôle
deploymentOrder	Une vague de test par profil d’hôte, dans cet ordre
criticalProfiles	Profils dont les échecs vont aussi au salon des incidents

Profils séparés par :, [others] désigne les profils non listés. Bloc facultatif : sans lui, l’outil applique les valeurs ci-dessus. Les options --deployment-order et --critical-profiles priment sur config.yaml.

Délais et surveillance

Deux autres blocs facultatifs de config.yaml règlent les durées :

etc/config.yaml

network:
  fleetUpdate:
    pingInterval: 15
    timeouts:
      build: 10800
      ssh: 30

Clé	Rôle	Défaut
pingInterval	Secondes entre deux sondes de présence	15
timeouts.<clé>	Durée maximale d’une opération, en secondes	selon l’opération

Clés de timeouts, dans l’ordre du déroulé :

timeouts.<clé>	Défaut (s)
flakeUpdate	120
clean	60
commit	60
eval	1200
build	10800
publish	3600
copy	3600
activation	300
ssh	30
ping	5
matrix	30
killGrace	10

Une clé inconnue arrête la génération

just generate vérifie les noms de clés et refuse un délai nul ou négatif : une faute de frappe retomberait sinon sur la valeur par défaut, en silence.

Erreurs, diagnostic et réparation

Une erreur courante doit se lire sans connaître Nix. L’outil tient une table de signatures : un motif reconnu dans la sortie d’une commande donne un message en clair, et l’action à prendre.

Motif reconnu	Ce que ça signifie	Action
mismatch in field 'narHash'	nix-eval-jobs n’est pas lié au même Nix que le système	Arrêt
lacks a signature by a trusted key	Le compte de déploiement n’est pas trusted user sur cet hôte	Arrêt

Le message s’affiche au fil du lancement (hint:), une seule fois, et se retrouve dans la section Known errors du rapport. Il s’ajoute à la raison de l’hôte, il ne la remplace jamais : la trace entière reste dans logs/.

Action de la table	Ce que fait l’outil
Relance	Rejoue la commande, au plus trois fois, si elle est rejouable : évaluation, construction, copie de dérivation, tirage
Exclusion	Poursuit sans l’hôte ; s’il était déjà activé, le ramène d’abord à son origine
Arrêt	Arrête le lancement, sans poser de question

Aucune signature ne demande de relance aujourd’hui : les deux entrées connues sont des arrêts.

Une action de la table ne se discute pas

Elle s’applique aussi en interactif : une réparation déterministe passe avant la question. Un lancement de nuit et un lancement surveillé traitent donc la même erreur de la même façon. La ligne known error decides: stop le dit au fil du lancement, et la raison de l’hôte reste au rapport.

Activation, pose du profil, commit et redémarrage d’unités ne sont jamais rejoués tout seuls : seules les commandes qu’on peut réexécuter sans conséquence le sont.

Collecte déterministe. Un hôte qui échoue en restant joignable est interrogé avant toute décision : systemctl status, liste des unités en échec, puis le journal de chacune depuis le début de sa vague.

Ce qui est collecté	Où ça va
Sortie complète des commandes et journaux	logs/<hôte>.diag du dossier de lancement
Unités en échec, extrait de l’erreur	Section Diagnostics du rapport, message d’incident

Redémarrage des unités. Une activation qui se termine avec des unités en échec laisse l’hôte en état error. L’outil tente alors une réparation simple.

1. Attente de dix secondes : une unité lente à démarrer n’est pas une unité en échec.
2. systemctl restart de toutes les unités en échec, en une seule commande.
3. Relecture de la liste des unités en échec : c’est elle qui conclut, pas le code de sortie.

Tout repart → l’hôte reprend son cours, rejoint le switch avec les autres, et le rapport note un probable problème d’ordre d’activation (section Notes). Une unité résiste → l’hôte reste en error, son nom et celui de l’unité au rapport.

Ce que l’interface affiche pendant ce temps

L’hôte porte un libellé clignotant à droite de son nom, avec son indicateur d’activité : under repair en jaune pendant la réparation déterministe, AI analysis et AI repair en magenta quand l’IA prendra le relais.

Analyse par l’IA

L’IA explique un échec : elle lit l’état du lancement, les journaux et, au besoin, le code, puis rend une analyse en clair. Avec --ai-error-action repair elle peut ensuite agir sur les unités tombées, et rien d’autre (voir Réparer un service). Le lancement n’attend jamais après elle — une analyse qui échoue, dépasse son délai ou son budget laisse l’hôte exactement où il était.

Deux options la commandent, toutes deux à none par défaut : rien ne part vers une IA tant qu’on ne l’a pas demandé. Une troisième choisit l’outil.

Option	Défaut	Rôle
--ai-analysis none|passive|active	none	Profondeur d’analyse, et synthèse de fin de lancement au rapport
--ai-error-action none|analysis|repair	none	Ce que l’IA fait quand un hôte échoue
--ai-model <outil>[:<modèle>][@<effort>]	claude:opus@high	Outil et modèle, par exemple opencode:ollama/qwen3:32b
--ai-context <texte>	aucun	Consigne ou contexte ajouté à tous les prompts IA

just fleet-update --ai-analysis passive          # rapport enrichi, rien de plus
just fleet-update --ai-error-action analysis     # chaque échec est expliqué

Par exemple, --ai-context "Répondre en français et rester concis." guide le style des réponses. Pour ne pas le répéter à chaque lancement, posez-le une fois pour l’hôte avec l’option aiContext du module : elle l’écrit dans /etc/fleet-update/ai-context, que tout lancement lit, just fleet-update comme le timer. L’option --ai-context prime sur ce fichier. À la reprise, le contexte du lancement initial est repris ; un --ai-context explicite le remplace.

# usr/machines/<hôte>/configuration.nix
darkone.admin.fleet-update.aiContext = "Répondre en français et rester concis.";

Le modèle par défaut du parc se pose dans config.yaml, l’option prime :

etc/config.yaml

network:
  fleetUpdate:
    aiModel: "claude:opus@high"

Les outils IA ne sont pas une dépendance de l’outil. claude et opencode sont cherchés dans le PATH ; l’option aiPackages du module les y met pour le lancement quotidien. Absents ou refusés → un avertissement au fil du lancement, une note au rapport, et la suite se déroule sans IA.

Ce que l’IA a le droit de faire

L’IA n’a ni shell ni SSH libre. Elle n’agit que par les outils de fleet-update, et le niveau demandé fixe la liste qu’on lui présente : ce qu’elle n’y voit pas, elle ne peut pas le demander.

Niveau	Outils présentés
passive	État du lancement, diagnostic d’un hôte, journaux de construction et d’activation, avertissements du lancement regroupés
active, analysis	+ lecture, recherche et liste du code (projet et dnf/), unités et journaux des hôtes (unités utilisateur comprises), en lecture seule
repair	+ une action sur les unités tombées d’un hôte, et l’édition du code qui les décrit

Le niveau retenu est le plus élevé des deux options : --ai-analysis passive --ai-error-action analysis donne active. Les outils intégrés de claude et d’opencode sont coupés, et les instructions que ces outils ramasseraient dans le projet (CLAUDE.md, réglages utilisateur) sont neutralisées : l’IA ne voit que ce qu’on lui montre.

Garde-fou	Effet
Chemin de lecture	Confiné au projet et à dnf/, après résolution des liens ; usr/secrets/ et .trash/ refusés
Hôte, unité	Vérifiés contre la table du lancement avant toute commande
Extraits	200 lignes de journal, 400 lignes de source, tronqués par la fin : l’erreur est en bas
Délai, budget	300 secondes par analyse ; budget en dollars pour claude

Chaque appel d’outil laisse une trace — une ligne au fil du lancement (AI reads usr/modules/nginx.nix) et une ligne dans logs/ai.log du dossier de lancement. Un appel refusé par un garde-fou est tracé aussi, avec sa raison.

Quand elle intervient

1. Un hôte échoue, avec --ai-error-action ≠ none : après la collecte déterministe et le redémarrage des unités, avant la question qui décide de son sort. L’hôte porte AI analysis en magenta pendant ce temps, puis revient à son état.
2. Un hôte se rétablit après un redémarrage d’unités, avec --ai-analysis ≠ none : l’analyse explique l’ordre d’activation, sans toucher à l’état de l’hôte.
3. Fin de lancement, avec --ai-analysis ≠ none : une synthèse de l’ensemble, écrite avant le rapport qui la porte.
4. Fin de lancement, avec --ai-analysis active : une revue des avertissements, qui dépose des suggestions d’amélioration.
5. Touche a, à tout moment : une question libre. Elle reçoit une réponse même sous --ai-analysis none — sans aucun outil : none supprime les outils et l’analyse automatique, pas la conversation.

Réparer un service

--ai-error-action repair ouvre une seconde session sur l’hôte, juste après l’analyse et dans l’état AI repair. Le premier de ses outils agit sur les services : systemctl start, stop, restart ou reset-failed sur les unités que le lancement a vues tomber. C’est le geste à préférer : il est local et réversible. Quand il ne suffit pas, l’IA corrige le code (Réparer par le code).

just fleet-update --ai-error-action repair

1. Le redémarrage groupé déterministe a échoué : l’hôte reste en error.
2. L’IA analyse, dans l’état AI analysis, en lecture seule.
3. L’IA répare, dans l’état AI repair : elle agit, puis relit les unités en échec.
4. Plus rien en échec → l’hôte reprend son cours et rejoint le switch. Sinon → la question habituelle, revert / keep / stop / rollback.

Garde-fou	Effet
Unités	Seules celles que la collecte a vues en échec sur cet hôte ; toute autre est refusée
Hôte	Refusé s’il n’est pas en cours de réparation : une session de lecture n’agit jamais
Essais	Trois actions par hôte, refus non compris ; la quatrième est refusée
Arrêt en cours	Un lancement qui s’arrête ne répare rien : c’est une opération nouvelle
Confirmation	En interactif, une question à boutons avant chaque action : apply ou skip

En non interactif (timer de nuit, --no-ui), l’action passe sans demander. Elle est strictement moins risquée que ce que le lancement fait déjà sans témoin : la réparation déterministe redémarre toutes les unités en échec de l’hôte.

Chaque action est comptée, pas seulement tracée : elle se retrouve dans state.json et dans la section AI repair du rapport, refus compris, avec sa raison. Un hôte réparé porte aussi une note au rapport.

Réparer par le code

Quand aucun redémarrage ne peut aider, l’IA écrit la correction dans le projet, la valide, la commite, et l’hôte seul est reconstruit puis redéployé.

1. edit_code remplace un passage exact (présent une seule fois), ou réécrit un fichier en entier. L’arbre git doit être propre avant la première édition, et le diff part dans logs/ai.log.
2. validate lance le nettoyage du projet, puis réévalue et reconstruit cet hôte seul.
3. commit écrit fix(<scope>): <sujet>, le scope nommant ce que la correction touche (fix(nginx): …). En co-développement, dnf/ est commité d’abord, puis le projet et son lock réaligné.
4. L’hôte repasse en built avec son nouveau chemin ; sa vague le sert une fois de plus : copie, activation, conclusion.

Garde-fou	Effet
Chemins	Le projet, et dnf/ en co-développement ; jamais usr/secrets/, .trash/, .git/, var/generated/, etc/config.yaml ni un *.lock
Hors co-développement	dnf/ est un chemin du store : l’écrire est refusé, et n’aurait rien changé
Arbre	Sale avant la première édition → refus : un commit de réparation ne porte que la correction
Essais	Un essai est un changement. Valider et commiter n’en coûtent aucun, sinon corriger coûterait trois fois plus que redémarrer
Hooks	Jamais contournés : le commit passe par la porte du dépôt comme n’importe quel autre
Message	dnf/ est publié : un commit du framework qui nomme un hôte du parc est refusé

Le parc se retrouve à cheval sur deux révisions

Seul l’hôte réparé est reconstruit : tous les autres gardent le chemin que le lancement avait construit au départ, et basculent avec. Jusqu’au lancement suivant, le parc tourne donc sur deux révisions. Le rapport et le message d’alerte le disent en toutes lettres : Repaired in flight: <hôte>.

Conséquence sur la reprise : après un commit de réparation, --resume reconstruit tout. C’est la garantie elle-même — on ne redéploie pas des chemins construits avant la correction.

En non interactif aussi

Sous le timer de nuit, l’IA édite, commite et redéploie sans demander. Un commit non relu peut donc atterrir sur la branche. Ce qui rend la chose tenable : l’arbre propre exigé, les chemins confinés, le diff journalisé, les trois essais, et le retour arrière automatique qui reste armé. Si ce n’est pas ce que vous voulez, laissez --ai-error-action à none ou à analysis dans timer.extraArgs.

Ce que la réparation IA n’est pas

Ce n’est ni la réparation déterministe (redémarrage groupé, une fois, sans IA), ni la relance d’une commande décidée par la table des signatures, ni une décision — exclure ou arrêter passe avant, sans question. L’IA n’arrive qu’après ce qui est déterministe.

L’analyse s’ajoute, elle ne remplace rien

La raison brute d’un hôte, ses unités en échec et la trace entière de logs/ restent ce qu’elles étaient. L’analyse les complète, comme le message en clair d’une erreur connue.

Suggestions d’amélioration

Avec --ai-analysis active, le lancement se termine par une revue de ses avertissements : option renommée ou dépréciée, changement qui ferait taire un avertissement, problème à investiguer. L’IA propose, elle ne change ni le code ni le parc.

1. Les avertissements de tous les journaux du lancement sont regroupés par forme : le même sur dix hôtes compte une fois. Aucun avertissement → aucune revue, rien n’est payé.
2. L’IA lit les suggestions déjà déposées, puis cherche dans le code d’où vient chaque avertissement.
3. Chaque constat utile devient un fichier var/deployments/suggestions/<slug>.md : quoi, où (fichier:ligne), pourquoi, et l’amélioration proposée.
4. La section Suggestions du rapport liste ce que le lancement a déposé ou revu. Rien ne part dans Matrix : ce n’est pas une alerte.

Les fichiers survivent aux lancements. Un constat qui revient ne réécrit pas son fichier : seules les lignes Last seen et Runs de l’en-tête bougent.

var/deployments/suggestions/nginx-deprecated-option.md

# Replace a deprecated nginx option

- Status: open
- First seen: 20260101T020000Z-full
- Last seen: 20260108T020000Z-full
- Runs: 4

The option is deprecated upstream: `usr/modules/web.nix:12`, …

Pour	Faire
Faire taire une suggestion	Écrire Status: ignored dans son en-tête : elle reste suivie, hors du rapport
L’oublier	Supprimer le fichier : un constat qui revient repart de zéro
L’appliquer	Corriger le code, puis supprimer le fichier

La portée suit le mode : en co-développement, le projet et dnf/ ; sinon, le projet seul (un constat que seul le framework corrige n’est pas déposé).

Rapport et alertes Matrix

Chaque lancement écrit son dossier dans var/deployments/<date>-<mode>/ : report.md (le rapport), state.json (l’état que --resume reprend), events.jsonl et les journaux par hôte. Le chemin s’affiche en fin de lancement.

Le rapport détaille ce que le lancement a réellement fait :

Section	Ce qu’elle donne
Steps, Waves	Durée de chaque étape, composition et durée de chaque vague
Builders	Qui a construit quoi, replis compris
Copies	Par hôte : chemins tirés et par quel substituteur, chemins poussés, volume
Zones without a cache	Zones du lancement qu’aucun harmonia ne sert
Hosts not deployed	Hôtes restés de côté, et la raison
Diagnostics	Par hôte en échec : unités en échec, puis extrait de l’erreur
Notes	Ce que le lancement a constaté : ordre d’activation probable après un redémarrage d’unités
AI analysis	Analyse de l’IA : une entrée par hôte analysé, puis la synthèse du lancement
AI repair	Actions de l’IA : hôte, action, issue, et la raison d’un refus. Un commit de réparation apparaît aussi dans l’en-tête, Repaired in flight
Suggestions	Suggestions d’amélioration déposées ou revues par le lancement, hors celles ignorées
Known errors	Pièges reconnus par la table de signatures, en clair

Lire les compteurs de copie

Un hôte qui tire l’essentiel depuis harmonia <zone> prouve que le cache de sa zone joue son rôle. Un hôte qui se fait pousser beaucoup de volume est au contraire candidat à un harmonia dans sa zone, ou à auto-build. Aucune ligne de copie pour un hôte → il détenait déjà tout, rien n’a voyagé.

L’option --send-report envoie ce rapport aux salons du bot d’alertes, installé au préalable par just configure-alert-bot.

Situation	Salon	Contenu
Lancement terminé	warnings	Résumé : hôtes par état, durée, erreurs connues
Hôtes critiques non déployés	incidents	Message séparé : hôtes concernés, raisons et unités en échec
Arrêt sur erreur	incidents	Erreur qui a arrêté le lancement, puis résumé

Un hôte est critique quand son profil figure dans criticalProfiles. Après un arrêt, les hôtes laissés en test complètent le message d’incident : un redémarrage les ramènerait à leur génération précédente.

Seule la synthèse de fin de lancement rejoint le message, jamais les analyses par hôte, et elle y est bornée à six lignes : au-delà, le message renvoie à report.md. Un salon d’alertes n’est pas un rapport.

Le message reprend l’en-tête du rapport, le code de sortie dans le titre :

**Fleet Update Report** (1)

Error: srv-ag: activation failed

- Started at 2026-09-17 02:00:00 UTC, duration: 4m12s
- Options: partial run, selection gw-*, test skipped, 10 in parallel
- Hosts: 5 deployed (hcs, gw-ag, pc-ag, gw-cp, lt-cp), 1 failed (srv-ag)
- Run stopped on error

Envoi impossible

Le lancement reste valide et le rapport est écrit, mais la commande sort en 3. Sous le timer, l’unité passe en échec, donc l’alerte SystemdUnitFailed.

Ce que l’envoi exige

L’envoi passe par la recette just send-msg : salons et jeton restent du ressort du framework, l’outil n’écrit que le texte. Rien ne part si le bot n’est pas provisionné, ni sur un abandon (^C, arrêt du service).

Exécution quotidienne

Sur l’hôte de déploiement, le module installe l’outil et, avec timer.enable, lance chaque jour fleet-update --no-ui :

# usr/machines/<hôte>/configuration.nix
darkone.admin.fleet-update = {
  enable = true;
  user = "admin";
  aiContext = "Répondre en français et rester concis.";
  timer.enable = true;
};

Option	Défaut	Rôle
user	aucun	Propriétaire du projet : git, clé age, IA, Matrix
workDir	/etc/nixos	Projet consommateur sur le disque
aiContext	null	Contexte ajouté aux prompts IA de tout lancement sur l’hôte, écrit dans /etc/fleet-update/ai-context, même sans enable ; --ai-context le remplace
timer.onCalendar	*-*-* 04:00	Heure de lancement
timer.extraArgs	[ ]	Options ajoutées à --no-ui, --send-report par exemple
timer.timeout	6h	Durée maximale d’un lancement

Codes de sortie et alertes

Un lancement déjà en cours (code 4) n’est pas une erreur. Tout autre échec, ou un dépassement de timer.timeout, met l’unité en échec et déclenche l’alerte SystemdUnitFailed.

Compte et hôte de déploiement

Le timer exige darkone.admin.nix sur l’hôte, et un compte user disposant de sudo sans mot de passe.

Rapport quotidien

--send-report deviendra le défaut de timer.extraArgs quand la version empaquetée de l’outil saura l’envoyer. Ajoutez-la d’ici là, après avoir vérifié l’envoi à la main.

Cache binaire

Deux services se combinent pour éviter de recompiler ou de retélécharger les dérivations à chaque déploiement.

Service	Rôle
harmonia	Sert le /nix/store local, signé, directement aux hôtes (LAN, ou VPN s’il est global).
nix-cache	Proxy nginx par zone qui met en cache le cache public cache.nixos.org sur la passerelle.

Un hôte harmonia a un second rôle : il est le builder élu de sa zone, parce qu’il sait servir ce qu’il construit.

Un hôte interroge ces sources dans l’ordre de priorité suivant. La première récupération depuis Internet est ainsi mutualisée pour toute la zone.

Priorité	Source	Portée
20	harmonia de la zone	LAN, ce que la zone a compilé
35	proxy nix-cache de la zone	LAN, miroir mutualisé du cache public
40	cache.nixos.org en direct	filet de sécurité si la passerelle est HS
45	harmonia global	dernier recours, par le VPN

Comment l’ordre est garanti

Nix ne suit pas l’ordre de la liste substituters, il trie les caches selon la priorité que chacun annonce dans son nix-cache-info. Or ces valeurs annoncées sont à égalité : toutes les harmonia déclarent 30, et le proxy relayant cache.nixos.org tel quel déclare 40, comme l’accès direct au cache public. DNF fixe donc la priorité dans l’URL du substituter (?priority=35), ce qui écrase la valeur annoncée et rend l’ordre du tableau explicite.

Deux conséquences voulues. Le proxy de zone passe devant l’accès direct au cache public, sans quoi la mutualisation de zone ne se ferait jamais. Et une harmonia global passe derrière ce cache public : harmonia sert un /nix/store entier, sans pouvoir distinguer ce qu’elle a compilé du reste, donc un hôte bien garni capterait tout le trafic que le cache public doit servir. En dernier recours, elle n’est consultée que pour ce que cache.nixos.org n’a pas, c’est-à-dire ses propres constructions.

Un hôte ne se sert pas de sa propre harmonia

Ce service sert son propre /nix/store, il ne peut donc fournir que des chemins déjà présents localement. Sur cet hôte, tout ce qui manque vient forcément d’une autre source : c’est normal, sa harmonia ne profite qu’aux autres machines de la zone.

Hôte nomade (portable multi-zones)

Un portable qui change de zone ne doit pas garder des substituters figés sur sa zone déclarée : injoignables ailleurs, ils coûtent des timeouts à chaque requête. Déclarez-le nomade :

etc/config.yaml

    features: ["roaming"]

Ses substituters deviennent des noms neutres (harmonia.dnf.internal, nix-cache.dnf.internal) que le DNS de chaque zone résout vers ses propres caches → le cache suit la machine. Hors de toute zone, réponse NXDOMAIN immédiate → repli direct sur cache.nixos.org, sans délai. Les clés de signature étant communes à tout le réseau, rien d’autre à configurer.

Hors zone, aucun cache du parc ne le sert : fleet-update le construit donc sur lui-même, comme un hôte auto-build. Pour un déplacement ponctuel, l’option darkone.service.nix-cache.roaming seule suffit.

Activation

harmonia et nix-cache sont des services à activer sur un hôte du réseau (nix-cache sur la passerelle de zone). La clé de signature de harmonia est gérée par sops (just configure-admin-host).

Pourquoi un proxy à upstream unique

nix-cache ne relaie qu’un seul upstream (cache.nixos.org) : il met en cache narinfo et nar tels quels, signatures intactes. Pas de réécriture d’URL ni de base de données, donc pas l’erreur HTTP 500 « invalid nar hash » de l’ancien relais ncps.

Ferme de build

Récupérer un paquet et le construire sont deux besoins distincts. Le cache binaire ci-dessus couvre le premier. Pour le second, un hôte puissant du réseau peut prendre à sa charge les compilations longues d’un hôte d’administration.

Déclarez-le par la fonctionnalité build-farm :

etc/config.yaml

    features: ["build-farm"]

Chaque hôte d’administration l’ajoute alors à ses nix.buildMachines, joint en SSH par le compte de déploiement nix. Rien d’autre à configurer : la clé et l’autorisation sont déjà en place sur tout le parc.

Seules les compilations longues partent

La délégation est volontairement étroite : la ferme ne se voit proposer que les dérivations déclarant requiredSystemFeatures = [ "big-parallel" ], soit le noyau, les navigateurs, llvm, rustc… Tout le reste est construit sur place. C’est décisif quand la ferme est derrière une liaison lente, puisque seul le résultat demandé fait le trajet retour.

Ajustez avec darkone.admin.nix.remoteBuilders : maxJobs, speedFactor, et mandatoryFeatures (liste vide = tout part à la ferme).

build-farm ou auto-build ?

Deux mécanismes distincts, cumulables sur un même hôte.

Fonctionnalité	Qui s’en sert	Ce qu’elle déplace
build-farm	Nix, sur les hôtes d’administration	Les seules dérivations big-parallel, quel que soit l’outil lancé
auto-build	fleet-update, à la construction du parc	Toute la fermeture système de l’hôte qui la déclare

build-farm soulage un poste admin de ses compilations longues. auto-build supprime un transfert vers un hôte. Ils ne se remplacent pas.

Une ferme n’est pas un cache prioritaire

Ne promouvez pas une ferme distante en harmonia global prioritaire pour partager ses résultats : harmonia sert le /nix/store entier et capturerait le trafic que le cache public doit servir, à travers la liaison la plus lente du réseau. C’est le rôle du niveau 45 du tableau plus haut : dernier recours, jamais source principale.

Repli si la ferme est injoignable

L’hôte d’administration conserve big-parallel dans ses propres system-features. Quand la ferme ne répond pas, Nix reprend simplement la compilation en local au lieu d’échouer. Ne retirez pas cette fonctionnalité pour forcer la délégation.