Set-OPS-Public/docs/usage.md

# Utilisation

> **Pour qui :** l'exploitant et le mainteneur — la référence de l'outil en ligne de
> commande. Set-OPS est un outil CLI : tout passe par `make`, qui appelle Ansible et les
> scripts de `scripts/`. Installation : [`setup.md`](setup.md).

## Conventions

| Convention | Sens |
|---|---|
| `make <sujet>-plan` | compare le réel à ce que le plan dérive ; **n'écrit rien** |
| `make <sujet>-appliquer CONFIRMER=true` | réconcilie ; sans `CONFIRMER=true`, refuse |
| `make <sujet>-verifier` | contrôle ; n'écrit rien (la plupart lisent le dépôt seul) |
| `make <sujet>-etat`, `-mesurer`, `-recenser` | regarde le réel ; ne corrige rien |
| `DESTRUCTIF` dans l'aide | exige `CONFIRMER=true` **et** le nom de la cible (`INSTANCE=`, `SITE=`) |
| `FORCE=1` | passe outre le diff de `instancier-appliquer` ; première génération seulement |
| `MODE_CHECK=1` | `deployer-tout` en essai à blanc (`--check`) |
| `ARGS="…"` | arguments passés tels quels au script ou au playbook (ex. `ARGS=--check`) |

`make` seul (ou `make aide`) affiche l'aide détaillée. L'aide de chaque cible (`## …` dans
le `Makefile`) est la source des tableaux ci-dessous ; une preuve exige que chaque cible
publique y figure.

**Sortie d'Ansible.** Ansible exige une sortie bloquante : depuis un shell non interactif,
toujours `set -o pipefail; make … < /dev/null 2>&1 | cat`. Sans tube, l'échec est silencieux.

## Variables de `make`

| Variable | Sens | Cibles |
|---|---|---|
| `HOTE` | une VM, par son nom court | `deployer`, `creer-vm`, `hote-afficher`, … |
| `GROUPE` | un groupe Ansible (= un playbook de `playbooks/groupes/`) | `deployer-groupe`, `appliquer`, `site-appliquer` |
| `TENANT` | le dépôt d'un locataire (`OPS-X`) vu depuis le site | `locataire-creer`, `inseminer`, `placement-plan`, … |
| `INSTANCE` | le nom court d'un écosystème, exigé par les cibles destructives | `raser`, `locataire-raser`, `parefeu-*-flotte` |
| `SITE` | le dépôt d'un site, exigé par `site-raser` | `site-raser` |
| `CONFIRMER` | `true` pour écrire | toute cible `-appliquer` ou destructive |
| `LIMITE` | motif d'hôtes Ansible | `faits`, `verifier-hote` |
| `VERS` | un répertoire de destination (support externe) | `cles-exporter`, `voutes-exporter`, `remise-paquet`, … |
| `DEPOT` | un seul dépôt du génome | `publier`, `genome-pousser` |
| `PARALLELE` | nombre de VM créées à la fois | `flotte-creer`, `locataire-creer` |
| `NOM`, `MODELE`, `INDEX` | nouvel écosystème | `instance-creer`, `instance-utiliser`, `model-creer` |
| `DIALECTE` | CLI du commutateur (`cisco`, `binardat`) | `devis-reseau` |

## Variables d'environnement

| Variable | Sens | Défaut |
|---|---|---|
| `SETOPS_INSTANCE` | dépôt du locataire visé | `instance` (le lien) |
| `SETOPS_UNDERLAY` | underlay du site visé | `underlay.yml` (le lien) |
| `SETOPS_INVENTAIRE` | inventaire de l'instance ; exporté par le `Makefile` | `principal`, puis `production` |
| `ANSIBLE_VAULT_IDENTITY_LIST` | les clés de toutes les voûtes ; construit par `scripts/voutes.py` | dérivé de `~/.config/setops-vault-*` |
| `SETOPS_PROXMOX_API` | `hote:port` de l'API Proxmox le temps d'une commande (par un rebond) | l'adresse de la carte |
| `SETOPS_SSH_KEY` | clé SSH vers les nœuds Proxmox | l'agent SSH |
| `SETOPS_MODELES` | dossiers de modèles en plus de `exemples/modeles/` | — |
| `SETOPS_DIALECTE` | CLI du commutateur pour `devis-reseau` | `dialecte` de l'underlay |
| `SETOPS_FORGE_URL` | adresse de la forge pour `forge_cles.py` | — |
| `SETOPS_FORGE_MDP`, `FORGEJO_ADMIN` | mot de passe d'administration de la forge, depuis la voûte, le temps d'une commande | — |

