Set-OPS/docs/catalogue-services.md

# Catalogue des services

Ce document fixe les noms de groupes et de playbooks pour les prochains services.

La règle reste :

```text
groupe opérationnel -> playbooks/groupes/<groupe>.yml
```

Les playbooks ajoutés maintenant sont des points d'ancrage. Ils ne doivent pas installer un service tant que le rôle correspondant n'existe pas et que ses variables, secrets et prérequis sont documentés.

La nomenclature des VM et des VMID est documentée dans `docs/nomenclature-vm.md`.

Un service central peut partager un hôte avec d'autres services de la même fonction opérationnelle (plusieurs applications par VM). La relation stricte est entre groupe et playbook, pas entre groupe et VM.

> Modèle à jour : chaque service est une **application** (`instance/plan/applications.yml`). Voir `docs/plan-et-generation.md`.

## État d'implémentation des rôles

> **Mise à jour (2026-06-24).** La plupart des rôles ci-dessous **existent désormais** —
> écrits et validés *en tant que code*, **pas encore éprouvés sur des VM réelles**. Le rôle
> effectif porte le nom du **groupe** (`serveur_keycloak`, `client_pki`…), pas le nom court
> de la colonne « Rôle » des tables.

**Implémentés** (`tasks` + `templates` + `handlers`, validés) : `serveur_step_ca`,
`client_pki`, `serveur_powerdns`, `client_dns`, `serveur_openldap`, `client_ldap`,
`serveur_keycloak`, `serveur_postgresql`, `serveur_redis`, `serveur_nginx`,
`serveur_sendmail`, `client_smtp`, `serveur_prometheus`, `client_metrique`, `serveur_loki`,
`client_journal`, `serveur_grafana`, `serveur_icinga`, `serveur_forgejo`. Plus le socle et
le durcissement, appliqués par `serveur_debian` / `serveur_durci`.

**É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
par convention mais pas encore implémentées.

**Rôles-catégories inertes** (dossiers `roles/<x>/` réduits à un `README.md`, jamais câblés) :
`applications`, `backup`, `database`, `identity`, `monitoring`, `proxmox`, `storage`, `web`.
L'architecture réelle est **plate** (`serveur_*` / `client_*`) ; ces dossiers sont des
vestiges d'un regroupement par catégorie abandonné — à supprimer ou réactiver lors d'une
consolidation ultérieure.

## Services centraux

| Service | Groupe | Playbook | Rôle |
| --- | --- | --- | --- |
| Keycloak | `serveur_keycloak` | `playbooks/groupes/serveur_keycloak.yml` | `keycloak` |
| OpenLDAP | `serveur_openldap` | `playbooks/groupes/serveur_openldap.yml` | `openldap` |
| PostgreSQL | `serveur_postgresql` | `playbooks/groupes/serveur_postgresql.yml` | `postgresql` |
| Loki | `serveur_loki` | `playbooks/groupes/serveur_loki.yml` | `loki` |
| Plateforme Icinga | `serveur_icinga` | `playbooks/groupes/serveur_icinga.yml` | `icinga` |
| Prometheus | `serveur_prometheus` | `playbooks/groupes/serveur_prometheus.yml` | `prometheus` |
| Grafana | `serveur_grafana` | `playbooks/groupes/serveur_grafana.yml` | `grafana` |
| Forgejo | `serveur_forgejo` | `playbooks/groupes/serveur_forgejo.yml` | `forgejo` |
| Sendmail MTA | `serveur_sendmail` | `playbooks/groupes/serveur_sendmail.yml` | `sendmail` |
| step-ca | `serveur_step_ca` | `playbooks/groupes/serveur_step_ca.yml` | `step_ca` |
| PowerDNS | `serveur_powerdns` | `playbooks/groupes/serveur_powerdns.yml` | `serveur_powerdns` |
| Redis | `serveur_redis` | `playbooks/groupes/serveur_redis.yml` | `redis` |
| NGINX WAF et reverse proxy | `serveur_nginx` | `playbooks/groupes/serveur_nginx.yml` | `nginx` |
| Nextcloud | `serveur_nextcloud` | `playbooks/groupes/serveur_nextcloud.yml` | `nextcloud` |
| Collabora | `serveur_collabora` | `playbooks/groupes/serveur_collabora.yml` | `collabora` |

## Couche applicative web

