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.

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 :

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

Flux de travail courants

# 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-.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= MODELE=
make instance-utiliser	Bascule l'instance active (symlink instance/) vers un dossier frere — NOM=
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= 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=
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=
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= VMID=
make creer-vm	Cree une VM et attend qu'elle soit joignable — HOTE= [TENANT=]
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= [TENANT=]
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=
make deployer	Deploie un hote, couche par couche, dans l'ordre du graphe — HOTE=
make deployer-groupe	Deploie un seul groupe sur toute la flotte — 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=
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 "
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= HOTE=
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=]
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=
make locataire-creer	Le SITE cree les VM d'un locataire d'apres sa face reseau — TENANT= CONFIRMER=true [PARALLELE=n]
make locataire-raser	DESTRUCTIF : le SITE rase les VM d'un locataire d'apres sa face reseau — TENANT= CONFIRMER=true INSTANCE= [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= [HOTE=]
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= pour un seul
make genome-pousser	Le runner du site pousse le genome sur la forge du site — DEPOT= 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= pour une seule

Sauvegardes et état

Commande	Effet
make sauvegarder-maintenant	Depose l'etat de chaque noeud TOUT DE SUITE (avant de raser) — HOTE= optionnel
make restauration-etat	Ce qui attend dans le depot, et ce que chaque jeu est devenu — 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=

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= NOM=
make cles-exporter	Sort les cles du poste, chiffrees et relues — VERS=
make cles-compagnons	Depose le script de restauration sur une cle DEJA faite — VERS=
make cles-restaurer	Remet les cles en place depuis une archive — ARCHIVE=

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=
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