Installation et configuration¶

Audience : administrateur du lab Proxmox.

Prérequis cluster Proxmox¶

Avant de lancer le script, le cluster Proxmox doit être configuré :

1. Zone SDN VXLAN¶

Une zone SDN de type VXLAN doit exister (ex. esgilab). Le script ne la crée pas — elle doit être créée manuellement dans Datacenter → SDN → Zones.

Type       : VXLAN
Zone ID    : esgilab
Peers      : IPs de tous les nœuds du cluster

2. Pool template¶

Un pool Proxmox nommé template (ou le nom défini dans template_pool) doit exister pour accueillir la template OpenWrt. labomatics template openwrt crée ce pool automatiquement s'il n'existe pas et y ajoute la template.

Pour le créer manuellement si nécessaire :

Datacenter → Pools → Create → Pool ID: template

3. Stockage partagé¶

La template OpenWrt doit résider sur un stockage accessible depuis tous les nœuds (Ceph RBD, NFS, ZFS over iSCSI…). Le déploiement sélectionne le nœud le moins chargé dynamiquement — un stockage local (non partagé) empêcherait le clone depuis d'autres nœuds.

Voir template.md pour la création de la template.

4. Token API Proxmox¶

Créer un token API avec les permissions nécessaires :

Datacenter → Permissions → API Tokens → Add
User        : root@pam  (ou un compte dédié)
Token ID    : esgilabs
Privilege Separation : non (pour hériter des droits root)

Permissions minimales requises sur / (ou par chemin) :

Permission	Explication
`Sys.Modify`	Création/suppression de zones SDN, apply SDN
`Pool.Allocate`	Création/suppression de pools
`VM.Allocate`	Clone de template, suppression de VMs
`VM.Config.*`	Configuration cloud-init
`User.Modify`	Création/suppression d'utilisateurs et ACL
`Datastore.AllocateSpace`	Allocation d'espace sur le stockage

Installation Python¶

Proxmox tourne sur Debian — l'environnement Python système est géré par APT et refuse les pip install directs. Installer d'abord le paquet venv puis créer un virtualenv :

# Installer le module venv (Debian/Proxmox)
apt install python3.13-venv

# Créer le venv (une seule fois)
python3 -m venv /opt/labomatics

# Installer labomatics
/opt/labomatics/bin/pip install labomatics

# Optionnel : ajouter au PATH pour éviter le chemin complet
echo 'export PATH="/opt/labomatics/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Vérification :

labomatics --help

Configuration¶

`.env` — Credentials Proxmox¶

cp .env.example .env
# Éditer .env

PROXMOX_HOST=192.168.1.10          # IP ou FQDN du cluster Proxmox
PROXMOX_TOKEN_ID=root@pam!esgilabs # format : user@realm!token-name
PROXMOX_TOKEN_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Ne pas versionner .env — il contient le secret du token API.

`infra.yaml` — Configuration de l'infrastructure¶

Clé	Exemple	Description
`openwrt.vmid_start`	`10000`	Premier VMID alloué (VMID = vmid_start + student.id)
`openwrt.template_vmid`	`90200`	VMID de la template OpenWrt (créée par le script build)
`openwrt.storage`	`zfs-store`	Stockage partagé entre tous les nœuds
`openwrt.students_csv`	`students.csv`	Chemin vers le CSV étudiants (relatif à la racine)
`openwrt.template_pool`	`template`	Pool Proxmox contenant les templates globales
`openwrt.network.zone_name`	`esgilab`	Nom de la zone SDN VXLAN (doit exister avant apply)
`openwrt.network.wan_subnet`	`172.16.0.0/24`	Subnet WAN — IP étudiant = réseau + id
`openwrt.network.wan_gateway`	`172.16.0.254`	Passerelle WAN
`openwrt.network.vxlan_pool`	`10.100.0.0/12`	Pool VXLAN — subnet étudiant = pool_base + id×256 → /24

`students.csv` — Liste des étudiants¶

id,nom,prenom,flavor,classe
18,Dupont,Jean,CO1,M1_SRC
240,Korniev,Mikhail,CO2,M2_SEC
42,Smith,Alice,CO1,M1_SRC

id : entier unique et stable (clé de toutes les allocations réseau)
nom : nom de famille
prenom : prénom (première lettre + nom → login, ex. jdupont)
flavor : profil ressources défini dans infra.yaml
classe : groupe / promotion — optionnel, utilisé avec --classe pour filtrer

Le login Proxmox est calculé automatiquement : première_lettre_prénom + nom en minuscule. Exemple : Jean Dupont → jdupont@pve, pool jdupont.

Important : ne jamais réutiliser un id après suppression d'un étudiant — cela réattribuerait son subnet VXLAN et son IP WAN à quelqu'un d'autre.

Ordre de mise en place (à suivre dans cet ordre)¶

Ces étapes sont à réaliser une seule fois avant le premier apply. Le wizard labomatics setup les guide automatiquement.

Option A — Wizard interactif (recommandé)¶

labomatics setup

Le wizard couvre toutes les étapes ci-dessous dans l'ordre, avec vérifications automatiques à chaque étape.

Option B — Étapes manuelles¶

Étape 1 — Zone SDN VXLAN¶

Créer la zone SDN dans Datacenter → SDN → Zones (si elle n'existe pas) :

Type    : VXLAN
Zone ID : esgilab
Peers   : IPs de tous les nœuds du cluster

Étape 2 — Initialisation de la configuration¶

labomatics setup --dir /etc/labomatics   # ou manuellement :
mkdir -p /etc/labomatics
# Copier et éditer les fichiers de config
nano /etc/labomatics/.env
nano /etc/labomatics/infra.yaml
nano /etc/labomatics/students.csv

Étape 3 — Build de la template OpenWrt¶

La template OpenWrt doit être créée avant tout déploiement. Voir template.md pour le détail complet.

À exécuter en root sur un nœud Proxmox ayant accès au stockage partagé :

# Télécharge la dernière version stable d'OpenWrt, crée et configure la template
labomatics template openwrt

# Forcer une version ou un stockage spécifique
labomatics template openwrt --version 24.10.0 --vmid 90200 --storage zfs-store

La commande crée le pool template automatiquement s'il n'existe pas.

Étape 4 — Premier `apply`¶

# Vérifier le diff avant d'appliquer
labomatics student diff

# Appliquer (avec confirmation interactive)
labomatics student apply

# Appliquer sans confirmation (CI/CD)
labomatics student apply --yes

Après apply, le fichier credentials.csv est généré dans le même répertoire que students.csv. Il contient les mots de passe Proxmox générés. Ne pas le versionner.

login,nom,userid,password,wan_ip
jdupont,Jean Dupont,jdupont@pve,Abc123XyzDef,172.16.0.18
mkorniev,Mikhail Korniev,mkorniev@pve,DefGhi456Jkl,172.16.0.240