La couche applicative web est distincte de l'edge `serveur_nginx` :

- `serveur_nginx` est l'edge : mandataire inverse, terminaison TLS, WAF ; il reçoit le trafic externe et le route.
- `serveur_web_frontal` est la couche présentation web (UI, rendu, assets), servie *derrière* l'edge.
- `serveur_web_dorsal` est la couche application web (API, traitement), consommée par les frontaux.

Le « web » de ces deux groupes est implicite par leur position derrière `serveur_nginx`. Le jour où un service dorsal n'est pas web (worker batch, file, démon), créer un groupe dédié plutôt que d'élargir `serveur_web_dorsal`.

| Couche | Groupe | Playbook | Rôle |
| --- | --- | --- | --- |
| Présentation web (frontends) | `serveur_web_frontal` | `playbooks/groupes/serveur_web_frontal.yml` | `web_frontaux` |
| Application web (backends) | `serveur_web_dorsal` | `playbooks/groupes/serveur_web_dorsal.yml` | `web_dorsaux` |

Hôtes planifiés : `web-frontal-01` et `web-frontal-02` dans `serveur_web_frontal` ; `web-dorsal-01` dans `serveur_web_dorsal`. Aucun n'est encore actif (à créer puis activer).

Dépendance d'intégration prévue : `serveur_web_frontal` devra publier via `serveur_nginx` (règle « tout service exposé en HTTP(S) passe par l'edge »). Cette dépendance n'est pas encore déclarée dans `docs/dependances-groupes.yml` (les deux groupes sont vides) ; elle sera ajoutée avec le rôle `web_frontaux`, lorsque des frontaux actifs devront publier via l'edge.

## Hôtes planifiés

| Hôte | Services |
| --- | --- |
| `infra-pki-01` | step-ca |
| `infra-edge-01` | NGINX WAF et reverse proxy |
| `infra-mail-01` | Sendmail MTA |
| `infra-dns-01` | PowerDNS |
| `idm-01` | OpenLDAP, Keycloak |
| `data-01` | PostgreSQL, Redis |
| `obs-01` | Prometheus, Loki, Grafana |
| `mon-01` | Plateforme Icinga : Icinga 2, Icinga Web 2, Icinga BPM |
| `forge-01` | Forgejo |
| `collab-01` | Nextcloud, Collabora |

## Intégrations clientes

| Intégration | Groupe | Playbook | Rôle |
| --- | --- | --- | --- |
| Résolution DNS interne | `client_dns` | `playbooks/groupes/client_dns.yml` | `client_dns` |
| Confiance PKI / ACME | `client_pki` | `playbooks/groupes/client_pki.yml` | `client_pki` |
| Authentification LDAP | `client_ldap` | `playbooks/groupes/client_ldap.yml` | `client_ldap` |
| Supervision Icinga | `client_supervision` | `playbooks/groupes/client_supervision.yml` | `client_supervision` |
| Métriques Prometheus | `client_metrique` | `playbooks/groupes/client_metrique.yml` | `client_metriques` |
| Journaux vers Loki | `client_journal` | `playbooks/groupes/client_journal.yml` | `client_journaux` |
| Relais SMTP | `client_smtp` | `playbooks/groupes/client_smtp.yml` | `client_smtp` |

## Ordre d'implémentation recommandé

L'ordre ci-dessous privilégie les dépendances structurantes avant les applications.

### Phase 1 - Fondations transversales

1. `serveur_powerdns`
   - Service central : DNS interne autoritaire et/ou résolution interne selon le design retenu.
   - Intégration à prévoir : `client_dns`.
   - Raison : les autres intégrations auront besoin de noms stables plutôt que d'adresses IP.

2. `serveur_step_ca`
   - Service central : autorité de certification interne et ACME.
   - Intégration à prévoir : `client_pki`.
   - Raison : les autres services auront besoin de certificats fiables avant d'être exposés proprement.

3. `serveur_nginx`
   - Service central : reverse proxy, terminaison TLS, publication HTTP(S), WAF.
   - Intégration à prévoir : publication des services HTTP derrière le proxy.
   - Raison : plusieurs services seront consommés par navigateur ou API et doivent passer par un point d'entrée cohérent.

4. `serveur_sendmail`
   - Service central : relais SMTP sortant.
   - Intégration à prévoir : `client_smtp`.
   - Raison : les notifications, réinitialisations de mot de passe et alertes doivent fonctionner tôt.

