From a8bea83a917095969d65ca84b8042a74dfd21239 Mon Sep 17 00:00:00 2001 From: Daniel Allaire Date: Fri, 3 Jul 2026 09:16:14 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20carte=20d'orientation=20(index=20+=20m?= =?UTF-8?q?=C3=A9canismes)=20+=20rafra=C3=AEchir=20la=20maturit=C3=A9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Après audit du dépôt : docs/carte-set-ops.md = point d'entrée « à lire d'abord » (index du corpus) + catalogue des mécanismes transverses (2 directions de binding, pont de cert, résolution BD par registre, socle-first, check-mode, voûte) avec où ils vivent. But : ne plus re-découvrir l'existant. Constat : la cruft était déjà inventoriée dans catalogue-services.md (rôles-catégories inertes, échafaudages) — référencée, pas dupliquée. catalogue-services « État d'implémentation » rafraîchi (rôles éprouvés sur VM réelles : socle, PKI, LDAP, DNS, nginx, pile courriel). Pointeur ajouté depuis architecture-set-ops.md. Co-Authored-By: Claude Opus 4.8 --- CHANGELOG.md | 8 +++++ docs/architecture-set-ops.md | 1 + docs/carte-set-ops.md | 64 ++++++++++++++++++++++++++++++++++++ docs/catalogue-services.md | 9 +++++ 4 files changed, 82 insertions(+) create mode 100644 docs/carte-set-ops.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e120780..abcb1f7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -21,6 +21,14 @@ conservé** (le secret ne quitte jamais le rôle) — ne PAS dupliquer en app-side/instancier. Deux directions assumées : app→app côté app (instancier), app→base côté base (registre). Reste (reporté à l'épreuve de Keycloak) : factoriser le bloc de résolution copié-collé en include partagé (DRY). +- **`docs/carte-set-ops.md` — carte d'orientation (index + mécanismes transverses).** Après audit + du dépôt : point d'entrée « à lire d'abord » (index du corpus, ~22 docs), et **catalogue des + mécanismes** dispersés dans le code (les 2 directions de binding, pont de cert, résolution BD + par registre, socle-first, sûreté check-mode, voûte, dimensionnement) avec **où ils vivent**. + But : ne plus re-découvrir l'existant. Constat : la **cruft était déjà inventoriée** dans + `catalogue-services.md` (rôles-catégories inertes, échafaudages) — non dupliquée, référencée. + `catalogue-services.md` « État d'implémentation » **rafraîchi** (rôles éprouvés sur VM réelles : + socle, PKI, LDAP, DNS, nginx, pile courriel). Pointeur ajouté depuis `architecture-set-ops.md`. ## 2026-07-02 diff --git a/docs/architecture-set-ops.md b/docs/architecture-set-ops.md index 1d6e4a5..d662dff 100644 --- a/docs/architecture-set-ops.md +++ b/docs/architecture-set-ops.md @@ -4,6 +4,7 @@ Set-OPS définit et construit l'écosystème numérique souverain. Il se pilote par un **plan** : l'inventaire Ansible (`instance/inventories/production/hosts.yml`) est **généré** depuis le plan, pas édité à la main. +- **Par où commencer + catalogue des mécanismes transverses : `docs/carte-set-ops.md`.** - Modèle, registres, commandes et flux de travail : **`docs/plan-et-generation.md`**. - Règles d'autorité : **`AGENTS.md`** (sections « Mission et identité » et « Le plan et la génération de l'inventaire »). diff --git a/docs/carte-set-ops.md b/docs/carte-set-ops.md new file mode 100644 index 0000000..67b9bd0 --- /dev/null +++ b/docs/carte-set-ops.md @@ -0,0 +1,64 @@ +# 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. But : ne plus re-déterrer ce qui existe. + +Le dépôt est **déjà bien documenté** (~22 docs). 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. + +## 1. À lire d'abord (dans l'ordre) + +| Sujet | Documents | +|---|---| +| **Autorité / gouvernance** | `AGENTS.md` (source d'autorité), `CLAUDE.md`, `docs/MISE-A-JOUR-CODEX-CLAUDE.md` | +| **Le modèle (plan)** | `docs/architecture-set-ops.md` (survol) → `docs/plan-et-generation.md` (à fond) → `docs/meta-classe.md` (concept) | +| **Services, maturité, dette** | `docs/catalogue-services.md` (**la carte de maturité + la cruft y sont déjà**) | +| **Exploitation / VM** | `docs/vm-lifecycle.md`, `docs/procedure-template-debian13-proxmox.md`, `docs/config-proxmox.md`, `docs/nomenclature-vm.md`, `docs/multi-instances.md` | +| **Conceptions de domaine** | `docs/identite-sso.md`, `docs/courriel-conception.md`, `docs/bindings-conception.md`, `docs/dns-interne.md`, `docs/dimensionnement-ressources.md`, `docs/integrations-vm.md` | +| **Vision / positionnement** | `docs/ecosysteme-chezlepro.md`, `docs/positionnement.md`, `docs/pouvoirs-set-ops.md` | + +## 2. Les mécanismes transverses (et OÙ ils vivent) + +Ce que je re-découvre sinon. **Consulter avant de concevoir un nouveau mécanisme.** + +| Mécanisme | Ce que c'est | Où, dans le code | Doc | +|---|---|---|---| +| Plan → inventaire | `plan/*.yml` → `hosts.yml` généré | `scripts/instancier.py`, `scripts/inventory_rules.py` | `plan-et-generation.md` | +| Nomenclature dérivée | VMID / IP / VLAN / FQDN dérivés | `inventory_rules.deriver_nomenclature` + `plan/nomenclature.yml` | `nomenclature-vm.md` | +| Dimensionnement | RAM/CPU/disque sommés par logiciel | `roles/*/meta/empreinte.yml` → `deriver_ressources` | `dimensionnement-ressources.md` | +| **Bindings app→app** | lien **côté app** (`liens`) résolu en host_vars | `plan/applications.yml` `liens:` + `roles/*/meta/liens.yml` + `instancier.resoudre_liens` | `bindings-conception.md` | +| **Bindings app→base** | lien **côté base** (`consommateur`/`portee`) résolu **dans le rôle** | `plan/bases-donnees.yml` + `include_vars`/`lookup('vars', secret)` dans les rôles consommateurs | `bindings-conception.md` §5 | +| Pont de certificat | cert step_ca → service, resync au renouvellement | script `*-cert-sync` + unité `.path`, dans chaque rôle serveur ; cert déposé par `client_pki` | — | +| Ordonnancement socle-first | socle/durci avant les `client_*` | `serveur_debian`/`serveur_durci` d'abord (posent `/etc/hosts` via `hosts_statiques`) | — | +| Sûreté check-mode | dry-run fiable | `when: not ansible_check_mode` sur les tâches de service + handlers | — | +| Voûte au déploiement | secret jamais en clair | `ANSIBLE_VAULT_PASSWORD_FILE` / `~/.config/setops-vault-pass` ; déréférencé par `lookup('vars', )` | — | +| Multi-instance | un dépôt par écosystème | symlink `instance/` | `multi-instances.md` | +| Exposition → edge | app expose un FQDN public servi par un edge | `plan/domaines.yml` + `expose` (applications) | `bindings-conception.md` §4 | + +> ⚠️ **Deux directions de binding, assumées** : `app→app` côté app (instancier), +> `app→base` côté base (registre, résolu en rôle pour que le secret ne quitte jamais le rôle). +> Ne pas unifier l'un dans l'autre sans raison. Cf. `bindings-conception.md`. + +## 3. Maturité & dette + +- **Maturité des rôles, échafaudages, rôles-catégories inertes** : voir + `docs/catalogue-services.md` « État d'implémentation » (source de vérité, tenue à jour). +- **Dette repérée en plus (audit 2026-07-03)** : + - README manquants sur les rôles récents : `serveur_dovecot`, `serveur_postfix`, + `serveur_rspamd`, et `hosts_statiques` ; + - `meta/liens.yml` seulement sur `serveur_postfix` (les autres liens app→app viendront) ; + - `requiert` / `expose` : câblés **côté GUI** (édition + validation `valider_applications`) + mais **pas encore consommés au déploiement** — `expose`→vhost nginx = Phase 3 des bindings ; + `requiert` = indice de dépendance (les dépendances de *groupes* sont dans + `docs/dependances-groupes.yml`, lues par la GUI). + +## 4. Discipline (pour ne plus re-déterrer) + +Avant de concevoir ou d'ajouter un mécanisme : +1. lire **cette carte** + le doc du sujet ; +2. **arpenter le code** (`grep`) et **lire les README des rôles** concernés ; +3. **étendre / factoriser** l'existant plutôt qu'ajouter un chemin parallèle. + +Un seul agent IA travaille dans le dépôt à la fois (Codex **ou** Claude) — cf. `AGENTS.md`. diff --git a/docs/catalogue-services.md b/docs/catalogue-services.md index c43e548..f3200c3 100644 --- a/docs/catalogue-services.md +++ b/docs/catalogue-services.md @@ -30,6 +30,15 @@ Un service central peut partager un hôte avec d'autres services de la même fon `client_journal`, `serveur_grafana`, `serveur_icinga`, `serveur_forgejo`. Plus le socle et le durcissement, appliqués par `serveur_debian` / `serveur_durci`. +**Éprouvés sur VM réelles (mise à jour 2026-07-03)** — déployés et prouvés de bout en bout sur +le cluster Proxmox (plus seulement « code ») : le **socle + durcissement**, `serveur_step_ca` + +`client_pki` (mTLS avec SAN), `serveur_openldap` (LDAPS), `serveur_powerdns`, `serveur_nginx`, +et la **pile courriel complète** `serveur_dovecot` + `serveur_postfix` + `serveur_rspamd` +(flux SMTP→LDAP→LMTP→IMAP + antispam + DKIM prouvé). Nouveaux rôles ⋆ mail = déployés, +idempotents. Restent « code non éprouvé » : `serveur_keycloak`, `serveur_postgresql`, +`serveur_redis`, `serveur_prometheus`, `serveur_loki`, `serveur_grafana`, `serveur_icinga`, +`serveur_forgejo`, `serveur_sendmail`. + **Échafaudages** (playbook-ancre `debug` « reste à définir », **sans rôle**) : `serveur_nextcloud`, `serveur_collabora`, `client_supervision`, `serveur_web_frontal`, `serveur_web_dorsal`. Les capacités *collaboration* et *couche web applicative* sont câblées