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 :

```text
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 :

```text
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 :*

```sh
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 :

```text
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 :

```text
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 :

```text
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 :

```text
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 :

```text
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 :

```text
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 :

```text
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 :

```text
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 :

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

Ne pas créer :

```text
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 :

```text
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 :

```text
/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 :

```bash
growpart /dev/sda 2
resize2fs /dev/sda2
```

### Swap

Pour le modèle :

```text
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 :

```bash
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 :

```text
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 :

```text
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 :

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

Laisser décoché :

```text
[ ] 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 :

```bash
su -
```

ou, si sudo est déjà disponible :

```bash
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 :

```bash
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 :

```bash
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 :

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

Résultat attendu :

```text
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 :

```bash
apt update
apt full-upgrade -y
```

---

## 15. Paquets de bootstrap

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

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

Rôle des paquets principaux :

```text
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 :

```bash
systemctl enable --now qemu-guest-agent
```

Vérifier :

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

Dans Proxmox, activer aussi :

```text
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 :

```text
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 :

```bash
shutdown -h now
```

Dans Proxmox :

```text
VM → Hardware → Add → CloudInit Drive
```

Ou en ligne de commande Proxmox :

```bash
qm set VMID --ide2 STORAGE:cloudinit
```

Exemple :

```bash
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 :

```bash
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 :

```bash
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 :

```bash
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 :

```bash
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 :

```bash
sudo -v
```

```bash
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 :

```bash
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 :

```bash
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 :

```text
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 :

```bash
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 :

```text
/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 :

```bash
make preparer-modele
make verifier-modele
```

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

```bash
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 :

```bash
make nettoyer-modele CONFIRMER=true
```

Ce nettoyage peut inclure :

```text
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 :

```text
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 :

```text
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 :

```bash
qm template VMID
```

Exemple :

```bash
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 :

```bash
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 :

```text
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` :

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

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

```text
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 :

```bash
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 :

```bash
# 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 :

```bash
make deployer HOTE=web-frontal-01
```

---

## 27. Résumé court

La VM vanille idéale est simple :

```text
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 :

```text
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 :

```bash
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.