### Phase 2 - Données et identité

5. `serveur_postgresql`
   - Service central : base de données relationnelle partagée.
   - Intégration à prévoir : bases dédiées par application, comptes applicatifs et sauvegardes.
   - Raison : Keycloak, Grafana, Icinga Web 2, Forgejo et Nextcloud peuvent dépendre de PostgreSQL.

6. `serveur_openldap`
   - Service central : annuaire interne.
   - Intégration à prévoir : `client_ldap`.
   - Raison : l'identité Unix et l'annuaire doivent exister avant les intégrations d'authentification avancées.

7. `serveur_keycloak`
   - Service central : SSO/OIDC/SAML.
   - Intégration à prévoir : applications web derrière `serveur_nginx`.
   - Raison : les applications devraient être branchées au SSO dès leur arrivée plutôt qu'après coup.

### Phase 3 - Observabilité minimale

8. `serveur_prometheus`
   - Service central : métriques.
   - Intégration à prévoir : `client_metrique`.
   - Raison : les prochains services doivent être mesurables dès leur déploiement.

9. `serveur_loki`
   - Service central : journaux centralisés.
   - Intégration à prévoir : `client_journal`.
   - Raison : les journaux centralisés accélèrent le diagnostic des services suivants.

10. `serveur_grafana`
   - Service central : tableaux de bord.
   - Intégration à prévoir : datasources Prometheus et Loki, authentification Keycloak.
   - Raison : Grafana consolide les métriques et journaux après leur mise en place.

### Phase 4 - Supervision active

11. `serveur_icinga`
    - Service central : supervision active, interface web et vues métiers Icinga.
    - Composants prévus : Icinga 2, Icinga Web 2, Icinga BPM.
    - Intégrations à prévoir : `client_supervision`, PostgreSQL, NGINX, Keycloak si retenu.
    - Raison : ces composants forment une même capacité de supervision et gagnent à cohabiter sur `mon-01` au départ.

### Phase 5 - Services applicatifs internes

12. `serveur_redis`
    - Service central : cache et files internes.
    - Intégration à prévoir : Nextcloud et autres applications qui en ont besoin.
    - Raison : Redis est une dépendance applicative, pas une fondation globale.

13. `serveur_forgejo`
    - Service central : forge Git.
    - Intégration à prévoir : PostgreSQL, NGINX, Keycloak, SMTP, sauvegardes.
    - Raison : la forge devient plus utile après SSO, TLS, SMTP et observabilité.

14. `serveur_nextcloud`
    - Service central : collaboration fichiers.
    - Intégration à prévoir : PostgreSQL, Redis, NGINX, Keycloak, SMTP, sauvegardes.
    - Raison : Nextcloud dépend de plusieurs fondations et doit arriver après elles.

15. `serveur_collabora`
    - Service central : édition documentaire en ligne.
    - Intégration à prévoir : Nextcloud, NGINX, certificats.
    - Raison : Collabora est une extension de Nextcloud et doit venir après lui.

## Règles d'intégration

- Tout service exposé en HTTP(S) doit prévoir son intégration avec `serveur_nginx`.
- Tout service avec authentification humaine doit prévoir son intégration avec `serveur_keycloak`, sauf justification contraire.
- Tout service générant des alertes ou notifications doit prévoir `client_smtp`.
- Toute VM de service doit rejoindre `client_metrique`, `client_journal` et `client_supervision` quand les services centraux correspondants existent.
- Tout service utilisant un certificat interne doit dépendre de `client_pki`.
- Tout rôle serveur doit documenter ses ports, secrets, sauvegardes, dépendances et groupes clients associés.

Les groupes clients peuvent être ajoutés aux VM existantes quand le service central correspondant est réellement disponible.

## Dépendances causales

Les dépendances exécutables sont déclarées dans `docs/dependances-groupes.yml`.

Le runbook DNS initial est dans `docs/dns-interne.md`.

Ce fichier sert à deux usages :

- bloquer le déploiement d'un groupe tant que ses prérequis actifs ne sont pas présents ;
- fournir une source exploitable pour les futurs modèles de supervision.

Un hôte peut porter un groupe client à l'état planifié. Le déploiement est refusé tant que le groupe serveur requis n'a pas au moins un hôte actif.