Set-OPS-Public/docs/procedure-template-debian13-proxmox.md

Procédure manuelle — VM Debian 13 vanille pour Proxmox

Pour qui : l'exploitant qui fabrique le gabarit d'or à la main, une fois.

Objet du document

Ce document décrit le travail manuel à effectuer pour créer une VM Debian 13 vanille dans Proxmox, jusqu’au moment où elle peut être prise en charge par Set-OPS.

Le résultat attendu est une VM minimale, sobre, joignable en SSH, capable d'installer des paquets depuis les dépôts Debian, compatible avec cloud-init et prête à recevoir le playbook de préparation du golden template.

Ce document s’arrête au point de bascule vers le Makefile.

Les ajouts appliqués ensuite par Ansible, leur validation et leur justification sont documentés dans :

docs/modeles_vm/debian13-proxmox.md

---

1. Objectif du modèle

Le modèle Debian 13 doit servir de base commune pour les futurs serveurs de l_instance

Objectifs :

• système Debian 13 minimal ;
• aucun environnement graphique ;
• SSH actif ;
• qemu-guest-agent installé ;
• cloud-init installé ;
• disque CloudInit Proxmox attaché ;
• compte technique ansible injecté par cloud-init ;
• clé publique SSH injectée par cloud-init ;
• ansible autorisé à utiliser sudo ;
• partitionnement simple et agrandissable ;
• aucune partition swap bloquant la croissance du disque ;
• aucune donnée propre à une VM finale ;
• aucune clé privée ;
• aucun secret ;
• prêt à être converti en template Proxmox.

---

2. Création de la VM dans Proxmox

Paramètres généraux

Créer une nouvelle VM dans Proxmox avec des paramètres sobres.

Exemple :

Nom de la VM : modeleSetOPS      ← voir l'encadré : ce nom N'EST PAS libre
VMID         : 9000 ou autre ID réservé aux modèles
OS           : Debian 13
BIOS         : OVMF / UEFI
Machine      : q35

Le nom du modèle est un contrat, pas une étiquette. Le clonage cherche sa source par ce nom : il doit être exactement celui que make config a enregistré sous proxmox_clone_source_nom — modeleSetOPS par défaut. Un nom qui ne correspond pas se solde par un clonage qui ne trouve rien, et le message ne dit pas que c'est le nom qui est en cause. (Cette procédure proposait debian13-template jusqu'au 2026-09-06 : suivie à la lettre, elle produisait un gabarit que le moteur ne savait pas cloner.)

Le VMID, lui, est libre — c'est proxmox_clone_vmid_modele qui le retient.

q35 n'est pas un réglage — c'est la raison de cette procédure

Ces deux lignes sont pourquoi l'installation est manuelle. Elles expliquent aussi pourquoi Set-OPS n'utilise pas l'image cloud officielle de Debian.

genericcloud est livrée configurée pour i440fx, le défaut de Proxmox. La convertir en q35 après coup ne change pas un paramètre : ça remplace le matériel virtuel sous un système qui croit connaître le sien. i440fx est un chipset PCI, q35 est PCIe — la topologie des bus change, donc :

• les noms d'interfaces prédictibles changent, puisqu'ils dérivent du chemin PCI (enp0s3 devient enp1s0) — la machine perd le réseau, et sa configuration réseau désigne une interface qui n'existe plus ;
• les chemins de disques bougent, ce qui peut valoir un initramfs qui ne trouve plus sa racine ;
• l'ordre d'énumération des périphériques n'est plus le même, et ce qui en dépend suit.

Constat de l'exploitant, paye en anomalies : une conversion i440fx → q35 sur une machine déjà installée produit une série de pannes dont chacune ressemble à autre chose qu'à sa cause. La conversion n'est pas une correction — c'est une transplantation.

D'où la règle : une machine naît q35, ou elle ne le sera jamais proprement. C'est ce que cette installation depuis l'ISO garantit, et ce qu'une image préconfigurée pour i440fx interdit.

Le gabarit hérite ces valeurs à chaque clonage — le vérifier avant de le convertir en modèle est le dernier moment où la correction est gratuite :

qm config <vmid> | grep -E '^machine|^bios'
# attendu : machine: q35   /   bios: ovmf

Disque EFI Proxmox

Avec OVMF/UEFI, Proxmox crée un petit disque EFI, par exemple :

efidisk0 : 4 Mo

Ce disque ne remplace pas la partition EFI de Debian.

Il sert à conserver les variables du firmware UEFI virtuel :

• ordre de démarrage ;
• entrées de boot ;
• variables UEFI ;
• paramètres liés à Secure Boot, si utilisé.