Viser un autre site ou un autre locataire sans toucher aux liens :

```bash
SETOPS_UNDERLAY=../SITE-Technolibre/underlay.yml make frontiere-plan
SETOPS_INSTANCE=../OPS-Chezlepro make instancier
```

## Flux de travail courants

```bash
# Modifier l'écosystème
$EDITOR instance/plan/applications.yml
make instancier && make instancier-appliquer && make deployer HOTE=<vm>

# Contrôler une couche d'infrastructure, puis la réconcilier
make frontiere-plan
make frontiere-appliquer CONFIRMER=true

# Publier le moteur et les plans vers les forges
make publier
make wiki-publier WIKI_REMOTE=<url>.wiki.git
```

## Scripts appelés directement

Les cibles `make` couvrent l'exploitation. Quelques scripts s'utilisent aussi seuls ; chacun
documente ses options (`--help`) dans sa docstring.

| Script | Usage |
|---|---|
| `scripts/voutes.py etat` | les voûtes et leurs clés, vues par le moteur |
| `scripts/contexte.py` | le contexte actif (site, locataire) et ce que dit chaque indice |
| `scripts/orchestrer.py ordre` | l'ordre de déploiement des groupes |
| `scripts/dnssec.py generer <zone>` | crée la clé DNSSEC d'une zone, dans la voûte du locataire |
| `scripts/vpn_admin.py cle-appareil`, `config` | un appareil dans le tunnel des administrateurs |
| `scripts/dns_bascule.py --serveur <ip>` | le devis de bascule DNS contre un serveur précis |

## Commandes

### Vérifier et prouver

