From 01ecea901b1dc699e460f53c15b894c839739b33 Mon Sep 17 00:00:00 2001 From: Daniel Allaire Date: Mon, 10 Aug 2026 07:34:32 -0400 Subject: [PATCH] =?UTF-8?q?doc=20:=20l'aiguillage=20=E2=80=94=20quatre=20s?= =?UTF-8?q?ituations,=20quatre=20portes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md ouvre desormais sur « par ou entrer, selon ce que tu viens faire » : monter (QUICKSTART), heriter (wiki Reprendre l'ecosysteme), modifier (carte-set-ops), apprendre (wiki Home). On n'arrive pas avec un sujet, on arrive avec une situation. carte-set-ods.md et wiki/Home.md declarent leur lecteur — le mainteneur et l'apprenant — et renvoient aux deux autres portes. C'est la convention qui empeche la rechute : un document qui declare son lecteur se range tout seul. La regle du miroir est ecrite aux trois endroits ou elle se lit : le wiki est publie DEPUIS le depot, une page modifiee dans l'interface de la forge est detruite a la publication suivante. Corrige au passage les comptes perimes de la carte (26 docs + 7 audits + 21 unites -> 34 + 15 + 23, et un README pour chacun des 54 roles). Le lien vers la page accentuee est percent-encode : aucun precedent de lien accentue hors du wiki dans ce depot, et le rendu du depot n'est pas celui du wiki. Verifie : les cinq liens relatifs du README resolvent, chaque porte declare son lecteur, prouver.py 0 (33 OK), plan-recette inchange. Co-Authored-By: Claude Opus 5 --- CHANGELOG.md | 53 +++++++++++++++++++++++++ README.md | 16 +++++++- docs/audit/preuve-2026-08-10.md | 69 +++++++++++++++++++++++++++++++++ docs/carte-set-ops.md | 17 +++++--- wiki/Home.md | 9 +++-- 5 files changed, 153 insertions(+), 11 deletions(-) create mode 100644 docs/audit/preuve-2026-08-10.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 91354db..4fef280 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,58 @@ # CHANGELOG — Set-OPS +## 2026-08-10 — Refonte documentaire : on n'arrive pas avec un sujet, on arrive avec une situation + +La documentation était organisée **par sujet** — identité, courriel, DNS, PKI, sauvegardes. +C'est l'organisation juste pour de la *référence*. Mais personne n'arrive avec un sujet. Il y +a exactement quatre situations, trois avaient déjà une porte, et **deux de ces trois ne +s'annonçaient pas** : + +| Situation | Lecteur | Porte | +|---|---|---| +| « c'est quoi ? » | qui découvre | `README.md` | +| « je viens d'hériter » | l'exploitant | **`wiki/Reprendre-l-écosystème.md`** — n'existait pas | +| « je dois modifier » | le mainteneur | `docs/carte-set-ops.md` — le dit désormais | +| « j'apprends le métier » | l'apprenant | `wiki/Home.md` — le dit désormais | + +**Une seule page créée**, et elle ne contient presque rien en propre : un **ordre** et des +renvois, en cinq temps. Dans quel état tu hérites (les six devis avant tout geste) ; entrer +(la clé de voûte, l'amorçage, la racine qui mène à la mauvaise console, l'AC) ; de quoi c'est +fait (à *demander* au plan, pas à lire) ; quand ça casse ; ce qui va te mentir. + +**Aucun fichier déplacé, aucune réécriture du wiki.** Les liens, l'historique git et les +renvois croisés valent plus qu'un rangement. + +**La convention qui empêche la rechute : chaque document déclare son lecteur en première +ligne** — pas un sujet, un lecteur et sa situation. C'est ce qui manquait vraiment : +`autorisation.md` contient un runbook de reprise parce que le *sujet* est l'autorisation, et +personne ne va l'y chercher. Un document qui déclare son lecteur se range tout seul, et un +intrus s'y voit. + +**Le wiki devient la porte unique du lecteur, le dépôt reste la source.** `wiki-publier` fait +un `delete` puis recopie : une page modifiée dans l'interface de la forge est **détruite** à +la publication suivante. La règle est maintenant écrite dans `README.md`, `Home.md` et la page +de reprise — elle ne l'était nulle part. + +**Ce qui n'a finalement pas été écrit, et pourquoi.** La page « Ce qui va te mentir » était +prévue. Trois des cinq pièges qu'elle devait cataloguer ont trouvé un meilleur domicile +pendant qu'on travaillait — le `connect()` vers le vide (`frontiere-opnsense.md`, et +`frontiere-mesurer` porte désormais le contrôle qui tranche), le `make prouver` vert +(*Vérifier le déployé*), le *banner exchange*. Les deux orphelins s'adressent à qui **écrit du +code**, pas à qui reprend l'exploitation. Une page séparée aurait redit ce que trois autres +disent déjà. + +Sa substance survit : la section ⑤ de la page de reprise porte la **règle** qui les relie — +*vérifier l'instrument avant d'accuser le composant, une sonde porte toujours un contrôle* — +et renvoie chaque signal faux à son domicile. + +**Un trou trouvé en vérifiant mes propres renvois.** Le *banner exchange* n'était documenté +nulle part où on le cherche : un commentaire du `Makefile` et trois entrées de ce fichier. +Écrit en **runbook §3**, avec ses trois causes par fréquence et ce qui tranche dans l'ordre. + +Vérifié : chaque cible `make` et chaque lien contrôlés un à un (`make ca-installer` n'existe +pas — c'est `ca-racine` + `ca-empreinte`) ; les cinq liens du README résolvent ; `prouver.py` +0 ; plan de recette inchangé. + ## 2026-08-09 — La frontière est étanche : 56 lignes conformes, dans les deux sens L'exploitant a retiré la dernière règle héritée, celle qu'il avait lui-même étiquetée diff --git a/README.md b/README.md index 7f3fa63..c7db645 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,21 @@ Le dépôt est le **moteur** (générique, partageable). Chaque déploiement réel est une **instance** (le plan + l'inventaire d'un hébergeur, dans son propre dépôt). Tu crées la tienne à partir d'un **modèle prêt à déployer** (`exemples/modeles/`). -> 👉 **Tu débarques avec une grappe Proxmox et tu veux monter ton écosystème ? Commence par [`QUICKSTART.md`](QUICKSTART.md).** +## Par où entrer — selon ce que tu viens faire + +On n'arrive pas avec un *sujet*, on arrive avec une **situation**. Il y en a quatre : + +| Ta situation | Ta porte | +|---|---| +| « Je veux **monter** mon écosystème sur ma grappe Proxmox » | [`QUICKSTART.md`](QUICKSTART.md) | +| « Je viens d'**hériter** d'un écosystème déjà déployé, je dois l'exploiter » | [`wiki/Reprendre-l-écosystème.md`](wiki/Reprendre-l-%C3%A9cosyst%C3%A8me.md) | +| « Je dois **modifier** le moteur » | [`docs/carte-set-ops.md`](docs/carte-set-ops.md) | +| « J'**apprends** le métier » | [`wiki/Home.md`](wiki/Home.md) | + +Et si tu veux d'abord savoir *ce que c'est* : continue simplement ci-dessous. + +> Le wiki (`wiki/`) est **publié depuis ce dépôt** vers la forge. Une page modifiée dans +> l'interface de la forge est détruite à la publication suivante : on lit là-bas, on écrit ici. **Souveraineté jusqu'au bout : Set-OPS s'exploite entièrement à la main** — la doc, `make` et le GUI suffisent, **sans aucune IA**. L'outil libère de la dépendance aux géants ; il ne la remplace pas par une dépendance à une IA. diff --git a/docs/audit/preuve-2026-08-10.md b/docs/audit/preuve-2026-08-10.md new file mode 100644 index 0000000..7b305ea --- /dev/null +++ b/docs/audit/preuve-2026-08-10.md @@ -0,0 +1,69 @@ +# Preuve de conformite — Set-OPS — 2026-08-10 + +> Genere par `make prouver` (`scripts/prouver.py`). **Rejouable** : relancer +> reproduit ce rapport. Chaque preuve rejoue l'outillage existant du depot ; +> aucune validation n'est reimplementee ici. Voir le mode d'emploi : +> [`docs/audit/README.md`](README.md), et le registre trace : +> [`docs/audit/affirmations.md`](affirmations.md). + +- **Instance** : `instance` — inventaire `instance/inventories/principal/hosts.yml` +- **Verdict** : ✅ CONFORME (33 OK · 0 echec · 0 saute) + +## Preuves + +| # | Preuve | Affirmations | Statut | Detail | +|---|---|---|---|---| +| P01 | Lint (ansible-lint) | AFF-006 | ✅ OK |  | +| P02 | Tests unitaires (inventory_host) | — | ✅ OK | >>> le verrou tient : aucune VM n'aurait ete touchee | +| P03 | Diff-vide du plan (inventaire genere) | AFF-001, AFF-004, AFF-030, AFF-031, AFF-032 | ✅ OK | DIFF VIDE : le plan reproduit exactement l'inventaire actuel. Bascule possible. | +| P04 | Groupes <-> playbooks homonymes | AFF-008 | ✅ OK | | +| P05 | Dependances causales de groupes | AFF-009, AFF-084 | ✅ OK | | +| P06 | Validateurs de registres (serveurs/apps/bases/domaines) | AFF-003 | ✅ OK | Registre des domaines valide. | +| P07 | GUI (node --check) | AFF-033 | ✅ OK | JS du GUI : syntaxe valide (node --check). | +| P08 | Orchestration (couches + graphe) | AFF-070 | ✅ OK | Orchestration coherente : 30 groupes classes, aucun cycle, aucune arete en arriere. | +| P09 | Flux reseau (schema + matrice) | AFF-071 | ✅ OK | Flux coherents : 29 rôles, 75 flux, schéma + matrice OK. | +| P10 | Handlers <-> notify | AFF-034, AFF-035 | ✅ OK | Tout notify pointe vers un handler du meme role (49 roles). | +| P11 | Syntaxe des playbooks (--syntax-check) | AFF-083 | ✅ OK | playbook: playbooks/proxmox/cloner_vm_debian.yml | +| P12 | Existence des runbooks cites | AFF-010, AFF-011, AFF-012, AFF-083 | ✅ OK | 17/17 runbooks/registres cites presents. | +| P13 | Invariants structurels/doctrinaux | AFF-015, AFF-022, AFF-037, AFF-038, AFF-062 | ✅ OK | LICENSE, socle dossier, pas de couches paralleles, SSH clef-only, nftables off : OK. | +| P14 | Pas de chemin lab/ code en dur | AFF-097 | ✅ OK | Aucun chemin instance/inventories/lab/group_vars code en dur. | +| P15 | Modele public socle valide | AFF-022, AFF-099 | ✅ OK | Modele public socle : domaines/serveurs/applications/bases valides. | +| P16 | Inventaire Ansible complet (--list) | AFF-030 | ✅ OK | 14 hotes, 31 groupes (inventaire dechiffre et parse). | +| P17 | Tous les modeles valident (registres + underlay) | AFF-022, AFF-099 | ✅ OK | Les 1 modele(s) decouvert(s) valident. | +| P18 | Gabarit de voute complet | AFF-026 | ✅ OK | Gabarit de voute complet : 25 secret(s) exige(s), tous presents. Voute reelle : 28 cle(s), aucun manque. | +| P19 | Le GUI couvre le schema du plan | AFF-002, AFF-095 | ✅ OK | GUI : les 28 champ(s) des plans reels sont editables (2 plan(s) inspecte(s)), registres toleres : nomenclature. | +| P20 | Adressage 100% derive du seed (aucun stocke) | AFF-001, AFF-003 | ✅ OK | 2 nomenclature(s) : adressage 100% derive du seed index. | +| P21 | Federation : aucun index en collision | AFF-102 | ✅ OK | Federation coherente : 2 instance(s) federee(s), aucun index en collision. | +| P22 | Plan de recette a jour (genere du wiki) | AFF-002 | ✅ OK | Plan de recette à jour (20 sections). | +| P23 | Underlay sans collision avec la plage tenant | AFF-103 | ✅ OK | Underlay conforme : 6 reseau(x), aucune collision avec la plage tenant. | +| P24 | Frontiere nord/sud : acces d'administration declare | AFF-104 | ✅ OK | CONFORME : frontiere nord/sud, 39 regles, 12 routes, admin=10.0.0.0/24,192.168.254.2/32,192.168.255.2/32. | +| P25 | Pare-feu Proxmox : est-ouest intra-tenant derive | AFF-107 | ✅ OK | CONFORME : pare-feu Proxmox, 2 tenant(s), 38 groupe(s), 64 regle(s). | +| P26 | Integrations universelles : aucun hote laisse de cote | AFF-108 | ✅ OK | 14 hote(s) x 4 integration(s) universelle(s) : aucune lacune, aucune recopie (1 exemption(s) derivee(s) du service rendu). | +| P27 | Propriete des intrants : hebergeur et tenant separes | AFF-109 | ✅ OK | 0 cle(s) de cluster chez l'hebergeur, aucune recopiee dans les group_vars du tenant. | +| P28 | Pools Proxmox : un par tenant, sans collision | AFF-110 | ✅ OK | CONFORME : 2 pool(s) Proxmox, 28 VM placee(s), aucun nom ni VMID en collision. | +| P29 | Authentification : chaque role declare sa position | AFF-111 | ✅ OK | 23 role(s) serveur declares (interne-sans-auth 2, ldap-direct 2, sans-auth-humaine 12, socle-identite 2, web-sso 5) ; 2 lacune(s) nommee(s) : serveur_loki, serv | +| P30 | SDN EVPN : zones, VNets et sous-reseaux derives | AFF-112 | ✅ OK | CONFORME : SDN EVPN, 2 zone(s), 12 VNet(s), 12 sous-reseau(x), aucune collision. | +| P31 | Documentation : tout ce que le depot FAIT est nomme | — | ✅ OK | 41 scripts expliques et atteignables, 90 cibles make documentees, 54 roles avec README. | +| P32 | Intrants exiges par les roles : tous fournis | — | ✅ OK | CONFORME : 30 exigence(s) de role, toutes satisfaites (126 cle(s) declaree(s) par l'instance). | +| P33 | Aucune collision de port entre roles co-localises | — | ✅ OK | CONFORME : 32 revendication(s) de port, aucune collision entre roles co-localises (33 groupes). | + +## Couverture des affirmations ✅ du registre + +Chaque affirmation ✅ automatisable est couverte par la preuve indiquee ci-dessus. +Les ✅ **structurelles/doctrinales** non rejouables par une commande (ex. AFF-005 +`make`=aide, AFF-014 ciblage groupe, AFF-024 `instancier-appliquer`, AFF-051 autorite +d'AGENTS.md, AFF-073/075 gardes `make`, AFF-090 wiki) ont ete verifiees a l'audit ; +elles restent hors du harnais recurrent (rien d'executable a rejouer). + +## Declarations d'intention (⚪ invérifiables localement — assumees) + +Ces affirmations ne sont pas rejouables hors production ; elles sont **assumees** +comme declarations d'intention, non comme preuves : + +- **AFF-036** — « testables avec `--check` autant que possible » : verifiable seulement + contre une flotte vivante. +- **AFF-091** — contenu pedagogique du wiki : affirmations conceptuelles. +- **AFF-096** — « GUI 100 % francais » : revue exhaustive des libelles rendus, non automatisee. +- **AFF-007** — hote d'exemple `web-frontal-01` : placeholder assume. + +_Rapport genere le 2026-08-10._ diff --git a/docs/carte-set-ops.md b/docs/carte-set-ops.md index c920b94..c3c2bae 100644 --- a/docs/carte-set-ops.md +++ b/docs/carte-set-ops.md @@ -1,12 +1,17 @@ # Carte d'orientation Set-OPS -> **À lire en premier.** Point d'entrée vers le corpus documentaire, et **catalogue des -> mécanismes transverses** — ceux qui vivent dans le code et qu'on *re-découvre* sinon. -> Créée le 2026-07-03 après un audit du dépôt, **revue le 2026-07-29**. But : ne plus -> re-déterrer ce qui existe. +> **Pour qui :** le **mainteneur** — celui qui va *modifier* le moteur. À lire avant +> d'ajouter quoi que ce soit. +> +> Tu viens plutôt **exploiter** un écosystème déjà déployé ? Wiki → +> **Reprendre l'écosystème**. Tu **apprends** le métier ? Wiki → **Accueil**. -Le dépôt est **déjà bien documenté** (26 docs + 7 pièces d'audit + 21 unités de wiki, et un -README par rôle). Le manque n'était pas la doc du *modèle*, +Point d'entrée vers le corpus documentaire, et **catalogue des mécanismes transverses** — +ceux qui vivent dans le code et qu'on *re-découvre* sinon. Créée le 2026-07-03 après un audit +du dépôt, **revue le 2026-07-29**. But : ne plus re-déterrer ce qui existe. + +Le dépôt est **déjà bien documenté** (34 docs + 15 pièces d'audit + 23 unités de wiki, et un +README pour chacun des 54 rôles). Le manque n'était pas la doc du *modèle*, mais (a) un index « par où commencer » et (b) une carte des *mécanismes* (dispersés dans le code + les README de rôles). Cette page comble ces deux trous. diff --git a/wiki/Home.md b/wiki/Home.md index 9aa61ad..0499ca7 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -1,5 +1,10 @@ # Set-OPS — moteur souverain **et** compagnon pédagogique +> **Pour qui :** celui qui **apprend le métier**. Chaque unité part d'un fondamental TIC, pas +> d'un produit. Pour *exploiter* dès aujourd'hui, va à +> **[Reprendre l'écosystème](Reprendre-l-écosystème)** ; pour *modifier* le moteur, la carte +> du dépôt est dans `docs/carte-set-ops.md`. + Bienvenue. **Set-OPS** est le moteur Ansible qui déploie un **écosystème numérique souverain complet** (Alliance Boréale · *tout est libre*). Mais c'est aussi, et volontairement, un **outil pédagogique** : il instancie *pour de vrai* la quasi-totalité des **fondamentaux des TIC**, avec @@ -12,10 +17,6 @@ des **méthodes 100 % génériques**. « Keycloak » — tu apprends le **SSO/OIDC**. Pas « step-ca » — la **PKI**. Ces savoirs se **transfèrent partout** (Active Directory, Okta, Vault, n'importe quel DNS…). -> **Tu ne découvres pas — tu viens d'hériter d'un écosystème déjà déployé ?** -> Commence par **[Reprendre l'écosystème](Reprendre-l-écosystème)** : dans quel état tu -> hérites, comment entrer, et ce qui va te mentir en chemin. - > **Ce wiki est publié depuis le dépôt** (`wiki/`). Une page modifiée dans l'interface de la > forge est **détruite** à la publication suivante : on lit ici, on écrit dans le dépôt.