Asami Receipes

Ce dépôt contient le catalogue global des receipes Asami.

Une receipe décrit une capacité d’administration qu’Asami peut installer sur une machine enregistrée : par exemple lire les informations SMART des disques, administrer un service Docker ou gérer un ensemble borné de machines virtuelles.

L’objectif est de donner aux agents les capacités dont ils ont réellement besoin sans leur donner un accès root généraliste.

Qu’est-ce qu’une receipe ?

Une receipe est une petite unité d’administration versionnée, lisible et auditable.

Elle peut contenir :

• une description de la capacité et de ses prérequis dans recipe.yml ;
• les règles sudo strictement nécessaires ;
• des commandes ou wrappers limitant volontairement ce qu’il est possible de faire ;
• des fichiers à installer ;
• lorsque nécessaire, des opérations d’installation, de retrait ou de qualification ;
• une documentation propre à la receipe.

Par exemple, une receipe de diagnostic peut autoriser la lecture des informations SMART d’un disque sans autoriser le lancement d’un test destructif ou une modification de sa configuration.

Une receipe n’est donc ni un paquet système, ni un rôle Ansible, ni une manière détournée de fournir un shell root.

Elle représente une capacité précise et bornée.

Un catalogue commun à toutes les instances Asami

Ce dépôt GitLab est la source canonique du contenu des receipes globales utilisées par les instances Asami.

La branche protégée main fait autorité.

GitLab
└── lodlp/asami-receipes
    └── main
        └── HEAD
            = révision canonique courante du catalogue

L’entrée d’une modification dans main est un acte d’admission humain.

Une merge request peut être préparée par un agent ou un contributeur, mais une nouvelle définition de receipe ne devient canonique qu’après validation puis merge dans main.

Il n’existe pas de second dépôt d’autorité, de canal stable, de registre de promotion ou de copie maîtresse propre à chaque instance Asami.

Comment Asami utilise ce dépôt

Une instance Asami ne lance pas directement des scripts depuis GitLab.

Lorsqu’elle met son catalogue à jour, elle :

1. récupère le HEAD courant de main ;
2. prépare cette révision localement sans modifier les machines administrées ;
3. valide l’ensemble du catalogue et de ses références ;
4. ne rend la nouvelle révision disponible localement que si cette validation réussit.

Si une nouvelle révision est invalide, le catalogue local déjà utilisable reste intact.

La commande conceptuelle receipes update signifie donc :

mettre à jour le catalogue local
≠
modifier les machines

Cette séparation permet à l’opérateur de récupérer et examiner une nouvelle révision avant de décider de la déployer.

Catalogue disponible et révision déployable

Asami distingue deux révisions globales :

• catalog_revision : la révision du catalogue actuellement disponible sur l’instance ;
• convergence_revision : la révision dont le déploiement sur le parc a été autorisé.

Elles peuvent temporairement être différentes.

Par exemple :

catalog_revision     = def456
convergence_revision = abc123

Cela signifie simplement :

une nouvelle version du catalogue est disponible, mais le parc doit encore rester sur la version précédemment autorisée.

Une mise à jour du catalogue n’accorde donc jamais silencieusement de nouvelles capacités aux agents.

L’autorisation de déploiement constitue une décision distincte.

Installation et mise à niveau

Les receipes installées sont choisies machine par machine.

Le fait qu’une receipe existe dans ce dépôt ne signifie pas qu’elle doit être installée partout.

catalogue global
├── diagnostics
├── docker-diagnosis
├── nginx
├── libvirt
└── workbenches

Machine_A
├── diagnostics
└── docker-diagnosis

Machine_B
├── diagnostics
├── libvirt
└── workbenches

Une mise à niveau du catalogue ne provoque jamais l’installation spontanée d’une nouvelle receipe.

Lorsqu’un déploiement est autorisé, Asami fait converger les receipes déjà installées vers la révision autorisée lorsque leur état et leurs paramètres le permettent.

Les situations nécessitant une décision humaine — conflit, modification locale, paramètre obligatoire manquant, adoption d’un fichier préexistant, etc. — restent bloquées jusqu’à cette décision.

Une frontière de confiance

Ce dépôt fait partie de la frontière de confiance d’Asami.

Une modification admise dans main peut à terme produire des effets privilégiés sur les machines où la receipe concernée est installée.

Pour cette raison :

• main est protégée ;
• les changements passent par merge request ;
• le catalogue est validé automatiquement avant admission ;
• une instance Asami valide de nouveau intégralement la révision téléchargée avant de l’utiliser ;
• les capacités exposées doivent rester aussi petites et explicites que possible.

Le même validateur est utilisé pour contrôler le catalogue avant son admission et lors de son chargement par Asami.

Structure d’une receipe

Une receipe possède une structure volontairement simple :

<receipe-id>/
├── recipe.yml
├── sudoers
├── README.md        # recommandé
├── install          # optionnel
├── remove           # optionnel
├── qualify          # optionnel
└── files/           # optionnel

recipe.yml décrit notamment l’identité de la receipe, ses dépendances, ses conflits, ses prérequis et ses éventuels paramètres.

Les données propres à une machine — nom d’un bridge, device local, liste de VMs autorisées, etc. — ne doivent pas être inscrites dans le catalogue lorsqu’elles peuvent rester des paramètres locaux.

catalog.json

Le dépôt contient également un catalog.json généré automatiquement.

Il sert d’index compact pour la recherche et l’affichage du catalogue.

Il n’est pas une seconde source d’autorité : il est généré depuis les définitions et les aides des commandes contenues dans les receipes, puis vérifié automatiquement.

Les opérations d’installation ou de mise à niveau utilisent toujours les fichiers autoritatifs de la révision Git concernée.

Valider une modification

Après un clone de travail, active une fois le hook versionné du dépôt :

git config core.hooksPath .githooks

À chaque commit, ce hook régénère catalog.json depuis les receipes puis vérifie que l’index obtenu correspond exactement au contenu candidat. Il utilise tools/catalog_validator.py, le même validateur que la CI et le contrôleur Asami.

Pour lancer manuellement le contrôle structurel :

python3 tools/catalog_validator.py --root . --revision WORKTREE --check-index --platform none --json

La CI ajoute la qualification Debian des host_requires.executables avec apt-file et refuse notamment un executable sans fournisseur ou avec plusieurs fournisseurs possibles. Un executable qui doit déjà appartenir au sous-système administré se déclare comme chemin requis dans host_requires.paths au lieu de demander à Asami de choisir arbitrairement un paquet.

Principe général

Une receipe doit rester :

• petite ;
• compréhensible ;
• auditable ;
• versionnée ;
• testable ;
• aussi portable que raisonnablement possible ;
• explicite sur ses prérequis et ses effets ;
• limitée à la capacité qu’elle prétend fournir.

Si une receipe commence à nécessiter un moteur de tâches généraliste, des règles complexes de précédence, un inventaire parallèle ou une logique de gestion de configuration complète, il faut réexaminer son périmètre plutôt que transformer ce dépôt en un Ansible bis.

Le principe recherché reste simple :

un besoin d’administration précis
→ une capacité bornée
→ une receipe lisible
→ une admission humaine dans main
→ une utilisation contrôlée par Asami