| Commande | Effet |
|---|---|
| `make aide` | Affiche l'aide detaillee du moteur (au-dela de cette liste) |
| `make verifier` | Rejoue les preuves SANS reecrire le rapport (verification rapide) |
| `make prouver` | Execute les preuves et ecrit docs/audit/preuve-<date>.md |
| `make test` | Lance les tests unitaires (derivation de nomenclature et d'inventaire) |
| `make lint` | Passe ansible-lint sur tout le depot |
| `make syntaxe` | Verifie la syntaxe de TOUS les playbooks (modele, hote, groupes, proxmox) |
| `make syntaxe-modele` | Verifie la syntaxe du playbook de preparation du gabarit dore |
| `make syntaxe-verification-modele` | Verifie la syntaxe du playbook de verification du gabarit |
| `make syntaxe-nettoyage` | Verifie la syntaxe du playbook de nettoyage du gabarit |
| `make syntaxe-verification-hote` | Verifie la syntaxe du playbook de verification d'hote |
| `make syntaxe-groupes` | Verifie la syntaxe de TOUS les playbooks de groupe (playbooks/groupes/*.yml) |
| `make syntaxe-proxmox` | Verifie la syntaxe du playbook de clonage de VM |
| `make ci` | Verifie le depot comme la CI : modele public monte a l'ecart, sans toucher ton instance |
| `make inventaire-verifier` | Verifie que l'inventaire se parse (voute dechiffree) |
| `make serveurs-verifier` | Valide le registre des serveurs |
| `make bases-verifier` | Valide le registre des bases de donnees |
| `make domaines-verifier` | Valide le registre des domaines |
| `make applications-verifier` | Valide le registre des applications |
| `make ports-verifier` | Deux roles co-localises revendiquent-ils le meme port ? (lecture seule) |
| `make intrants-verifier` | Tout intrant qu'un role EXIGE est-il fourni par l'instance ? (lecture seule) |
| `make site-verifier` | Verifie que playbooks/site.yml correspond aux couches declarees |
| `make flux-verifier` | Verifie que le registre des flux correspond aux meta/flux.yml des roles |
| `make schema` | Regenere docs/audit/schema-plan.json depuis les registres et les validateurs |
| `make plan-recette` | Regenere docs/audit/plan-de-recette.md depuis le wiki |
| `make sonder` | Sonde une cible et DIT ce qui distingue — CIBLE=<hote\|ip> [PORTS="22 443"] |
| `make valider` | Passe la recette de validation sur la flotte |

### Instances et modèles

| Commande | Effet |
|---|---|
| `make instance-modeles` | Liste les modeles d'ecosysteme disponibles |
| `make instance-creer` | Cree un nouvel ecosysteme depuis un modele — NOM=<nom> MODELE=<modele> |
| `make instance-utiliser` | Bascule l'instance active (symlink instance/) vers un dossier frere — NOM=<dossier> |
| `make instance-courante` | Affiche vers quel ecosysteme pointe l'instance active |
| `make instances` | Liste les ecosystemes decouverts (dossiers freres) et signale les collisions d'index |
| `make model-creer` | Cree un modele d'ecosysteme — MODE=<mode> NOM=<nom> |
| `make genome` | Les depots requis a la reproduction de cet ecosysteme, et leur etat |
| `make genome-inscrire` | Inscrit la parente dans l'instance (instance/parente.yml) |
| `make genome-verifier` | La parente inscrite tient-elle encore ? (code de sortie) |

### Plan et inventaire

| Commande | Effet |
|---|---|
| `make config` | Affiche la configuration Proxmox lue par le moteur |
| `make inventaire-ui` | Ouvre la console d'exploitation (GUI web) sur l'inventaire actif |
| `make instancier` | Genere hosts.yml depuis le plan (sans l'appliquer) |
| `make instancier-appliquer` | Applique l'inventaire genere — FORCE=1 pour passer outre le diff |
| `make serveurs` | Liste les serveurs declares au plan |
| `make serveurs-bootstrap` | REPRISE : (re)constitue plan/serveurs.yml depuis un inventaire existant |
| `make bases` | Liste les bases de donnees declarees au plan |
| `make domaines` | Liste les domaines declares au plan |
| `make applications` | Liste les applications declarees au plan |
| `make applications-bootstrap` | Amorce les applications declarees au plan |
| `make hote-afficher` | Affiche tout ce que le plan derive pour un hote — HOTE=<nom> |
| `make inventaire` | Verifie l'inventaire et en affiche le graphe (lab puis production) |
| `make inventaire-lister` | Affiche l'inventaire complet (JSON) |
| `make inventaire-graphe` | Affiche le graphe des groupes de l'inventaire |
| `make inventaire-hote` | Affiche les variables derivees d'un hote — HOTE=<nom> |
| `make inventaire-lab` | Affiche le graphe de l'inventaire de laboratoire |
| `make inventaire-production` | Affiche le graphe de l'inventaire de production |

### Gabarit et VM

| Commande | Effet |
|---|---|
| `make preparer-modele` | Prepare le gabarit dore (VM de reference clonee pour chaque hote) |
| `make verifier-modele` | Verifie le gabarit dore |
| `make nettoyer-modele` | Nettoie le gabarit avant capture — exige CONFIRMER=true |
| `make cloner-vm` | Clone une VM depuis le gabarit dore — HOTE=<nom> VMID=<id> |
| `make creer-vm` | Cree une VM et attend qu'elle soit joignable — HOTE=<nom> [TENANT=<depot>] |
| `make flotte-creer` | Cree les VM manquantes de la flotte depuis le plan — PARALLELE=n |
| `make raser` | DESTRUCTIF : detruit les VM derivees du plan — exige CONFIRMER=true ET INSTANCE=<nom> [TENANT=<depot>] |
| `make reconstruire` | Reconstruit un ecosysteme depuis zero : VM puis deploiement complet |
| `make myDay` | Alias strict de `reconstruire` (meme cible, memes gardes) |
| `make monter-flotte` | Monte une flotte deja creee : flux, AC et DNS, tout le reste, recette — CONFIRMER=true |
| `make reconstruire-locataire` | Rase et reconstruit un locataire, du site a la recette, etat remis — TENANT=OPS-X CONFIRMER=true |

### Déployer

| Commande | Effet |
|---|---|
| `make ansible-runtime` | Prepare le repertoire temporaire local d'Ansible (prerequis interne des cibles qui deploient) |
| `make site` | Regenere playbooks/site.yml depuis les couches et le graphe de dependances |
| `make appliquer` | Applique un groupe a la flotte — GROUPE=<groupe> |
| `make deployer` | Deploie un hote, couche par couche, dans l'ordre du graphe — HOTE=<nom> |
| `make deployer-groupe` | Deploie un seul groupe sur toute la flotte — GROUPE=<groupe> |
| `make deployer-tout` | Deploie TOUTE la flotte dans l'ordre des couches |
| `make verifier-deploiement` | Verifie l'etat de la flotte apres deploiement |
| `make verifier-hote` | Passe le playbook de verification sur un hote |
| `make faits` | Interroge les faits Ansible de la flotte — LIMITE=<motif> |
| `make cacher-paquets` | Tire les paquets NON DEBIAN dans le cache du controleur (a faire en ligne) |

### Réseau : flux, frontière, SDN, pare-feu

| Commande | Effet |
|---|---|
| `make flux` | Regenere le registre des flux et les regles nftables depuis les meta/flux.yml |
| `make devis-reseau` | Devis switch (VLANs/SVIs/ACLs) du reseau converge, derive des nomenclatures. DIALECTE=cisco\|binardat |
| `make devis-opnsense` | Devis OPNsense (frontiere nord/sud), derive du registre des flux (pair: externe) |
| `make devis-opnsense-verifier` | Verifie le devis de la frontiere nord/sud (aucune ecriture) |
| `make frontiere-plan` | Ecart entre la frontiere OPNsense et son devis (aucune ecriture) |
| `make frontiere-appliquer` | Reconcilie la frontiere : cree ce qui manque, RETIRE ce qui est perime. CONFIRMER=true |
| `make frontiere-mesurer` | La frontiere refuse-t-elle ce qui n'est pas declare ? (sonde reelle, aucune ecriture) |
| `make devis-proxmox-fw` | Devis pare-feu Proxmox (est-ouest intra-tenant), derive du registre des flux |
| `make devis-proxmox-fw-verifier` | Verifie le devis du pare-feu est-ouest Proxmox (aucune ecriture) |
| `make proxmox-fw-plan` | Ecart entre le pare-feu est-ouest Proxmox et son devis (aucune ecriture) — ARGS="--objets-seulement" ou "--vm <vmid>" |
| `make proxmox-fw-appliquer` | Reconcilie le pare-feu est-ouest : IPSets, groupes, affectations. CONFIRMER=true |
| `make proxmox-fw-eprouver` | Verifie qu'activer le pare-feu d'UNE VM ne coupe rien (aucune ecriture) — TENANT=<OPS-X> HOTE=<vm> |
| `make proxmox-fw-activer-vm` | Active le pare-feu d'UNE VM en le prouvant avant/apres — TENANT= HOTE= CONFIRMER=true |
| `make parefeu-verifier-flotte` | La sonde `connectivite` est-elle saine sur chaque VM (prealable a l'activation) — INSTANCE=OPS-X |
| `make parefeu-activer-flotte` | Active le pare-feu Proxmox de toutes les VM, juge par la sonde `connectivite` — INSTANCE=OPS-X CONFIRMER=true |
| `make devis-sdn` | Devis SDN EVPN (zone + VNets + sous-reseaux par tenant), derive du seed |
| `make devis-sdn-verifier` | Verifie le devis SDN EVPN — zones, VNets, sous-reseaux (aucune ecriture) |
| `make sdn-plan` | Ecart entre le SDN EVPN (+ sortie des VRF) et son devis (aucune ecriture) |
| `make sdn-appliquer` | Reconcilie le SDN : cree ce qui manque, RETIRE ce qui est perime. CONFIRMER=true |
| `make devis-proxmox-pools` | Devis des pools Proxmox (un par tenant), derive du plan |
| `make devis-proxmox-pools-verifier` | Verifie le devis des pools Proxmox (aucune ecriture) |
| `make placement-plan` | Le noeud, stockage, pont et gabarit du tenant existent-ils sur ce cluster ? (aucune ecriture) [TENANT=<depot>] |
| `make underlay` | Underlay (fabric physique cluster-global : mgmt/iSCSI/Ceph) : affiche + valide (P23) |
| `make underlay-plan` | Confronte l'underlay DECLARE au reel (API du cluster + sonde TCP) — n'ecrit rien |
| `make mtu-mesurer` | L'invite porte-t-il le MTU de sa zone SDN ? (aucune ecriture) |
| `make routes-fabric-etat` | Les hyperviseurs routent-ils toutes les zones du SITE ? — ne corrige rien |
| `make vpn-admin-plan` | Acces WireGuard des admins : ce que la frontiere porte face au plan (aucune ecriture) |
| `make vpn-admin-appliquer` | Pose l'instance et les pairs declares, retire ceux qui ne le sont plus — CONFIRMER=true |

### Devis de service

| Commande | Effet |
|---|---|
| `make identite-plan` | Ecart entre l'identite deployee et ce que le plan derive (aucune ecriture) |
| `make certificats-plan` | Ecart entre les certificats sur disque et ceux reellement servis (aucune ecriture) |
| `make expositions-plan` | Chaque exposition du plan repond-elle ? (edge et poste, aucune ecriture) |
| `make expositions-etat` | Chaque exposition est-elle servie sous un certificat qui la porte ? — ne corrige rien |
| `make postgresql-plan` | Chiffrement impose et portee des acces PostgreSQL (aucune ecriture) |
| `make courriel-plan` | Chaine Postfix -> LDAP -> Dovecot -> IMAP (aucune ecriture) |
| `make versions-mesurer` | De combien nos epinglages ont-ils vieilli ? (interroge les amonts, aucune ecriture) |

### PKI et DNS

| Commande | Effet |
|---|---|
| `make ca-racine` | Recupere la racine de l'AC interne + son empreinte (a verifier AVANT de l'installer) |
| `make ca-empreinte` | Empreinte de la racine, lue SUR l'AC (le temoin de comparaison) |
| `make dnssec-ds` | DS a remettre au registraire, calcules depuis la voute du locataire (aucune ecriture) |
| `make dnssec-verifier` | Cle en voute pour chaque zone signee, et DS du registre conforme ? (aucune ecriture) |
| `make dns-bascule-devis` | Basculer nos serveurs de noms changerait-il quelque chose ? Plan contre DNS en service (aucune ecriture) |

### Site et locataires

| Commande | Effet |
|---|---|
| `make site-intrants` | Les intrants que le SITE monte expose a ses locataires (derives) |
| `make site-intrants-verifier` | Le locataire monte suit-il encore son site ? (aucune ecriture) |
| `make face-reseau-publier` | Chaque locataire publie sa face reseau pour son site (a commiter chez lui, apres `make flux`) |
| `make fiches-site-deposer` | Le site depose chez chacun de ses locataires la fiche qu'il lui destine (a commiter chez eux) |
| `make site-decrire` | Les machines de l'hebergeur declarees dans l'underlay |
| `make site-inventaire` | L'inventaire dynamique du site, tel qu'Ansible le voit |
| `make site-appliquer` | Applique un role aux machines du site — GROUPE=<serveur_ops_site\|...> |
| `make site-deployer-tout` | Deploie TOUT le site dans l'ordre des couches — CONFIRMER=true |
| `make site-creer` | Cree les machines du site depuis l'underlay — CONFIRMER=true |
| `make site-raser` | DESTRUCTIF : detruit les VM du SITE — CONFIRMER=true ET SITE=<depot> |
| `make locataire-creer` | Le SITE cree les VM d'un locataire d'apres sa face reseau — TENANT=<depot> CONFIRMER=true [PARALLELE=n] |
| `make locataire-raser` | DESTRUCTIF : le SITE rase les VM d'un locataire d'apres sa face reseau — TENANT=<depot> CONFIRMER=true INSTANCE=<nom court> [HOTE=h] |
| `make gabarit-etat` | Le gabarit porte-t-il ce que le SITE declare ? — ne corrige rien, regarde |
| `make inseminer` | Le SITE amorce le runner d'un tenant — TENANT=<dossier> [HOTE=<nom>] |
| `make emancipation-prouver` | Prouve qu un lien est coupe — SERVICE=<artefacts\|genome\|resolveur> [HOTE=] CONFIRMER=true |

### Génome, forge, publication

| Commande | Effet |
|---|---|
| `make publier` | Publie le genome d'un geste : eregion PUIS la forge du site, et le verifie — DEPOT=<nom> pour un seul |
| `make genome-pousser` | Le runner du site pousse le genome sur la forge du site — DEPOT=<nom> pour un seul |
| `make genome-etat` | Ce que la forge du site porte, face au poste — ne corrige rien, regarde |
| `make forge-amorcer` | Amorce la forge d'un SITE neuf avec le genome — CONFIRMER=true |
| `make forge-cles` | Le site enregistre sur le depot de chaque locataire la cle de lecture que sa face publie — CONFIRMER=true pour ecrire |
| `make forge-comptes` | Les comptes de la forge du site : un par mainteneur (plan du site), et le lecteur de la console — CONFIRMER=true pour ecrire |
| `make forge-etancheite` | La forge du site laisse-t-elle chaque runner lire ses depots, et personne d'autre ? (mesure, aucune ecriture) |
| `make depots-perimes` | Depots qu'un runner ne declare plus : regarde, et retire avec CONFIRMER=true |
| `make wiki-publier` | Publie le wiki (wiki/) vers la forge |
| `make fiches` | Regenere la fiche de chaque role (docs/roles/) — ROLE=<nom> pour une seule |

### Sauvegardes et état

| Commande | Effet |
|---|---|
| `make sauvegarder-maintenant` | Depose l'etat de chaque noeud TOUT DE SUITE (avant de raser) — HOTE=<hote> optionnel |
| `make restauration-etat` | Ce qui attend dans le depot, et ce que chaque jeu est devenu — HOTE=<hote> optionnel |
| `make temoins-etat` | L'etat vivant est-il celui d'avant le rasage ? (lecture seule) — HOTE= SOURCE=candidat optionnels |
| `make restauration-renoncer` | Ecarte l'etat anterieur d'un jeu, sans le remettre — HOTE= JEU= CONFIRMER=true |
| `make depot-hors-site` | Copie le depot de sauvegarde du site HORS du site — VERS=<repertoire> |

### Clés et voûtes

| Commande | Effet |
|---|---|
| `make cles-recenser` | Montre ce qui n'existe QUE sur ce poste (sans rien ecrire) |
| `make voutes-recenser` | Montre les voutes de ce poste (gitignorees : sur aucune forge), sans rien ecrire |
| `make voutes-exporter` | Sort les voutes (deja chiffrees) vers un support, relues — VERS=<repertoire> NOM=<base> |
| `make cles-exporter` | Sort les cles du poste, chiffrees et relues — VERS=<repertoire> |
| `make cles-compagnons` | Depose le script de restauration sur une cle DEJA faite — VERS=<repertoire> |
| `make cles-restaurer` | Remet les cles en place depuis une archive — ARCHIVE=<fichier> |

### Remise au client

| Commande | Effet |
|---|---|
| `make remise-recenser` | Ce qu'une remise au client emporterait, sans rien ecrire |
| `make remise-paquet` | Temps 1 : fabrique le paquet de remise, chiffre et relu — VERS=<repertoire> |
| `make remise-inscrire` | Inscrit la remise chez le locataire — RECU_PAR="…" COURRIEL="…" [DANS=30] |
| `make remise-verifier` | Etat de la remise : temps 1 fait ? temps 2 du, ou echu ? |
| `make remise-recleer` | Temps 2 : mesure la revocation reelle, puis estampille — CONFIRMER=true |