Référence des opérations
Chaque action de la console (installation, démarrage, mise à niveau, sauvegarde, retrait d'un hôte et les autres) est une opération composée d'étapes ordonnées ; une étape exécute ses tâches en parallèle, une par hôte, et l'étape suivante démarre quand toutes les tâches de l'étape sont terminées (CONTRACT.md section 11). Cette page liste les types d'opérations, les noms d'étapes et les types de tâches. Elle est générée par navin-manager/docs/tools/generate_reference.py à partir de navin_manager/engine/core.py, navin_manager/services/planner.py, navin_manager/services/tasks.py, des fichiers de traduction et des traitements de l'agent : ne la modifiez pas à la main.
Types d'opérations
Le type s'affiche dans la page Opérations et est enregistré dans nm.operations.type. La colonne des étapes liste les étapes que le planificateur peut ajouter, dans leur ordre ; une étape sans tâche n'est pas créée.
| Type d'opération | Description | Étapes |
|---|---|---|
service.install | Installe un ou plusieurs services (assistant d'installation), dépendances d'abord ; utilisée aussi par Réinstaller. | préparation des liaisons ; dépendances ; vérifications préalables ; prérequis des machines (podman, Python, tar) ; utilisateurs et répertoires ; artefacts et images ; fichiers de configuration et certificats ; unités systemd ; démarrage de <components> ; contrôles de santé ; vérification du service |
blueprint.apply | Installe les services d'un plan de déploiement (une topologie complète décrite dans un document) ; mêmes étapes que service.install. | préparation des liaisons ; dépendances ; vérifications préalables ; prérequis des machines (podman, Python, tar) ; utilisateurs et répertoires ; artefacts et images ; fichiers de configuration et certificats ; unités systemd ; démarrage de <components> ; contrôles de santé ; vérification du service |
service.action | Démarrage, arrêt, redémarrage ou redémarrage progressif de composants ; aussi la bascule d'un service et la correction d'un écart. | démarrage de <components> ; arrêt de <components> ; redémarrage de <components> ; redémarrage du lot <batch> sur <batches> ; contrôles de santé du lot <batch> sur <batches> ; contrôles de santé |
service.config_apply | Produit et écrit chaque fichier de configuration, puis redémarre les instances périmées (progressivement, toutes ou aucune) et lance les contrôles de santé. | fichiers de configuration et certificats ; configuration des pairs ; redémarrage de <components> ; redémarrage du lot <batch> sur <batches> ; contrôles de santé du lot <batch> sur <batches> ; contrôles de santé |
service.command | Exécute une commande personnalisée du catalogue (ses pas : command.run, health.check, service.control, file.write, logs.tail). | commande <command> |
service.components | Ajoute un composant sur des hôtes, ou retire une instance. | vérifications préalables ; prérequis des machines (podman, Python, tar) ; utilisateurs et répertoires ; artefacts et images ; fichiers de configuration et certificats ; unités systemd ; démarrage de <components> ; contrôles de santé ; arrêt de <components> ; suppression des unités ; suppression des enregistrements |
service.uninstall | Arrête le service, retire ses unités, purge éventuellement ses données, puis supprime ses enregistrements. | arrêt de <components> ; suppression des unités ; purge des données ; suppression des enregistrements |
service.logs | Lit les dernières lignes du journal d'une instance (logs.tail). | lecture des journaux |
service.mode | Change le mode d'exploitation d'un service (maintenance et les autres modes de navin-manager/server/src/navin_manager/services/modes.py). | voir la description |
service.upgrade | Met un service à niveau vers une nouvelle version : hôte canari d'abord, puis hôte par hôte, migrations, nouvelle version enregistrée. | canari <host>, nouvelle version ; canari <host>, arrêt ; canari <host>, fichiers et unités ; canari <host>, démarrage ; canari <host>, contrôles de santé ; canari <host>, test fonctionnel ; canari <host> mis à niveau ; <host>, nouvelle version ; <host>, arrêt ; <host>, fichiers et unités ; <host>, démarrage ; <host>, contrôles de santé ; <host> mis à niveau ; migration <migration> ; nouvelle version enregistrée |
service.rollback | Ramène un service mis à niveau à sa version précédente. | arrêt de chaque instance ; <host>, version précédente ; <host>, fichiers et unités précédents ; <host>, démarrage ; <host>, contrôles de santé ; <host> revenu à la version précédente ; version précédente enregistrée |
service.restore | Ramène un service mis à niveau à sa version précédente et restaure la sauvegarde prise avant la mise à niveau. | voir la description |
backup.create | Sauvegarde les données de services : répertoire, commande de sauvegarde, empreintes des fichiers, enregistrement. | répertoire de sauvegarde ; sauvegarde ; empreintes des fichiers de sauvegarde ; sauvegarde enregistrée |
backup.restore | Restaure une sauvegarde : contrôle d'intégrité, arrêt, restauration, démarrage, vérification des données. | empreintes des fichiers de sauvegarde ; intégrité de la sauvegarde ; arrêt avant la restauration ; restauration ; démarrage après la restauration ; vérification des données restaurées ; restauration enregistrée |
drift.scan | Compare les empreintes des fichiers gérés avec celles attendues (détection des écarts). | Empreintes des fichiers gérés |
network.firewall_members | Envoie les membres du cluster et les ports restreints au pare-feu de chaque hôte (tâche network.firewall_members, quand un hôte arrive, part ou change de cluster). | Pare-feu des nœuds : ports entre nœuds ouverts au seul cluster |
support.bundle | Collecte les fins de journaux des instances et construit une archive de support expurgée. | Fins de journaux des instances ; Archive nettoyée |
acceptance.run | Recette d'installation : contrôle préalable, vivacité, disponibilité, tests fonctionnels, rapport signé. | Recette : vérifications préalables ; Recette : vivacité des instances ; Recette : disponibilité des services ; Recette : tests fonctionnels ; Recette : rapport signé |
host.preflight | Collecte de nouveau les faits d'un hôte (facts.collect) et évalue le contrôle préalable. | voir la description |
host.facts | Rafraîchit les faits d'un hôte (facts.collect). | voir la description |
host.parameters | Applique les paramètres système d'un hôte (paramètres du noyau, limites). | voir la description |
host.decommission | Retire un hôte sans composant : l'agent s'arrête et oublie son identité, puis le serveur enregistre l'hôte comme retiré. | voir la description |
host.ssh_bootstrap | Installe et enregistre l'agent sur des hôtes par SSH (empreinte de chaque clé d'hôte vérifiée, clé gardée en mémoire seulement). | voir la description |
host.node_bootstrap | Prépare un nœud par SSH (sécurité des nœuds : compte de service, sudoers, agent) avant son enregistrement. | voir la description |
pki.rotate | Émet de nouveaux certificats pour les instances d'un service et les redémarre. | voir la description |
mcp.hosting.apply | Applique l'hébergement des serveurs MCP sur le service mcp-host. | voir la description |
Noms des étapes
Chaque nom d'étape des fichiers de traduction, tel que la console l'affiche. <service>, <host> et les autres valeurs entre chevrons sont remplies lors de la planification.
| Clé | Nom |
|---|---|
hosts.stage.agent | Arrêt de l'agent |
hosts.stage.cert_install | Installation des certificats |
hosts.stage.restart | Redémarrage des composants |
hosts.stage.revoke | Révocation des certificats |
hosts.stage.ssh_bootstrap_summary | Verdict de la connexion |
lifecycle.stage.acceptance_liveness | Recette : vivacité des instances |
lifecycle.stage.acceptance_preflight | Recette : vérifications préalables |
lifecycle.stage.acceptance_readiness | Recette : disponibilité des services |
lifecycle.stage.acceptance_report | Recette : rapport signé |
lifecycle.stage.acceptance_smoke | Recette : tests fonctionnels |
lifecycle.stage.bundle_build | Archive nettoyée |
lifecycle.stage.bundle_logs | Fins de journaux des instances |
lifecycle.stage.drift_scan | Empreintes des fichiers gérés |
network.stage.firewall_members | Pare-feu des nœuds : ports entre nœuds ouverts au seul cluster |
services.stage.backup_digest | <service> : empreintes des fichiers de sauvegarde |
services.stage.backup_done | <service> : sauvegarde enregistrée |
services.stage.backup_prepare | <service> : répertoire de sauvegarde |
services.stage.backup_run | <service> : sauvegarde |
services.stage.command | <service> : commande <command> |
services.stage.configure | <service> : fichiers de configuration et certificats |
services.stage.dependencies | <service> : dépendances |
services.stage.fetch | <service> : artefacts et images |
services.stage.forget | <service> : suppression des enregistrements |
services.stage.health | <service> : contrôles de santé |
services.stage.logs | <service> : lecture des journaux |
services.stage.nothing | <service> : enregistrement |
services.stage.peers | <service> : configuration des pairs |
services.stage.preflight | <service> : vérifications préalables |
services.stage.prepare | <service> : utilisateurs et répertoires |
services.stage.prerequisites | <service> : prérequis des machines (podman, Python, tar) |
services.stage.provision | <service> : préparation des liaisons |
services.stage.purge | <service> : purge des données |
services.stage.remove_units | <service> : suppression des unités |
services.stage.restart | <service> : redémarrage de <components> |
services.stage.restore_check | <service> : intégrité de la sauvegarde |
services.stage.restore_digest | <service> : empreintes des fichiers de sauvegarde |
services.stage.restore_done | <service> : restauration enregistrée |
services.stage.restore_run | <service> : restauration |
services.stage.restore_start | <service> : démarrage après la restauration |
services.stage.restore_stop | <service> : arrêt avant la restauration |
services.stage.restore_verify | <service> : vérification des données restaurées |
services.stage.rollback_configure | <service> : <host>, fichiers et unités précédents |
services.stage.rollback_done | <service> : version précédente enregistrée |
services.stage.rollback_fetch | <service> : <host>, version précédente |
services.stage.rollback_health | <service> : <host>, contrôles de santé |
services.stage.rollback_host_done | <service> : <host> revenu à la version précédente |
services.stage.rollback_start | <service> : <host>, démarrage |
services.stage.rollback_stop | <service> : arrêt de chaque instance |
services.stage.rolling_batch | <service> : redémarrage du lot <batch> sur <batches> |
services.stage.rolling_health | <service> : contrôles de santé du lot <batch> sur <batches> |
services.stage.service_check | <service> : vérification du service |
services.stage.smoke | <service> : test fonctionnel |
services.stage.start | <service> : démarrage de <components> |
services.stage.stop | <service> : arrêt de <components> |
services.stage.units | <service> : unités systemd |
services.stage.upgrade_canary_configure | <service> : canari <host>, fichiers et unités |
services.stage.upgrade_canary_done | <service> : canari <host> mis à niveau |
services.stage.upgrade_canary_fetch | <service> : canari <host>, nouvelle version |
services.stage.upgrade_canary_health | <service> : canari <host>, contrôles de santé |
services.stage.upgrade_canary_smoke | <service> : canari <host>, test fonctionnel |
services.stage.upgrade_canary_start | <service> : canari <host>, démarrage |
services.stage.upgrade_canary_stop | <service> : canari <host>, arrêt |
services.stage.upgrade_done | <service> : nouvelle version enregistrée |
services.stage.upgrade_host_configure | <service> : <host>, fichiers et unités |
services.stage.upgrade_host_done | <service> : <host> mis à niveau |
services.stage.upgrade_host_fetch | <service> : <host>, nouvelle version |
services.stage.upgrade_host_health | <service> : <host>, contrôles de santé |
services.stage.upgrade_host_start | <service> : <host>, démarrage |
services.stage.upgrade_host_stop | <service> : <host>, arrêt |
services.stage.upgrade_migration | <service> : migration <migration> |
Types de tâches exécutés par l'agent
Ces tâches s'exécutent sur un hôte, une à la fois, par l'agent Navin (Python nm_agent/handlers.py et Go agent-go/internal/agent/handlers.go). Leur contenu est scellé en base ; la console n'en affiche que le résumé.
| Type de tâche | Description |
|---|---|
agent.config | Met à jour agent.json depuis le Manager. |
agent.decommission | Arrête l'agent et oublie l'identité de l'hôte. |
archive.extract | Extrait une archive ; noms absolus, .., périphériques, FIFO et liens sortants sont refusés (archive_unsafe). |
artifact.fetch | Télécharge un artefact depuis le miroir et vérifie son sha256 avant de le déposer (checksum_mismatch sinon). |
cert.install | Écrit le certificat, la clé et l'autorité d'une instance. |
command.run | Lance un programme absolu autorisé depuis sa liste d'arguments, jamais par un shell. |
dir.ensure | Crée un répertoire avec son propriétaire, son groupe et son mode. |
facts.collect | Collecte les faits de l'hôte. |
file.remove | Supprime un fichier géré. |
file.write | Écrit un fichier avec son propriétaire, son groupe et son mode ; un contenu sensible est masqué dans les journaux. |
files.digest | Calcule le sha256 de fichiers gérés (écarts et sauvegardes). |
firewall.open | Ouvre les ports clients d'un composant à toutes les sources et les ports que seul le cluster utilise aux hôtes du cluster et au Manager (ipset et règles riches firewalld, ou règles ufw par membre). |
health.check | Exécute les contrôles de santé (http, tcp, command) avec leurs nouvelles tentatives. |
image.load | Charge une image de conteneur depuis le miroir et vérifie son empreinte ; avec store, dans le magasin d'images en lecture seule <store>/storage listé par un utilisateur de service sans root. |
image.pull | Récupère une image de conteneur depuis le registre et vérifie son empreinte ; avec store, dans le magasin d'images en lecture seule <store>/storage listé par un utilisateur de service sans root. |
limits.apply | Écrit un fichier de limites dans /etc/security/limits.d. |
link.ensure | Fait pointer un lien symbolique (current, venv) vers un répertoire de version ; avec displace_dir, un vrai répertoire présent est conservé sous <lien>.nm-legacy. |
logs.tail | Lit les dernières lignes d'un journal systemd ou d'un fichier de journal. |
packages.install | Installe des paquets système avec dnf, apt ou pacman, à la version figée par le catalogue, signatures des dépôts toujours vérifiées. |
preflight.run | Exécute les contrôles préalables d'un service sur l'hôte. |
python.venv | Crée l'environnement virtuel d'une version depuis les paquets wheel du miroir, avec pip --require-hashes --no-index. |
quadlet.unit | Écrit les fichiers Quadlet d'un composant Podman (navin-*.container, navin-*.network dans /etc/containers/systemd), désactive et retire l'unité systemd qu'ils remplacent, puis recharge systemd. |
service.control | Démarre, arrête, redémarre, active ou désactive un composant (pilote systemd ou process). |
smoke.run | Exécute le test fonctionnel d'un service. |
sysctl.apply | Écrit et applique un fichier dans /etc/sysctl.d. |
systemd.mask | Arrête, désactive et masque les unités systemd qu'un paquet de la distribution démarre seul (distribution_units du catalogue, par exemple asterisk.service), seulement si chaque fichier d'unité appartient à un paquet de la liste installée ; à la désinstallation, démasque seulement, sans jamais démarrer. |
systemd.unit | Écrit une unité systemd et recharge systemd. |
user.ensure | Crée le compte système d'un service ; avec subordinate_ids, lui donne des plages d'uid et de gid subordonnés de 65536 identifiants (usermod) pour Podman sans root. |
Types de tâches exécutés par le serveur
Ces tâches n'ont pas d'hôte : le moteur les exécute dans le Manager (décorateur @server_task).
| Type de tâche | Description |
|---|---|
server.host_decommissioned | Enregistre l'hôte comme retiré une fois son agent arrêté. |
server.lifecycle.acceptance_preflight | Étape de contrôle préalable de la recette d'installation. |
server.lifecycle.acceptance_report | Construit et signe le rapport de recette. |
server.lifecycle.backup_check | Vérifie les empreintes d'une sauvegarde avant une restauration. |
server.lifecycle.backup_done | Enregistre une sauvegarde terminée. |
server.lifecycle.instances_version | Enregistre la version désormais exécutée par les instances mises à niveau. |
server.lifecycle.restore_done | Enregistre une restauration terminée. |
server.lifecycle.rollback_done | Enregistre la version précédente après un retour arrière. |
server.lifecycle.support_bundle | Construit l'archive de support expurgée. |
server.lifecycle.upgrade_done | Enregistre la nouvelle version après une mise à niveau. |
server.node_bootstrap | Prépare un nœud par SSH (exécutée en arrière-plan). |
server.services.dependencies | Vérifie les dépendances des services de l'opération. |
server.services.forget | Supprime les enregistrements d'un service désinstallé. |
server.services.preflight | Évalue les contrôles préalables des instances prévues. |
server.services.register | Enregistre une opération qui n'a besoin d'aucune tâche sur un hôte. |
server.services.remove_instance | Supprime l'enregistrement d'une instance. |
server.ssh_bootstrap | Installe et enregistre l'agent par SSH (exécutée en arrière-plan). |
server.ssh_bootstrap_summary | Verdict d'une installation SSH sur plusieurs machines : met l'opération en échec avec ssh_bootstrap_partial quand une machine n'a pas été connectée, liste sinon les machines connectées. |
Statuts des tâches
Statuts d'une tâche (nm.tasks.status). Une opération est pending, running, succeeded, failed ou aborted ; une étape est pending, running, succeeded, failed, aborted ou skipped.
| Statut | Description |
|---|---|
waiting | En attente des étapes précédentes. |
queued | Prête, en attente de son agent. |
running | Réclamée et en cours. |
succeeded | Terminée sans erreur. |
failed | Terminée en erreur. |
timed_out | Non terminée dans son délai. |
aborted | Arrêtée par l'abandon de l'opération. |
skipped | Non exécutée (opération arrêtée avant elle). |