Il faut le garder.

---

3. Disque virtuel principal

Type de disque

Pour une VM Linux moderne :

Bus/Device      : SCSI
SCSI Controller : VirtIO SCSI single
IO thread       : activé si disponible
Cache           : Default / No cache
Discard         : selon stockage, seulement si pertinent
SSD emulation   : oui si le stockage est réellement SSD/NVMe

Même si le stockage réel est sur un stockage réseau iSCSI, le disque présenté à la VM doit rester :

SCSI via VirtIO SCSI single

Le choix SCSI ici concerne le bus virtuel vu par la VM, pas le protocole réel entre Proxmox et le stockage.

Taille du disque

Pour le modèle de base :

Disque : 16 Go

C’est suffisant pour une base Debian minimale.

Des clones pourront ensuite être agrandis avant le premier démarrage cloud-init.

---

4. Processeur

Pour un modèle portable entre plusieurs hôtes Proxmox :

CPU Type : x86-64-v2-AES
Sockets  : 1
Cores    : 2

Éviter host pour un modèle générique, sauf si tous les nœuds Proxmox sont strictement homogènes et que la portabilité n’est pas une priorité.

---

5. Mémoire

Pour le modèle Debian 13 minimal :

Mémoire : 2048 MiB

Le ballooning peut être activé, mais si la VM n’a pas de swap, éviter de descendre trop bas.

Réglage prudent :

RAM max     : 2048 MiB
RAM minimum : 1536 MiB ou 2048 MiB

Pour un modèle simple, il est acceptable de laisser 2048 MiB fixe.

---

6. Carte graphique virtuelle

Pour un serveur Debian minimal :

Display : Default / Standard VGA

Ne pas installer d’environnement graphique.

SPICE et VirtIO-GPU ne sont pas nécessaires pour un modèle serveur administré par SSH et Ansible.

---

7. Installation Debian 13

Démarrer la VM sur l’ISO Debian 13.

L’option Graphical install est acceptable : elle ne signifie pas qu’un environnement graphique sera installé. Elle ne concerne que l’interface de l’installateur.

---

8. Partitionnement

Objectif

Le disque doit rester facile à agrandir après clonage.

Ne pas créer de partition swap à la fin du disque, car cela bloquerait l’agrandissement direct de la partition racine avec growpart.

Partitionnement recommandé

Utiliser un partitionnement manuel :

/dev/sda1   EFI System Partition   512 Mo   FAT32   /boot/efi
/dev/sda2   Linux root             reste    ext4    /

Ne pas créer :

partition swap
LVM
/home séparé
/var séparé

Pourquoi éviter LVM dans le modèle

Le stockage réel contient déjà plusieurs couches :

stockage ZFS
→ zvol iSCSI
→ Proxmox
→ disque virtuel
→ Debian

Ajouter LVM dans la VM complique le modèle sans bénéfice clair pour une base minimale.

Pourquoi éviter la partition swap

Un exemple à éviter :

/dev/sda1   EFI
/dev/sda2   /
/dev/sda3   swap

Si le disque est agrandi plus tard, l’espace libre sera après la swap. La partition / ne sera donc plus la dernière partition, ce qui complique ou empêche l’usage direct de :

growpart /dev/sda 2
resize2fs /dev/sda2

Swap

Pour le modèle :

Swap : aucun

L’avertissement de Debian au sujet de l’absence de swap peut être ignoré.

Si un clone a besoin de swap plus tard, utiliser plutôt :

• un swapfile ;
• ou un deuxième disque virtuel dédié au swap.

Exemple de swapfile futur :

sudo fallocate -l 1G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

---

9. Choix du noyau Debian

Si l’installateur demande quel noyau installer, choisir :

linux-image-amd64

Ne pas choisir une version fixe du noyau sauf besoin très particulier.

Le méta-paquet linux-image-amd64 suivra les mises à jour normales de Debian.

---

10. Image initrd

Si l’installateur demande le type d’image initrd, choisir :

image générique : comporte tous les pilotes disponibles

C’est le meilleur choix pour un modèle Proxmox, car la VM doit rester portable même si certains paramètres virtuels changent plus tard.

---

11. Sélection des logiciels Debian

Dans l’écran de sélection des logiciels, cocher seulement :

[x] serveur SSH
[x] utilitaires usuels du système

Laisser décoché :

[ ] environnement de bureau Debian
[ ] GNOME
[ ] KDE Plasma
[ ] XFCE
[ ] LXDE
[ ] LXQt
[ ] MATE
[ ] serveur web
[ ] serveur d’impression

