Set-OPS-Public/docs/setup.md

Installation et configuration

Pour qui : l'exploitant qui monte son premier écosystème sur une grappe Proxmox. Le résumé est dans le README ; ce document donne chaque étape, ses fichiers et ses pièges. Préparer le matériel d'un hébergeur est un autre parcours : hebergement/preparer-un-site-hebergeur.md.

Prérequis

Quoi	Détail
Grappe Proxmox	droits d'administration, API joignable depuis le poste
Jeton d'API Proxmox	utilisateur ansible@pve ou équivalent
Poste de pilotage	Linux, Python 3, Ansible, make, git ; node optionnel (garde JS du GUI)
Paire de clés SSH	la publique est injectée dans les VM par cloud-init
Phrase de passe de voûte	une par écosystème

1. Cloner le moteur

git clone <url-de-Set-OPS> Set-OPS && cd Set-OPS

2. Créer l'instance

Une instance est un dépôt frère du moteur, créé depuis un modèle. Le dépôt public fournit socle : PKI (step-ca), DNS interne (PowerDNS), edge TLS (nginx), magasin de courriel (Dovecot). Les modèles assemblés par offre sont dans le dépôt privé Set-OPS-modeles (SETOPS_MODELES les rend visibles).

make instance-modeles                          # modèles disponibles
make instance-creer NOM=OPS-MonOrg MODELE=socle   # crée ../OPS-MonOrg ; INDEX=<n> fixe le seed
ln -s ../OPS-MonOrg instance                   # l'instance active (ou : make instance-utiliser NOM=OPS-MonOrg)
make instances                                 # écosystèmes découverts, collisions d'index

instance-creer refuse un index déjà pris par un écosystème voisin : tout l'adressage en dérive. Il ne bascule pas le lien instance/ et ne fait pas git init.

3. Renseigner l'instance

<inventaire> est principal ou, à défaut, production (le nom que porte le modèle).

Fichier	Valeur
instance/inventories/<inventaire>/group_vars/all/10-intrants.yml	domaine_interne (ex. monorg.internal)
instance/plan/nomenclature.yml	index (seed) et supernet
instance/plan/domaines.yml	domaine public, autorite, edge
instance/plan/serveurs.yml	placement Proxmox : nœud, stockage, disque, mémoire, cœurs

Le GUI (make inventaire-ui) édite les mêmes registres. Valeurs communes : conception/intrants-communs.md.

4. Proxmox

make config      # API, nœud, stockage, VMID et nom du gabarit

Chaque paramètre : exploitation/config-proxmox.md. Les identifiants Proxmox appartiennent à l'hébergeur : ils vivent dans sa voûte (celle de l'underlay), pas dans celle du locataire.

5. Voûtes et clés

Une voûte par dépôt, chiffrée par ansible-vault, depuis le gabarit exemples/vault.exemple.yml : instance/inventories/<inventaire>/group_vars/all/vault.yml.

Une clé par voûte, dans un fichier nommé d'après le dossier de l'écosystème, en minuscules :

install -m 600 /dev/null ~/.config/setops-vault-ops-monorg
$EDITOR ~/.config/setops-vault-ops-monorg      # la phrase de passe, une ligne
python3 scripts/voutes.py etat                  # le moteur trouve-t-il chaque clé ?

Rien à exporter : le Makefile construit ANSIBLE_VAULT_IDENTITY_LIST avec scripts/voutes.py. Créer une VM ouvre deux voûtes dans la même exécution (locataire et hébergeur) : un seul ANSIBLE_VAULT_PASSWORD_FILE ne suffit pas.

Les clés n'existent que sur le poste. Les sortir sur un support chiffré : exploitation/sortir-les-cles-du-poste.md.

6. Gabarit Debian 13 (une fois par grappe)

Créer une VM Debian 13 minimale, joignable par SSH avec clé, puis :

make preparer-modele
make verifier-modele
make nettoyer-modele CONFIRMER=true

Convertir la VM en gabarit Proxmox sous le nom enregistré par make config (proxmox_clone_source_nom, modeleSetOPS par défaut). Un autre nom fait échouer le clonage. Machine q35/OVMF : ne jamais convertir depuis i440fx.

Procédure : exploitation/procedure-template-debian13-proxmox.md ; contenu justifié : exploitation/gabarit-debian13-justification.md.

7. Générer l'inventaire

make instancier                    # ce que le plan produit, en diff
make instancier-appliquer FORCE=1  # première génération seulement
make serveurs                      # VMID / IP dérivés

Les hôtes naissent en etat: planifie.

8. Créer et déployer

make creer-vm HOTE=infra-dns-01          # clone + cloud-init, attend que la VM réponde
# passer l'hôte en etat: actif dans instance/plan/serveurs.yml, puis :
make instancier-appliquer
make deployer HOTE=infra-dns-01          # couche par couche, dans l'ordre du graphe

Toute la flotte : make flotte-creer CONFIRMER=true puis make deployer-tout CONFIRMER=true, ou make reconstruire CONFIRMER=true (créer puis déployer). Les déploiements ne visent que les hôtes actifs.

9. Vérifier

make inventaire-verifier   # registres, inventaire, gardes
make verifier              # lint, tests, inventaire, ordre, flux, syntaxe, puis les preuves
make valider               # recette sur la flotte déployée

Configuration de référence

Élément	Rôle	Défaut
instance/	lien vers le dépôt du locataire actif	—
underlay.yml	lien vers l'underlay du site actif	underlay.yml à la racine
ansible.cfg	configuration Ansible du moteur	dans le dépôt
.ansible/	répertoires temporaires d'Ansible	créé par make

Variables d'environnement et de make : usage.md.

Pannes connues au premier montage

Symptôme	Cause	Remède
Attempting to decrypt but no vault secrets found	clé de voûte absente ou mal nommée	étape 5, python3 scripts/voutes.py etat
make instancier-appliquer refuse d'écrire	diff non vide, première génération	FORCE=1 la première fois seulement
le clonage ne trouve pas sa source	nom du gabarit ≠ proxmox_clone_source_nom	renommer le gabarit ou refaire make config
une sortie d'Ansible vide, sans erreur	Ansible exige un tube sur sa sortie	set -o pipefail; make … < /dev/null 2>&1 | cat