Set-OPS-Public/docs/frontiere-physique-virtuel.md

# La frontière entre les deux mondes — physique et virtuel

> **Pour qui :** l'**exploitant** et le **mainteneur**. Ce document tranche une question qui
> revenait à chaque décision : *qui possède quoi, et où ça vit ?*

Set-OPS manipule deux mondes qui se ressemblent et n'obéissent pas aux mêmes règles. Les
confondre a coûté plusieurs soirées ; les séparer proprement rend la plupart des questions
suivantes évidentes.

---

## Les deux mondes

| | **Monde PHYSIQUE** — l'underlay | **Monde VIRTUEL** — le tenant |
|---|---|---|
| Ce que c'est | commutateurs, hyperviseurs, frontière, stockage, transport VXLAN | VM, applications, données |
| Possédé par | l'**hébergeur** | l'**organisation** |
| Adressage | bande basse du site : `10.<index>.0-15.x` | zones : `10.<index>.16+.x` |
| Décrit dans | `underlay.yml`, `proxmox-hebergeur.yml` | `plan/` |
| Monté par | le symlink `underlay.yml` | le symlink `instance` |
| Change quand | on touche au **matériel** | on touche au **service** |
| Ses secrets | jeton d'API Proxmox, clé d'API de la frontière, accès aux commutateurs | LDAP, forge, SSO, bases |
| Sa voûte | **la sienne**, chez l'hébergeur | `group_vars/all/vault.yml` |

**Les deux symlinks sont indépendants** (D-80) : `instance` dit *quel tenant*,
`underlay.yml` dit *sur quelle fabric*. Un tenant se déplace d'une fabric à l'autre sans
qu'on touche à son plan — c'est ce qui rend la portabilité possible.

---

## La règle qui rend la frontière opérante

> **Un tenant ne détient jamais un secret du monde physique.**

Chaque tenant a porté dans sa voûte le jeton d'API du cluster — patient 0 a dû le recopier
pour exister. C'était exactement la faute des **neuf copies** de la résolution d'instance,
appliquée aux secrets : une valeur qui vit à N endroits finit par diverger, et on ne peut
plus révoquer l'une sans révoquer les autres.

**C'est réglé depuis le 2026-08-22** : l'underlay a **sa propre voûte**
(`underlay.vault.yml`), chez l'hébergeur, à côté d'`underlay.yml`. Les opérations qui parlent
au matériel — cloner une VM, poser une zone SDN, écrire sur la frontière — l'y lisent : le
chemin se **dérive** du symlink `underlay.yml`, sans rien redéclarer
(`playbooks/proxmox/cloner_vm_debian.yml`). Les tenants n'y ont pas accès et n'en ont pas
besoin.

Deux compléments arrivés depuis, et qui achèvent la séparation :

- les **clés** aussi sont séparées (2026-08-28) : une voûte, **une clé**. Tant qu'un seul mot
  de passe les ouvrait toutes, la séparation était organisationnelle, pas cryptographique ;
- **P25** refuse qu'une clé de l'hébergeur — nœuds, stockages, ponts, API — réapparaisse dans
  un `group_vars` de tenant. La garde attrape la rechute : un `make config` lancé d'un autre
  poste, une reprise à la main.

---

## Qui administre quoi, et depuis où

L'administration du monde physique se fait **depuis le tenant de l'hébergeur** : c'est lui
qui porte les outils, les clés et les traces. Le plan de gestion du site
(`10.<index>.0.0/24`) est la seule source autorisée à ouvrir SSH sur la flotte et à
franchir la frontière.

Ce n'est pas un détail de commodité. Une machine qui administre depuis l'extérieur des deux
mondes — un portable sur le réseau de la maison — n'est ni sauvegardée, ni reconstructible,
ni prouvée. Le jour où elle disparaît, l'écosystème est intact et personne ne peut plus y
entrer.

---

## Ce que la confusion a coûté

**Une règle qui ne peut jamais correspondre.** `devis_opnsense` dérive l'interface d'une
règle de l'**attachement réel** de sa source (D-61), et cet attachement se lit dans
`underlay.yml`. Un plan d'administration absent du fichier est classé « distant », et sa
règle atterrit sur `wan`. Le 22 août, on s'apprêtait à poser 89 objets sur la frontière
avec une règle d'admin qui n'aurait jamais laissé passer personne.

**Un fichier qui décrit un monde disparu.** Mesuré le même jour :

```
management  10.0.0.0/24    déclaré  →  PERSONNE
stockage    10.0.1.0/24    déclaré  →  PERSONNE
ceph        10.0.2-3.0/24  déclaré  →  PERSONNE
transit     10.0.4.0/24    déclaré  →  occupé (3 nœuds)
vxlan       10.0.5.0/24    déclaré  →  occupé (3 nœuds)

et, portés par les nœuds sans être déclarés nulle part :
192.168.11.x  10.11.5-7.x  192.168.50.x  10.1.110.254
```

La frontière avait déjà migré vers `10.17.0.1` ; les hyperviseurs, non. Le fichier était
resté au monde d'avant.

---

## L'instrument

```
make underlay-plan      # confronte le fichier au réel, n'écrit rien
```

Il interroge l'API du cluster pour les adresses **réellement portées**, et sonde en TCP ce
qui répond. Deux précautions y sont inscrites, toutes deux apprises en l'écrivant :

- **l'autorité dépend du rôle.** L'API de Proxmox connaît ses hyperviseurs, et eux seuls.
  Déclarer un commutateur « porté par personne » parce que le cluster l'ignore, c'est
  accuser le monde de ce que l'instrument ne voit pas ;
- **« pas joignable d'ici » n'est pas « absent ».** Les réseaux de *chemin* (transit,
  transport VXLAN, stockage) ne sont **jamais** joignables depuis l'extérieur, par
  construction (D-78). Le premier jet du devis les déclarait morts.

---

## La séquence — faite, dans cet ordre

Cette section était une liste de tâches ouvertes. **Les trois sont faites** ; on la garde
sous forme d'ordre parce que c'est l'ordre lui-même qui est la leçon — un site neuf le
rejouera tel quel.

- [x] **Reconnaître** — `make underlay-plan` confronte l'underlay *déclaré* au réel (API du
      cluster + sondes). `underlay.yml` décrit ce qui **est**, pas ce qui était prévu :
      chaque réseau porté et non déclaré est un réseau que le moteur ne sait pas classer.
- [x] **Séparer les voûtes** — fait le **2026-08-28**. Une voûte, une clé
      (`scripts/voutes.py`, `ANSIBLE_VAULT_IDENTITY_LIST`) : le jeton Proxmox et la clé de
      la frontière vivent dans `underlay.vault.yml`, hors de toute voûte de tenant. La
      séparation devait précéder la distribution des clés aux runners — sans elle, poser
      « la » clé sur le plus petit locataire lui donnait les secrets de l'hébergeur.
- [x] **Appliquer la frontière** — ses règles dépendent des deux points ci-dessus, et
      elles en dérivent : P43 mesure que le devis de la frontière retrouve les machines du
      plan (7 machines, 104 règles du site).