Le serveur web, les rôles applicatifs et les services métier seront installés plus tard par Ansible.

---

12. Premier démarrage après installation

Après l’installation, démarrer la VM et se connecter en console ou par SSH.

Passer root si le compte root est disponible :

su -

ou, si sudo est déjà disponible :

sudo -i

Toutes les commandes de bootstrap suivantes sont exécutées dans la VM.

---

13. Réparer APT après installation DVD

Si Debian a été installé depuis l'ISO/DVD complet, APT peut garder une source cdrom:. Dans ce cas, apt update ou apt install échoue parce que le système cherche les paquets sur le média d'installation plutôt que sur les miroirs Debian.

Vérifier les sources :

grep -R "^[[:space:]]*deb cdrom:" /etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null || true

Si une ligne deb cdrom: est présente, la commenter ou la retirer.

Configuration simple attendue pour Debian 13 :

cat > /etc/apt/sources.list <<'EOF'
deb http://deb.debian.org/debian trixie main contrib non-free-firmware
deb http://security.debian.org/debian-security trixie-security main contrib non-free-firmware
deb http://deb.debian.org/debian trixie-updates main contrib non-free-firmware
EOF

Si l'installation a créé des fichiers .sources sous /etc/apt/sources.list.d/, vérifier qu'ils ne contredisent pas cette configuration et qu'ils ne pointent pas vers cdrom:.

Vérifier le réseau avant de continuer :

ip route
cat /etc/resolv.conf
ping -c 3 1.1.1.1
ping -c 3 deb.debian.org

Résultat attendu :

une route par défaut existe
un serveur DNS est configuré
le ping IP fonctionne
la résolution DNS fonctionne

---

14. Mise à jour du système

Exécuter :

apt update
apt full-upgrade -y

---

15. Paquets de bootstrap

Installer seulement les paquets nécessaires pour que Set-OPS puisse prendre le relais :

apt install -y \
  sudo \
  openssh-server \
  qemu-guest-agent \
  cloud-init \
  cloud-guest-utils \
  ca-certificates \
  curl \
  vim \
  nano

Rôle des paquets principaux :

sudo               : délégation administrative
openssh-server     : accès distant initial
qemu-guest-agent   : communication Proxmox ↔ VM
cloud-init         : personnalisation au premier boot du clone
cloud-guest-utils  : fournit notamment growpart

Les autres paquets communs, outils de diagnostic, chrony et composants de durcissement sont installés ensuite par make preparer-modele.

---

16. Activation du QEMU Guest Agent

Activer le service :

systemctl enable --now qemu-guest-agent

Vérifier :

systemctl status qemu-guest-agent --no-pager

Dans Proxmox, activer aussi :

VM → Options → QEMU Guest Agent → Enabled

---

17. Identité initiale par Cloud-Init

À partir d'ici, ne pas créer manuellement le compte ansible ni son fichier authorized_keys, sauf dépannage.

L'identité initiale doit venir de Proxmox + Cloud-Init :

Proxmox : ciuser, clé SSH, réseau, DNS
Debian  : cloud-init applique ces paramètres au démarrage
Ansible : configure ensuite le vrai socle du serveur

Cette séparation évite de maintenir deux méthodes concurrentes pour créer le même accès.

Ajouter le CloudInit Drive

Éteindre la VM :

shutdown -h now

Dans Proxmox :

VM → Hardware → Add → CloudInit Drive

Ou en ligne de commande Proxmox :

qm set VMID --ide2 STORAGE:cloudinit

Exemple :

qm set 9000 --ide2 local-lvm:cloudinit

Le nom exact du stockage dépend de la configuration Proxmox.

Définir les paramètres Cloud-Init du modèle

Pour la VM qui deviendra le modèle, utiliser une identité technique minimale, pas une identité de serveur final.

Exemple DHCP :

qm set 9000 --ciuser ansible
qm set 9000 --sshkeys ~/.ssh/id_ed25519.pub
qm set 9000 --ipconfig0 ip=dhcp

Exemple IP statique temporaire pour joindre la VM de modèle :

qm set 9000 --ciuser ansible
qm set 9000 --sshkeys ~/.ssh/id_ed25519.pub
qm set 9000 --ipconfig0 ip=10.0.99.99/24,gw=10.0.99.1
qm set 9000 --nameserver 10.0.99.1

Pour les clones, ces valeurs seront remplacées par l'identité réelle du serveur.

Réinitialiser l'état Cloud-Init avant le test

Comme cloud-init vient d'être installé après le premier démarrage Debian, nettoyer son état avant de tester l'injection Proxmox :

cloud-init clean --logs
reboot

