#!/usr/bin/env python3 """La fiche d'un role : comment il est branche dans l'ecosysteme. GENEREE, JAMAIS ECRITE — ET C'EST TOUT L'INTERET. Soixante-huit roles. Autant de pages faites a la main seraient perimees avant la fin du mois : c'est le defaut que ce depot traque partout ailleurs sous le nom « une liste qui suit une autre prend du retard ». Une soixante-neuvieme liste ne ferait pas exception. CE QUE LA FICHE LIT, ELLE NE L'INVENTE PAS. Chaque rôle DECLARE deja ce qu'il faudrait dessiner, et chaque declaration porte sa RAISON : meta/flux.yml qui lui parle, sur quel port, et pourquoi meta/authentification.yml qui il laisse entrer meta/empreinte.yml ce qu'il coute meta/supervision.yml quel verdict il rend meta/metriques.yml quelles series il expose UNE SECTION VIDE EST UNE INFORMATION, PAS UN DEFAUT DE LA FICHE. Un role qui ne declare aucune supervision l'affiche ; la fiche devient alors la carte de ce qui reste a faire, tenue a jour toute seule. CE QU'ELLE N'EST PAS : les pages de flux ecrites a la main racontent « par ou passe l'heure, un certificat, un courriel » — un mecanisme qui traverse plusieurs machines, et qu'on LIT pour comprendre. Cette fiche-ci repond a « ce role, il est branche comment ? », et on la CONSULTE pour agir. Aucune ne remplace l'autre. """ from __future__ import annotations import sys from pathlib import Path import yaml RACINE = Path(__file__).resolve().parents[1] ROLES = RACINE / "roles" # UN SEUL DOMICILE, ET C'EST LE WIKI. Ces fiches sont faites pour etre LUES, et le wiki # est l'endroit ou l'on lit — « on lit la-bas, on ecrit ici ». Les garder aussi dans # `docs/` en ferait deux copies du meme contenu, donc deux listes dont l'une prendrait du # retard sur l'autre. On connait la suite. # # LE PREFIXE GROUPE. Vingt-sept pages redigees a la main vivent deja ici ; soixante-huit # fiches generees les noieraient dans l'index de la forge. `Role-` les rassemble, et # `Roles.md` sert de porte d'entree. SORTIE = RACINE / "wiki" PREFIXE = "Rôle-" def lire(role: str, nom: str): f = ROLES / role / "meta" / f"{nom}.yml" if not f.is_file(): return None try: return yaml.safe_load(f.read_text(encoding="utf-8")) except yaml.YAMLError as e: return {"_erreur": str(e)} def court(r: str) -> str: """`serveur_postgresql` -> `postgresql`. Les diagrammes se lisent mieux courts.""" return r.split("_", 1)[1] if "_" in r else r def diagramme(role: str, flux, supervision, metriques) -> list[str]: """Le role au centre ; ce qui entre a gauche, ce qu'il rend a droite. MERMAID, PAS UNE IMAGE. Une image se regenere a la main et diverge ; un bloc mermaid vit dans le fichier, se relit en diff, et se rend aussi bien sur la forge que dans une page publiee. """ L = ["```mermaid", "graph LR"] moi = court(role) L.append(f' R["{moi}"]') entrants = [] for fl in (flux or {}).get("flux", []): if fl.get("sens") != "ingress": continue ports = fl["port"] if isinstance(fl["port"], list) else [fl["port"]] for p in (fl.get("pair") if isinstance(fl.get("pair"), list) else [fl.get("pair")]): if p: entrants.append((court(str(p)), "/".join(str(x) for x in ports), str(fl.get("chiffrement", "")))) for i, (src, ports, chif) in enumerate(sorted(set(entrants))): sur = f"{ports}" + (f" · {chif}" if chif and chif not in ("n-a", "aucun") else "") L.append(f' E{i}["{src}"] -->|"{sur}"| R') for s in (supervision or {}).get("sondes", []): L.append(f' R -.->|"sonde « {s["nom"]} »"| ICINGA[["Icinga"]]') expo = (metriques or {}).get("exportateur") if expo: L.append(f' R -.->|"{expo.get("port")} · {expo.get("job")}"| PROM[["Prometheus"]]') L.append("```") return L def fiche(role: str) -> str: flux = lire(role, "flux") sup = lire(role, "supervision") met = lire(role, "metriques") emp = lire(role, "empreinte") aut = lire(role, "authentification") L = [f"# Rôle `{role}`", "", "> **Généré** par `scripts/fiche_role.py` depuis les `meta/` de ce rôle.", "> Ne pas éditer à la main : corriger la déclaration, puis régénérer.", "", "> **Pour qui :** celui qui doit agir sur ce rôle et veut savoir, avant de " "toucher quoi que ce soit, qui lui parle, ce qu'il rend, et ce qu'il coûte.", ""] L += diagramme(role, flux, sup, met) + [""] L += ["## Qui lui parle", ""] entrants = [f for f in (flux or {}).get("flux", []) if f.get("sens") == "ingress"] if entrants: L += ["| port | depuis | chiffrement | pourquoi |", "|---|---|---|---|"] for f in entrants: pairs = f.get("pair") if isinstance(f.get("pair"), list) else [f.get("pair")] L.append(f"| `{f['port']}` | {', '.join(f'`{p}`' for p in pairs if p) or '—'} " f"| {f.get('chiffrement', '—')} | {f.get('raison', '').strip()} |") else: L.append("*Aucun flux entrant déclaré — `meta/flux.yml` absent ou sans `ingress`.*") L.append("") L += ["## Ce qu'il rend à la supervision", ""] if (sup or {}).get("sondes"): L += ["| sonde | TTL | ce qu'elle voit |", "|---|---|---|"] for s in sup["sondes"]: L.append(f"| `{s['nom']}` | {s.get('ttl', '—')} s | {s.get('raison', '').strip()} |") else: L.append("*Aucune sonde déclarée. Un service qui porte de l'état et n'en déclare " "aucune mérite qu'on se demande pourquoi — voir `docs/supervision-conception.md`.*") L.append("") # LES DEUX MOITIES DE `metriques.yml` SONT INDEPENDANTES, ET LA FICHE LES LISAIT # IMBRIQUEES (corrige le 2026-09-14). Le tableau des panneaux vivait DANS la condition # de l'exportateur : un role qui declare des panneaux SANS exportateur — comme # `client_metrique`, dont le job `node` est universel et ecrit ailleurs — affichait # « aucun exportateur declare » et cachait ses quatre panneaux. # # Une fiche qui tait ce qu'un role declare est pire qu'une fiche absente : elle # affirme que rien n'existe. L += ["## Ce qu'il expose en séries", ""] expo = (met or {}).get("exportateur") panneaux = (met or {}).get("panneaux") or [] if expo: L += [f"Exportateur `{expo.get('paquet')}` — port **{expo.get('port')}**, " f"job `{expo.get('job')}`.", ""] elif panneaux: L += ["*Aucun exportateur propre : les séries viennent d'un collecteur universel " "(`node_exporter`), déclaré une seule fois.*", ""] else: L.append("*Aucun exportateur déclaré — voir `docs/metriques-conception.md`.*") if panneaux: L += ["| panneau | unité | pourquoi on le regarde |", "|---|---|---|"] for p in panneaux: L.append(f"| {p['titre']} | {p.get('unite', '—')} | {p.get('raison', '').strip()} |") elif expo: L.append("*Séries collectées, aucun panneau déclaré : personne ne les regarde " "encore.*") L.append("") L += ["## Ce qu'il coûte, et qui entre", ""] e = (emp or {}).get("setops_empreinte") L.append(f"- **Empreinte** : {e['coeurs']} cœur(s), {e['memoire_mo']} Mo, " f"{e['disque_go']} Go." if e else "- **Empreinte** : non déclarée.") a = (aut or {}).get("authentification") L.append(f"- **Authentification** : `{a['portee']}` — {a.get('raison', '').strip()}" if a else "- **Authentification** : non déclarée.") L.append("") return "\n".join(L) def index(noms: list[str]) -> None: """La porte d'entree des fiches, avec le compte de ce qui manque. CE TABLEAU EST LA VRAIE VALEUR DE L'ENSEMBLE. Une fiche dit comment UN role est branche ; l'index dit ce que la flotte ne declare pas encore — et il se recompte a chaque generation, sans que personne ait a tenir la liste. """ lignes = [ "# Les rôles, un par un", "", "> **Généré** par `make fiches`. Ne pas éditer à la main : corriger la " "déclaration du rôle, puis régénérer.", "", "> **Pour qui :** celui qui doit agir sur un rôle et veut savoir, avant de toucher " "quoi que ce soit, qui lui parle, ce qu'il rend et ce qu'il coûte.", "", "Chaque fiche est construite depuis ce que le rôle **déclare lui-même** — " "`meta/flux.yml`, `meta/supervision.yml`, `meta/metriques.yml`, " "`meta/empreinte.yml`, `meta/authentification.yml`. Aucune n'est écrite à la main : " "soixante-huit pages rédigées seraient périmées avant la fin du mois.", "", "**Une colonne vide est une information**, pas un trou dans la fiche. C'est la " "carte de ce qui reste à déclarer, tenue à jour toute seule.", "", "| rôle | flux entrants | sonde | métriques |", "|---|---|---|---|", ] manque = {"flux": 0, "sonde": 0, "metriques": 0} for r in noms: fl = lire(r, "flux") or {} entrants = len([f for f in fl.get("flux", []) if f.get("sens") == "ingress"]) sondes = len((lire(r, "supervision") or {}).get("sondes", [])) expo = 1 if (lire(r, "metriques") or {}).get("exportateur") else 0 for cle, v in (("flux", entrants), ("sonde", sondes), ("metriques", expo)): if not v: manque[cle] += 1 lignes.append(f"| [`{r}`]({PREFIXE}{r}) | {entrants or '—'} | {sondes or '—'} " f"| {'oui' if expo else '—'} |") lignes += ["", "## Ce qui reste à déclarer", "", f"Sur **{len(noms)}** rôles :", "", f"- **{manque['flux']}** ne déclarent aucun flux entrant", f"- **{manque['sonde']}** ne déclarent aucune sonde", f"- **{manque['metriques']}** ne déclarent aucune métrique", "", "Ces nombres ne sont pas tous des dettes : un rôle de durcissement n'a " "rien à exposer, et beaucoup de `client_*` n'ont aucun verdict à rendre. " "Mais un service qui porte de l'état et ne déclare rien mérite qu'on se " "demande pourquoi.", ""] (SORTIE / "Rôles.md").write_text("\n".join(lignes) + "\n", encoding="utf-8") if __name__ == "__main__": noms = sys.argv[1:] or sorted(d.name for d in ROLES.iterdir() if d.is_dir()) SORTIE.mkdir(parents=True, exist_ok=True) for r in noms: if not (ROLES / r).is_dir(): print(f"Refus: role inconnu « {r} ».", file=sys.stderr) raise SystemExit(2) (SORTIE / f"{PREFIXE}{r}.md").write_text(fiche(r) + "\n", encoding="utf-8") index(noms) print(f"{len(noms)} fiche(s) + index dans {SORTIE.relative_to(RACINE)}/")