Au redémarrage, cloud-init doit appliquer le ciuser, la clé SSH et les paramètres réseau.

---

18. SSH et sudo après Cloud-Init

Tester la connexion par clé

Depuis le poste d'administration :

ssh -o PreferredAuthentications=publickey ansible@IP_DE_LA_VM

Résultat attendu : la connexion fonctionne sans saisir le mot de passe du compte ansible.

Vérifier sudo

Tester :

sudo -v

sudo -n true && echo OK

Le résultat attendu est OK. Le flux make ne demande pas de mot de passe interactif.

Correction minimale si sudo manque

Si cloud-init a créé ansible sans privilège sudo, corriger seulement ce point depuis la console Proxmox ou un compte administrateur existant :

usermod -aG sudo ansible

Puis retester sudo -v avec le compte ansible.

Ne pas créer manuellement /home/ansible/.ssh/authorized_keys dans le flux normal. Si la clé ne fonctionne pas, corriger les paramètres Cloud-Init dans Proxmox, puis relancer :

cloud-init clean --logs
reboot

---

19. SSH durci attendu

Le modèle suppose que Cloud-Init injecte le ciuser et sa clé publique avant la prise en charge par Ansible.

L'exigence immédiate est que l'accès par clé fonctionne pour ansible.

L'état final sera appliqué et validé par Set-OPS :

PermitRootLogin no
PubkeyAuthentication yes
PasswordAuthentication no
AuthenticationMethods publickey

Ne pas lancer le playbook de préparation tant que l'accès SSH par clé ne fonctionne pas.

---

20. Vérifications avant passage à Set-OPS

Redémarrer la VM une dernière fois si nécessaire, puis vérifier :

lsblk
df -h
swapon --show
ip a
hostnamectl
timedatectl
systemctl status ssh --no-pager
systemctl status qemu-guest-agent --no-pager
cloud-init --version

État attendu :

/boot/efi présent
/ sur ext4
aucun swap actif
qemu-guest-agent actif
ssh actif
cloud-init installé
compte ansible fonctionnel
connexion SSH par clé fonctionnelle
sudo fonctionnel pour ansible
CloudInit Drive présent côté Proxmox

---

21. Point de bascule vers Set-OPS

À partir de ce point, ne pas continuer manuellement la configuration du socle. Utiliser le Makefile depuis le dépôt Set-OPS.

Depuis le poste Ansible :

make preparer-modele
make verifier-modele

Le cleanup final est séparé et protégé :

make nettoyer-modele CONFIRMER=true

Ne pas lancer le cleanup final tant que make verifier-modele n'a pas réussi.

---

22. Dépannage du bootstrap initial

Symptôme	Cause probable	Correction
apt install demande le DVD	Source APT cdrom: encore active.	Refaire la section 13 et relancer apt update.
Temporary failure resolving deb.debian.org	DNS absent ou incorrect.	Vérifier /etc/resolv.conf, Proxmox cloud-init DNS, passerelle et réseau.
Network is unreachable	Pas de route par défaut.	Vérifier l'IP, la passerelle et ip route.
SSH refuse la clé	Clé Cloud-Init absente, mauvais ciuser, ou cloud-init déjà initialisé avant l'ajout des paramètres.	Corriger les paramètres Proxmox, puis cloud-init clean --logs et redémarrer.
sudo: a password is required	Sudo NOPASSWD pas encore posé.	Corriger sudo NOPASSWD pour ansible, puis relancer make preparer-modele.
ansible is not in the sudoers file	Le compte a été créé par Cloud-Init sans privilège sudo.	Ajouter seulement ansible au groupe sudo, puis laisser Set-OPS gérer NOPASSWD.
Cloud-init sans effet	cloud-init absent au premier boot concerné, disque CloudInit absent, ou VM déjà initialisée.	Installer cloud-init, ajouter le CloudInit Drive, corriger les paramètres Proxmox, puis cloud-init clean --logs et redémarrer.

---

23. Nettoyage avant conversion en template

Le nettoyage est fait par Set-OPS, pas à la main, sauf diagnostic exceptionnel.

Commande attendue :

make nettoyer-modele CONFIRMER=true

Ce nettoyage peut inclure :

cloud-init clean --logs
nettoyage du cache APT
rotation ou purge contrôlée des journaux
remise à zéro de /etc/machine-id
suppression des historiques shell

---

24. Point d’arrêt : VM prête à convertir

À ce stade, la VM doit être arrêtée.

Elle est prête à être convertie en template Proxmox.

État attendu côté Proxmox :

VM arrêtée
BIOS OVMF / UEFI
Machine q35
EFI Disk présent
Disque principal SCSI / VirtIO SCSI single
CloudInit Drive présent
QEMU Guest Agent activé dans les options
CPU x86-64-v2-AES
RAM 2048 MiB
Aucun environnement graphique

État attendu côté Debian :

Debian 13 minimal
SSH installé
qemu-guest-agent installé
cloud-init installé
cloud-guest-utils installé
sudo installé
compte ansible injecté par cloud-init
clé publique SSH injectée par cloud-init
sudo NOPASSWD pour ansible après préparation Set-OPS
partition EFI 512 Mo
partition / ext4
aucune partition swap
aucun LVM
machine-id nettoyé
cloud-init nettoyé
apt cache nettoyé
VM éteinte

---

25. Conversion en template Proxmox

Cette commande n’est exécutée qu’après validation finale :

qm template VMID

Exemple :

qm template 9000

À partir de là, le modèle peut être cloné — à condition que son nom et son VMID correspondent à ce que make config a enregistré (proxmox_clone_source_nom, proxmox_clone_vmid_modele). Vérifier avant de s'en servir :

make config          # affiche la configuration lue par le moteur

---

26. Flux normal après conversion

Après conversion du modèle, le flux normal passe par make et l'API Proxmox.

Les paramètres communs Proxmox sont dans :

instance/inventories/<inventaire>/group_vars/proxmox.yml

Les secrets d'API vivent dans la voûte unifiée de l'instance (le token Proxmox aux côtés des autres vault_*), semée par make config :

instance/inventories/<inventaire>/group_vars/all/vault.yml

Créer le clone et l'ajouter à l'inventaire :

1. Cloner le template via l'API Proxmox.
2. Agrandir le disque si demandé.
3. Définir l'identité Cloud-Init.
4. Démarrer la VM.
5. Ajouter l'hôte à l'inventaire Set-OPS.

Exemple :

make creer-vm HOTE=web-frontal-01

Les paramètres par VM (VMID, IP, VLAN, passerelle) ne sont plus saisis à la main : creer-vm les lit dans l'inventaire généré depuis le plan. L'hôte doit donc être déclaré dans instance/plan/serveurs.yml et l'inventaire régénéré (make instancier-appliquer) au préalable.

Après le premier démarrage, tester l'accès :

# L'adresse n'est pas à retenir : elle est DÉRIVÉE, et le plan la donne.
make hote-afficher HOTE=web-frontal-01     # VMID · IP · VLAN · passerelle
ssh ansible@10.17.21.31                     # (l'IP ainsi obtenue)

Ensuite appliquer la conformité Ansible :

make deployer HOTE=web-frontal-01

---

27. Résumé court

La VM vanille idéale est simple :

Debian 13 minimal
UEFI / OVMF
q35
SCSI / VirtIO SCSI single
16 Go
2 Go RAM
2 cores
partition EFI 512 Mo
partition / ext4
pas de LVM
pas de swap
SSH
sudo
qemu-guest-agent
cloud-init
cloud-guest-utils
CloudInit Drive Proxmox
ciuser ansible défini dans Proxmox
clé publique SSH définie dans Proxmox
sudo fonctionnel pour ansible
APT réseau fonctionnel

La philosophie :

Proxmox crée la VM.
Cloud-init donne son identité au clone.
Ansible configure le vrai serveur.
Set-OPS documente et automatise l’ensemble.

---

28. Rejouer la préparation sur une VM existante — MODELE_HOTE

Ajouté le 2026-08-09, après avoir constaté que make preparer-modele, verifier-modele et nettoyer-modele ne pouvaient rien faire.

Ils ciblaient le groupe modeles_vm, qu'instancier émet toujours vide : les états d'un serveur ne connaissent que actif et planifie, donc rien ne pouvait y entrer. Ansible répondait « skipping: no hosts matched » — ce qui n'est pas une erreur, et passait donc inaperçu.

Pourquoi le gabarit ne peut pas venir du plan. Sa configuration Proxmox le place sur le réseau de fabrication (ip=192.168.12.99/24), pas dans le supernet du tenant. Ce n'est pas un hôte de l'écosystème : c'est la matrice dont l'écosystème est tiré.

On le désigne donc explicitement :

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

Sans MODELE_HOTE — et sans groupe modeles_vm peuplé — les trois refusent en expliquant comment les appeler. Une commande qui ne fait rien en silence est pire qu'une commande absente.

La VM doit être démarrée. Un template Proxmox ne démarre pas : le convertir en VM, ou en cloner une copie de travail et ne convertir celle-ci en template qu'une fois prouvée. Le gabarit en service reste intact pendant toute l'opération.