All checks were successful
Tests / test (push) Successful in 3m46s
Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
636 lines
34 KiB
Markdown
636 lines
34 KiB
Markdown
# Guide de labctl
|
|
|
|
Référence détaillée ; le [README](../README.md) en est le résumé. Les sorties citées viennent de
|
|
campagnes réelles : les dates et versions sont celles de leur relevé.
|
|
|
|
## Le serveur loué : `scripts/lab-host.sh`
|
|
|
|
Un serveur **Scaleway Elastic Metal**, créé pour une campagne de tests puis supprimé, facturé à
|
|
l'heure.
|
|
|
|
**Offre.** L'offre par défaut est `EM-B420E-NVME` (AMD EPYC 7272, 12 cœurs, 119 Gio) : son modèle
|
|
de CPU est exact et atteint **x86-64-v3**, le minimum de RHEL 10 et Rocky 10. Les offres « Xeon …
|
|
or equivalent » ne garantissent rien : `EM-B212X-SSD` (« E5-2620 v4 or equivalent ») a livré un
|
|
E5-2640 v3 une fois, un E5-2670 de 2012 (x86-64-v2, sur lequel Rocky 10 ne démarre pas) une autre.
|
|
`prepare` refuse donc un serveur sans x86-64-v3 — dans une `session`, il est aussitôt supprimé.
|
|
Relever `lscpu` au début de chaque campagne.
|
|
|
|
### Prérequis côté Scaleway
|
|
|
|
1. **Un projet dédié au lab**, séparé de toute autre ressource. `lab-host.sh down` supprime
|
|
tout serveur de lab du projet : il ne doit rien y avoir d'autre.
|
|
2. **Une clé d'API limitée à ce projet**, avec les droits Elastic Metal et la lecture des clés SSH
|
|
du projet. Rien d'autre.
|
|
3. **Les clés SSH publiques enregistrées dans le projet**, injectées à l'installation : sans
|
|
elles, le serveur serait facturé sans que personne puisse s'y connecter, et `plan` refuse de
|
|
continuer.
|
|
4. **Le quota Elastic Metal.** Il exige un compte dont le moyen de paiement *et* l'identité sont
|
|
validés. Vérifier dans la console : Organisation → Quotas → Elastic Metal. Voir
|
|
[les quotas Scaleway](https://www.scaleway.com/en/docs/organizations-and-projects/organization/organization-quotas/).
|
|
|
|
### Fichiers locaux
|
|
|
|
Tout ce dont le script a besoin vit sous `~/.config/labctl/`, hors du dépôt.
|
|
|
|
**`~/.config/labctl/scaleway.env`** — identifiants Scaleway, une ligne `CLÉ=valeur` chacun :
|
|
|
|
```bash
|
|
SCW_SECRET_KEY=<clé secrète>
|
|
SCW_DEFAULT_PROJECT_ID=<identifiant du projet de lab>
|
|
SCW_DEFAULT_ZONE=fr-par-1
|
|
```
|
|
|
|
- le fichier doit être en `0600` : le script refuse de s'en servir s'il est lisible par
|
|
d'autres que son propriétaire ;
|
|
- il est **lu, jamais exécuté** — pas de `source` ; seules ces trois clés sont reconnues ;
|
|
- une variable d'environnement du même nom l'emporte sur le fichier ;
|
|
- la clé d'accès (`SCW…`) n'est pas nécessaire : l'API REST n'authentifie que par la clé
|
|
secrète, dans l'en-tête `X-Auth-Token`.
|
|
|
|
Pour changer de clé, remplacer la ligne `SCW_SECRET_KEY=` ; rien d'autre à modifier.
|
|
|
|
**`~/.config/labctl/ssh/lab_ed25519`** — clé SSH dédiée au lab, **sans phrase de passe**, pour
|
|
que les sessions tournent sans intervention. Sa partie publique doit être enregistrée dans le
|
|
projet. Quand elle existe, le script l'utilise **seule** (`IdentitiesOnly`, agent désactivé) ;
|
|
sinon il retombe sur l'agent SSH.
|
|
|
|
Elle ne doit ouvrir que les serveurs éphémères du projet de lab : **ne jamais l'installer sur une
|
|
machine durable**. En cas de doute, la retirer du projet et en générer une autre :
|
|
|
|
```bash
|
|
mkdir -p ~/.config/labctl/ssh && chmod 700 ~/.config/labctl ~/.config/labctl/ssh
|
|
ssh-keygen -t ed25519 -N '' -C lab-automation -f ~/.config/labctl/ssh/lab_ed25519
|
|
```
|
|
|
|
**`~/.cache/labctl/`** — état de la session en cours : adresse et utilisateur du serveur,
|
|
`known_hosts` dédié. Vidé par `down`.
|
|
|
|
### Commandes
|
|
|
|
```text
|
|
usage: lab-host.sh <commande> [arguments]
|
|
|
|
plan résout l'offre horaire, l'OS et les clés SSH, affiche la requête de création
|
|
et le prix ; ne crée rien
|
|
up crée le serveur de lab, attend la fin de son installation et son SSH,
|
|
puis le prépare (voir prepare)
|
|
status liste les serveurs de lab du projet, dans toutes les zones candidates
|
|
ssh [commande] se connecte au serveur de lab ; avec une commande, un terminal n'est demandé
|
|
que si l'entrée standard en est un
|
|
prepare installe sur le serveur ce dont labctl a besoin (qemu, genisoimage), vérifie
|
|
/dev/kvm, la virtualisation imbriquée et un CPU x86-64-v3 ; lancé aussi par up
|
|
push <topologie> compile cmd/labctl pour linux/amd64 et dépose sur le serveur ~/labctl et le
|
|
répertoire de la topologie dans ~/topology/ (avec les fichiers qu'elle
|
|
référence) ; ensuite : ssh './labctl up topology/<topologie>'
|
|
down supprime tous les serveurs de lab du projet, dans toutes les zones candidates,
|
|
et attend leur disparition
|
|
session [cmd] up, puis la commande distante (ou un shell), puis down quoi qu'il arrive
|
|
```
|
|
|
|
`plan` et `status` sont **gratuits** ; `up` et `session` **créent un serveur facturé**.
|
|
|
|
Toujours commencer par `plan`. Il valide la clé d'API, le quota d'offre, l'OS et les clés SSH,
|
|
et montre exactement ce qui serait commandé :
|
|
|
|
```text
|
|
$ scripts/lab-host.sh plan
|
|
!! fr-par-1 : offre EM-B420E-NVME en rupture de stock en fr-par-1
|
|
!! fr-par-2 : offre EM-B420E-NVME en rupture de stock en fr-par-2
|
|
!! nl-ams-1 : offre horaire EM-B420E-NVME : 0 correspondance(s) en nl-ams-1, une seule attendue
|
|
== zone : nl-ams-2
|
|
== offre : EM-B420E-NVME (d14eef5e-3279-42db-bb57-bb2bbe6a5b28), AMD EPYC 7272, facturation hourly, stock available
|
|
== prix : 0.444 EUR HT par heure, frais de mise en service 0 EUR
|
|
== os : Debian 12 (Bookworm) (83640d93-a0b8-45ad-9c9f-30cae48380a4), utilisateur root
|
|
== clés : 2 clé(s) SSH du projet
|
|
== requête : POST /baremetal/v1/zones/nl-ams-2/servers
|
|
```
|
|
|
|
**Zone.** Elle n'est pas imposée : `plan` et `up` prennent la première zone de `LAB_ZONES` (par
|
|
défaut toutes les zones Elastic Metal) où l'offre est en stock, `SCW_DEFAULT_ZONE` passant en
|
|
tête ; `status` et `down` couvrent toutes ces zones. Une zone dont la liste échoue est signalée
|
|
sans masquer les autres : `status` affiche ce qui a répondu, `down` supprime les serveurs listés,
|
|
et tous deux sortent en erreur ; `up` refuse de créer tant qu'une zone reste inconnue.
|
|
|
|
**`session`** est la forme la plus sûre : le serveur est supprimé à la fin, que la commande
|
|
réussisse, échoue, ou que la session soit interrompue (Ctrl-C, `TERM`, fermeture du terminal).
|
|
Son code de sortie est celui de la commande distante. `up`, `ssh` et `down` séparément servent
|
|
aux campagnes longues et au debug interactif — et laissent la suppression à la charge de
|
|
l'utilisateur.
|
|
|
|
Compter **environ 15 minutes** entre la création et le SSH disponible : l'installation de Debian
|
|
par Scaleway en prend une dizaine, et SSH ne répond pas tout de suite après — d'où l'attente
|
|
intégrée à `up`.
|
|
|
|
Une campagne enchaîne ces commandes depuis le poste ; `labctl` s'exécute sur le serveur (voir
|
|
[Lancement des VM](#lancement-des-vm)) :
|
|
|
|
```text
|
|
scripts/lab-host.sh up
|
|
scripts/lab-host.sh push examples/evpn-2hv/topology.yml
|
|
scripts/lab-host.sh ssh './labctl up topology/topology.yml'
|
|
scripts/lab-host.sh ssh './labctl ssh hv1' # shell interactif sur hv1
|
|
scripts/lab-host.sh ssh './labctl ssh hv1 ip -br a' # commande, code de retour propagé
|
|
scripts/lab-host.sh down
|
|
```
|
|
|
|
`push` transfère par la connexion SSH du script — mêmes options, même clé, même `known_hosts`
|
|
que `ssh` : le binaire par `cat`, le répertoire de la topologie par `tar` (sans les métadonnées
|
|
macOS), chacun renommé une fois complet. Tout le répertoire part, pour que les fichiers que la
|
|
topologie référence arrivent avec elle. Avec `LABCTL_BIN`, `push` envoie ce binaire (par exemple
|
|
celui d'une release, vérifié) au lieu de compiler.
|
|
|
|
## Topologie
|
|
|
|
Un lab est décrit par un fichier YAML : des **nœuds** (les VM) et des **segments** (des réseaux
|
|
L2). Exemple livré : [`examples/evpn-2hv/topology.yml`](../examples/evpn-2hv/topology.yml) — deux
|
|
routeurs en VRRP, un route reflector et deux hôtes en EVPN.
|
|
|
|
Chaque segment est un **bridge Linux sur l'hôte du lab** (`lb-<segment>`), et chaque nœud qui y
|
|
est attaché y branche une carte par un tap (`lt<i>`). Le L2 ne dépend donc d'aucune VM : la
|
|
perte d'un routeur ne coupe pas le trafic direct entre les autres nœuds du segment. Un
|
|
**routeur** est un nœud comme les autres, qui porte en plus la passerelle et le NAT des segments
|
|
dont il est routeur.
|
|
|
|
Ce que le fichier déclare :
|
|
|
|
**`images`** — `url` de l'image qcow2 et `sums` du fichier de sommes à vérifier, tous deux en
|
|
`https://`.
|
|
|
|
**`segments`** — `cidr` IPv4 entre `/8` et `/30`, `mtu` facultatif — 9000 par défaut, entre 1280
|
|
et 9000 —, et `routers`, facultatif : les nœuds de rôle `router` qui portent la passerelle du
|
|
segment, **dans l'ordre de priorité**. Sans routeur, le segment est un L2 pur (lien entre VM,
|
|
lien inter-cluster) : pas de passerelle, pas de NAT. Nom : 12 caractères au plus, minuscules et
|
|
chiffres, parce qu'il devient le nom d'interface dans les VM et, préfixé de `lb-`, celui du bridge
|
|
sur l'hôte (15 caractères au plus sous Linux).
|
|
|
|
**`nodes`** — `role` (`router`, `rr` ou `host`), `image`, `cpus`, `memory` en Mio (256 au
|
|
moins), `segments` auxquels le nœud est relié, et `addresses` pour fixer l'adresse d'un nœud sur
|
|
un segment (`addresses: {underlay: 192.168.14.50}`). Un routeur listé dans `segments.<s>.routers`
|
|
doit être attaché à `<s>`. Champs facultatifs :
|
|
|
|
- `secondary` — des adresses supplémentaires par segment, avec leur longueur de préfixe
|
|
(`secondary: {underlay: [169.254.0.3/28]}`), posées sur la même interface que l'adresse
|
|
principale : même L2, même MAC. Elles doivent être **hors** du CIDR du segment, pour ne
|
|
jamais croiser l'attribution automatique ;
|
|
- `loopback` — une adresse sur une interface `dummy` nommée `lo1` (`loopback: 10.255.255.1/32`) ;
|
|
- `frr` — le chemin d'un `frr.conf`, relatif au fichier de topologie : FRR est installé au
|
|
démarrage et la configuration déposée **telle quelle** (voir [FRR](#frr)) ;
|
|
- `provision` — le chemin d'un script, relatif au fichier de topologie, exécuté au premier
|
|
démarrage **avant** FRR ;
|
|
- `post_provision` — un second script, exécuté **après** FRR ;
|
|
- `files` — des fichiers **ou répertoires** déposés dans `/etc/lab/files/<nom>` avant les
|
|
scripts, sous la forme `{<nom>: <chemin>}` (`files: {motd: motd}`). Ils voyagent dans un
|
|
`files.iso` propre au nœud (volume `LABFILES`), attaché comme second lecteur et recopié au
|
|
premier démarrage : la taille n'est pas limitée par cloud-init, et un binaire de plusieurs
|
|
dizaines de Mio passe ;
|
|
- `services` — les unités systemd que `labctl up` vérifie actives sur le nœud.
|
|
|
|
Les scripts reçoivent `LAB_NODE` (nom du nœud), `LAB_UPLINK` (interface qui porte la route par
|
|
défaut : celle du premier segment du nœud qui a une passerelle, `mgmt0` pour un routeur) et
|
|
`LAB_FILES`
|
|
(`/etc/lab/files`). L'outil ne sait rien de ce qu'ils installent.
|
|
|
|
**Un seul script de provisionnement par nœud.** cloud-init exécute `runcmd` comme un script `sh`
|
|
sans `set -e` : seule la dernière commande compterait, et une provision en échec suivie d'un FRR
|
|
installé avec succès passerait pour un démarrage réussi. Chaque nœud reçoit donc
|
|
`/usr/local/sbin/lab-provision`, en `set -eu`, qui enchaîne ses étapes — service du routeur ou de
|
|
la loopback, `provision`, FRR, `post_provision` ; `runcmd` n'appelle que lui, et la première
|
|
étape en échec met cloud-init en erreur.
|
|
|
|
`mgmt0` et `lo1` sont réservés : aucun segment ne peut porter ces noms.
|
|
|
|
### Passerelle et routeurs
|
|
|
|
| Routeurs du segment | Passerelle |
|
|
|---|---|
|
|
| aucun | aucune : les nœuds n'y ont pas de route par défaut |
|
|
| un | la première adresse du CIDR, posée sur l'interface du routeur, en plus de la sienne |
|
|
| deux ou plus | la première adresse du CIDR, **virtuelle**, portée en VRRP v3 par `vrrpd` de FRR |
|
|
|
|
Avec plusieurs routeurs, `labctl` prépare tout sur chacun : interface `macvlan` `vr<segment>`
|
|
avec la MAC VRRP (`00:00:5e:00:01:<vrid>`) et la passerelle, créée **coupée** (`protodown on`) :
|
|
seul `vrrpd` la rétablit, quand il devient maître ; `arp_ignore=1` et `arp_announce=2`
|
|
sur l'interface du segment (sans quoi elle répondrait aux ARP de la passerelle avec sa propre
|
|
MAC), FRR installé avec `vrrpd`, et la configuration VRRP **ajoutée** à la fin de son `frr.conf`
|
|
(ou d'un `frr.conf` minimal s'il n'en déclare pas) :
|
|
|
|
```text
|
|
interface underlay
|
|
vrrp 1 version 3
|
|
vrrp 1 priority 200
|
|
no vrrp 1 preempt
|
|
vrrp 1 ip 192.168.14.1
|
|
exit
|
|
```
|
|
|
|
Le VRID est le rang du segment plus un (d'où au plus 255 segments à plusieurs routeurs, parmi les
|
|
premiers) ; la priorité vaut 200 pour le premier routeur de la liste, puis 10 de moins pour
|
|
chacun des suivants. **Pas de préemption** : un routeur qui revient reste en attente, plutôt que
|
|
de reprendre la passerelle avant d'avoir ses routes BGP — un prétest l'a montré, la préemption
|
|
coupait les sessions qui passaient par lui. Conséquence : le maître est le premier routeur dont
|
|
VRRP démarre, la priorité ne départageant que des démarrages simultanés ; un scénario qui arrête
|
|
« le maître » doit le demander (`vtysh -c 'show vrrp'`), pas le supposer. Bascule mesurée en
|
|
prétest : environ 2,6 s de perte (trois annonces manquées à une seconde d'intervalle).
|
|
|
|
Chaque routeur masque (NAT nftables) vers `mgmt0` les segments dont il est routeur, et sort par
|
|
le NAT de QEMU. Un nœud qui n'est pas routeur prend sa route par défaut et ses DNS (`1.1.1.1`,
|
|
`8.8.8.8`) sur le premier de ses segments qui a une passerelle.
|
|
|
|
### Plan déterministe
|
|
|
|
Ce que l'outil déduit du fichier — même fichier, même plan :
|
|
|
|
| | |
|
|
|---|---|
|
|
| Passerelle d'un segment | la première adresse du CIDR, si le segment a au moins un routeur |
|
|
| Adresse d'un nœud | les suivantes (dès la première sans routeur), **dans l'ordre de déclaration des nœuds** ; une adresse fixée par `addresses` est réservée d'abord et sautée par l'attribution automatique |
|
|
| Bridge | `lb-<segment>` sur l'hôte du lab |
|
|
| Ports | un par couple (segment, nœud), segments puis nœuds dans l'ordre de déclaration ; le port *i* est le tap `lt<i>` |
|
|
| MAC | `02:4c:<nœud>:<nœud>:<segment>:00` — préfixe localement administré, rang du nœud sur deux octets, rang du segment |
|
|
| Interfaces | dans la VM, le nom du segment |
|
|
| SSH d'administration | `127.0.0.1:<2200 + rang du nœud>` sur l'hôte du lab |
|
|
|
|
> [!WARNING]
|
|
> Réordonner les nœuds ou les segments dans le fichier **change les adresses, les MAC, les taps et
|
|
> les ports**. C'est assumé pour un lab ; `labctl plan` montre le résultat avant tout lancement.
|
|
|
|
Limites : 1000 nœuds, 256 segments.
|
|
|
|
`labctl plan` valide le fichier et affiche le plan, sans rien lancer :
|
|
|
|
```text
|
|
$ go run ./cmd/labctl plan examples/evpn-2hv/topology.yml
|
|
lab evpn-2hv: nodes 5, segments 1, ports 5
|
|
|
|
nodes
|
|
name role image cpus memory ssh
|
|
r1 router debian12 1 1024 MiB 127.0.0.1:2200
|
|
r2 router debian12 1 1024 MiB 127.0.0.1:2201
|
|
rr1 rr debian12 1 1024 MiB 127.0.0.1:2202
|
|
hv1 host debian12 2 2048 MiB 127.0.0.1:2203
|
|
hv2 host debian12 2 2048 MiB 127.0.0.1:2204
|
|
|
|
roles
|
|
name loopback secondary frr provision post_provision files services
|
|
r1 - underlay 169.254.0.1/28 r1.conf - - - -
|
|
r2 - underlay 169.254.0.2/28 r2.conf - - - -
|
|
rr1 lo1 10.255.255.1/32 underlay 169.254.0.3/28 rr1.conf - - - -
|
|
hv1 - - hv1.conf host.sh - motd -
|
|
hv2 - - hv2.conf host.sh - motd -
|
|
|
|
segment underlay: 192.168.14.0/24, mtu 9000, bridge lb-underlay, gateway 192.168.14.1 by vrrp 1 on r1, r2
|
|
node interface address mac tap
|
|
r1 underlay 192.168.14.252/24 02:4c:00:00:00:00 lt0
|
|
r2 underlay 192.168.14.253/24 02:4c:00:01:00:00 lt1
|
|
rr1 underlay 192.168.14.2/24 02:4c:00:02:00:00 lt2
|
|
hv1 underlay 192.168.14.11/24 02:4c:00:03:00:00 lt3
|
|
hv2 underlay 192.168.14.12/24 02:4c:00:04:00:00 lt4
|
|
```
|
|
|
|
Un fichier invalide est refusé avec **toutes** ses erreurs à la fois, et un code de sortie 1. Les
|
|
champs inconnus et les clés en double sont refusés aussi :
|
|
|
|
```text
|
|
$ labctl plan cassee.yml
|
|
labctl: cassee.yml:
|
|
segment underlay: rr1 is a rr, not a router
|
|
segment underlay: router r9 is not a declared node
|
|
segment underlay: cidr 10.250.0.0/31 prefix length out of range [/8, /30]
|
|
node r1: must be attached to at least one segment
|
|
```
|
|
|
|
### Migration depuis 0.1
|
|
|
|
Le rôle `switch` et le champ `segments.<s>.switch` n'existent plus : `labctl` les refuse avec un
|
|
message qui dit quoi faire. Pour une topologie 0.1 :
|
|
|
|
1. `role: switch` devient `role: router` ;
|
|
2. le routeur déclare `segments: [<s>]` et, de préférence, une adresse fixée (`addresses`) — en
|
|
0.1, le switch n'avait que la passerelle ;
|
|
3. `segments.<s>.switch: <nom>` devient `segments.<s>.routers: [<nom>]` ;
|
|
4. ses `secondary` restent valables : elles vont désormais sur son interface du segment, et non
|
|
plus sur un bridge interne.
|
|
|
|
## FRR
|
|
|
|
Au premier démarrage, cloud-init installe FRR (`frr-stable` de `deb.frrouting.org`, sans les
|
|
paquets recommandés), active `bgpd` — et `bfdd` sur les routeurs et les route reflectors,
|
|
`vrrpd` sur les routeurs d'un segment en VRRP —, puis
|
|
dépose le `frr.conf` du nœud et redémarre FRR. La mise à jour des index de paquets est réessayée
|
|
pendant cinq minutes : un nœud peut démarrer avant que le routeur, par lequel il sort, n'ait posé
|
|
son NAT.
|
|
|
|
La **clé du dépôt FRR** n'est pas téléchargée au démarrage : elle est enregistrée dans `labctl`
|
|
(`internal/render/frrouting.gpg`) et déposée par cloud-init. Elle a été récupérée le 2026-10-04
|
|
sur `deb.frrouting.org` ; les empreintes de ses clés primaires sont publiées sous la même valeur
|
|
sur `keys.openpgp.org` et `keyserver.ubuntu.com` :
|
|
|
|
```text
|
|
3D99 68AC 9AE7 BE11 6928 8DDB 1FD5 8398 95F5 7FDA David Lamparter
|
|
4A56 C773 8BB3 F815 95A8 05D2 A832 7699 08F1 3ED1 FRRouting Debian Repository
|
|
A90F C36D 9429 4097 98E9 C2D8 74DE ED43 AB19 4DBF Jafar Al-Gharaibeh
|
|
```
|
|
|
|
Une clé renouvelée par FRR fera échouer l'installation (signature inconnue) : remplacer le fichier
|
|
après avoir vérifié les nouvelles empreintes.
|
|
|
|
**Ce que vérifie** `labctl up`, une fois cloud-init terminé sans erreur : les `services` déclarés
|
|
par chaque nœud, et `frr` sur chaque nœud qui en a un. Ce contrôle couvre ce que cloud-init ne
|
|
voit pas — une provision qui arme un redémarrage, par exemple : la VM redémarrée ne rejoue pas
|
|
`runcmd`.
|
|
|
|
> [!NOTE]
|
|
> **Le routeur du lab est un Linux avec FRR, par choix.** Il joue le rôle générique de
|
|
> routeur de cluster : passerelle des nœuds et, dans l'exemple, session eBGP avec BFD vers le
|
|
> route reflector, dont il n'accepte que la loopback. L'équipement réel d'une infrastructure
|
|
> (MikroTik, Cisco, Juniper, Arista…) n'a besoin que de BGP et d'EVPN ; sa configuration propre
|
|
> au constructeur n'a pas sa place dans le lab.
|
|
|
|
## Rendu des VM
|
|
|
|
`labctl render` produit, pour chaque nœud, ce qu'il faut pour démarrer sa VM — sans rien lancer :
|
|
|
|
```text
|
|
$ go run ./cmd/labctl render -key ~/.config/labctl/ssh/lab_ed25519.pub examples/evpn-2hv/topology.yml <répertoire>
|
|
```
|
|
|
|
`<répertoire>/<nœud>/` reçoit :
|
|
|
|
- **`qemu.args`** — les arguments de `qemu-system-x86_64`, **un par ligne** : rien à échapper,
|
|
rien à interpréter par un shell ;
|
|
- **`meta-data`, `user-data`, `network-config`** — les trois fichiers NoCloud de cloud-init, à
|
|
mettre dans une image de volume `cidata`.
|
|
|
|
Les chemins de la VM (`disk.qcow2`, `seed.iso`, `console.log`, `qmp.sock`, `qemu.pid`) sont ceux
|
|
du répertoire du nœud ; `-key` peut être répété, et accepte un fichier `authorized_keys` (lignes
|
|
vides et commentaires ignorés). Les fichiers sont créés en `0600`.
|
|
|
|
Ce que contiennent les arguments QEMU d'un nœud — côté réseau :
|
|
|
|
```text
|
|
-netdev
|
|
user,id=mgmt0,restrict=on,ipv6=off,hostfwd=tcp:127.0.0.1:2203-:22
|
|
-device
|
|
virtio-net-pci,netdev=mgmt0,mac=02:4d:00:03:00:00,romfile=
|
|
-netdev
|
|
tap,id=underlay,ifname=lt3,script=no,downscript=no
|
|
-device
|
|
virtio-net-pci,netdev=underlay,mac=02:4c:00:03:00:00,host_mtu=9000,romfile=
|
|
```
|
|
|
|
Les choix qui s'y lisent :
|
|
|
|
- **machine** `q35`, `-accel kvm -cpu host` — le KVM imbriqué des nœuds en dépend ;
|
|
`-nodefaults` pour qu'aucun périphérique implicite ne s'ajoute ;
|
|
- **administration** (`mgmt0`) : le NAT de QEMU, MAC `02:4d:<nœud>:<nœud>:00:00`, SSH redirigé
|
|
sur la boucle locale de l'hôte. `restrict=on` pour tous les nœuds **sauf les routeurs** : un
|
|
nœud isolé ne joint ni l'hôte ni l'extérieur par là, seule la redirection SSH passe.
|
|
`ipv6=off` partout (voir plus bas) ;
|
|
- **segments** : un tap créé par `labctl up` (`script=no` : QEMU ne lance aucun script), branché
|
|
sur le bridge du segment ; `host_mtu` annonce le MTU du segment au guest ;
|
|
- `romfile=` vide sur toutes les cartes : pas de ROM de démarrage réseau, donc pas de repli sur
|
|
un démarrage PXE si le firmware ne trouve pas le disque. Pendant les premiers essais, une VM
|
|
restée bloquée sans rien écrire sur sa console, CPU au repos, avait toutes les apparences de
|
|
ce repli ; la cause n'a pas été isolée, l'option est une précaution.
|
|
|
|
Ce que fait cloud-init :
|
|
|
|
- **toutes les VM** : interfaces nommées d'après leur MAC (`mgmt0`, nom du segment),
|
|
`dhcp4: false` partout, `mgmt0` en `10.0.2.15/24` ; connexion SSH par clé seulement,
|
|
utilisateur `debian`, `root` désactivé, mot de passe refusé ;
|
|
- **un nœud** : adresse et `secondary` sur chaque segment, MTU du segment, route par défaut et
|
|
DNS sur le premier de ses segments qui a une passerelle ; `mgmt0` **sans passerelle** ;
|
|
- **un routeur** : mêmes adresses, route par défaut par `mgmt0` ; un service `lab-router` active
|
|
le routage, pose les passerelles (adresse ou `macvlan` VRRP, voir
|
|
[Passerelle et routeurs](#passerelle-et-routeurs)) et le NAT nftables. Le service est rejoué à
|
|
chaque démarrage.
|
|
|
|
### Vérifié sur de vraies VM
|
|
|
|
Relevés faits avec le modèle 0.1 — le switch portait alors le bridge du segment, relié aux nœuds
|
|
par des câbles UDP ; ce qui touche au L2 et à la passerelle est à revérifier avec les bridges de
|
|
l'hôte.
|
|
|
|
Le switch et le route reflector n'ont pas besoin de KVM imbriqué : `sw1` et `rr1` ont été
|
|
démarrés **sur un Mac**, en émulation (TCG), avec Debian 12 `generic` et les fichiers produits
|
|
par `labctl render`.
|
|
|
|
| Vérification | Résultat |
|
|
|---|---|
|
|
| interfaces nommées et adressées, bridge `br-underlay` en `10.250.0.1/24` | conforme |
|
|
| service `lab-switch` actif, y compris après redémarrage | conforme |
|
|
| `ping -M do -s 8972` de `rr1` vers le switch (MTU 9000, sans fragmentation) | passe |
|
|
| `ping -M do -s 8973` (MTU 9001) | refusé : `message too long, mtu=9000` |
|
|
| Internet depuis `rr1` en IPv4 | passe, par `10.250.0.1` |
|
|
| `rr1` vers un service TCP de l'hôte par `mgmt0` — le switch, témoin, y parvient | bloqué |
|
|
| `rr1` vers Internet par `mgmt0` | bloqué |
|
|
|
|
Un défaut trouvé par cet essai, et corrigé : sans `ipv6=off`, le NAT de QEMU annonce un préfixe
|
|
IPv6 et `mgmt0` reçoit une **route IPv6 par défaut** — vers une impasse, puisque `restrict=on`
|
|
bloque tout. Pas de fuite, mais chaque programme qui tente l'IPv6 d'abord (le DNS renvoie d'abord
|
|
des adresses IPv6) attend un délai avant de se rabattre sur l'IPv4.
|
|
|
|
> [!NOTE]
|
|
> Un `ping` vers `10.0.2.2` n'est pas un test d'isolation : c'est la passerelle virtuelle de QEMU
|
|
> qui répond elle-même, `restrict=on` ou non. Seule une connexion vers un vrai service de l'hôte,
|
|
> avec un témoin qui y parvient, le prouve.
|
|
|
|
## Lancement des VM
|
|
|
|
`labctl` s'exécute **sur l'hôte du lab**. Il garde l'état du lab dans un répertoire (`-run`, par
|
|
défaut `~/lab-run`) : `status`, `down` et `ssh` n'ont donc pas besoin de la topologie.
|
|
|
|
```text
|
|
labctl up [-run dir] [-cache dir] [-timeout 20m] <topologie.yml>
|
|
labctl status [-run dir]
|
|
labctl down [-run dir]
|
|
labctl ssh [-run dir] <nœud> [commande…]
|
|
```
|
|
|
|
**`labctl up`**
|
|
|
|
1. refuse de continuer si un lab tourne déjà dans le répertoire ;
|
|
2. télécharge chaque image dans le cache (`-cache`, par défaut `~/.cache/labctl`) et la vérifie
|
|
contre `SHA512SUMS` ; une image déjà présente et toujours conforme n'est pas retéléchargée, la
|
|
liste des sommes est relue à chaque fois ;
|
|
3. génère une paire de clés SSH dans le répertoire du lab, si elle n'existe pas encore ;
|
|
4. pour chaque nœud : fichiers de `labctl render`, disque **neuf** en overlay qcow2 sur l'image
|
|
(`qemu-img create -b`, 20 Gio annoncés), image `cidata` et `files.iso` (`genisoimage`) ;
|
|
5. crée les bridges des segments et les taps des nœuds (voir [Réseau de l'hôte](#réseau-de-lhôte)),
|
|
et refuse de continuer si l'un d'eux existe déjà ;
|
|
6. démarre les QEMU, **routeurs d'abord**, détachés (`-daemonize`) : ils survivent à la session
|
|
SSH qui les a lancés ;
|
|
7. attend sur chaque nœud la fin de cloud-init (`cloud-init status --wait` par SSH), jusqu'au
|
|
délai `-timeout`, puis vérifie ses services (`frr` compris quand il est installé).
|
|
|
|
La topologie est copiée dans `<run>/topology.yml`. Un échec laisse les nœuds démarrés en place :
|
|
`labctl status`, puis `labctl down`.
|
|
|
|
**`labctl status`** — pour chaque nœud : rôle, état du processus QEMU, PID, port SSH sur la
|
|
boucle locale ; pour chaque segment : bridge présent ou absent, passerelle.
|
|
|
|
**`labctl down`** — arrête chaque QEMU par `SIGTERM`, puis `SIGKILL` au bout de 30 s, puis
|
|
supprime les taps et les bridges du lab. Les disques sont conservés jusqu'au prochain `up`, qui
|
|
les recrée.
|
|
|
|
`up` et `down` doivent tourner **en root** : ils créent et suppriment des interfaces de l'hôte.
|
|
|
|
### Réseau de l'hôte
|
|
|
|
Pour chaque segment, `labctl up` exécute :
|
|
|
|
```text
|
|
ip link add name lb-<segment> type bridge stp_state 0 mcast_snooping 0
|
|
ip link set dev lb-<segment> addrgenmode none
|
|
ip tuntap add dev lt<i> mode tap # pour chaque port du segment
|
|
ip link set dev lt<i> addrgenmode none
|
|
ip link set dev lt<i> mtu <mtu> master lb-<segment> up
|
|
ip link set dev lb-<segment> mtu <mtu> up
|
|
```
|
|
|
|
- **Aucune adresse côté hôte**, IPv4 ni IPv6 (`addrgenmode none` : pas même de lien local) :
|
|
l'hôte n'est pas joignable depuis un segment, et ne route rien entre eux.
|
|
- **Pas de STP ni de surveillance IGMP** : le bridge se comporte comme un switch simple, et les
|
|
annonces VRRP (`224.0.0.18`) circulent sans dépendre d'un querier.
|
|
- Si `br_netfilter` est chargé sur l'hôte, `bridge-nf-call-iptables` est mis à 0 : le pare-feu
|
|
de l'hôte ne filtre pas le trafic des segments.
|
|
- Un lab par hôte : les noms `lb-*` et `lt*` ne sont pas propres à un répertoire `-run`.
|
|
|
|
**`labctl ssh`** — ouvre un shell sur un nœud, ou y exécute une commande, avec la clé générée par
|
|
`up`. `labctl` cède la place à `ssh`, dont le code de retour est donc celui de la commande. Un
|
|
terminal n'est demandé (`-t`) que si l'entrée de `labctl` en est un : depuis un script, ni
|
|
pseudo-terminal ni `\r\n` dans la sortie.
|
|
|
|
Comme `ssh`, `labctl ssh` recolle ses arguments par des espaces et les confie à un shell distant
|
|
— et depuis le poste, il y en a **deux** : celui du serveur, puis celui de la VM. Une commande
|
|
qui contient elle-même des guillemets se passe en une seule chaîne :
|
|
|
|
```text
|
|
$ echo | scripts/lab-host.sh ssh './labctl ssh hv1 sh -c "exit 42"'; echo "rc 42=$?"
|
|
rc 42=0
|
|
$ echo | scripts/lab-host.sh ssh "./labctl ssh hv1 'sh -c \"exit 42\"'"; echo "rc 42=$?"
|
|
rc 42=42
|
|
```
|
|
|
|
Dans le premier cas, la VM reçoit `sh -c exit 42` : `exit` sans argument, `42` en `$0`. Pour plus
|
|
d'une commande, passer un script sur l'entrée standard :
|
|
`scripts/lab-host.sh ssh "./labctl ssh hv1 'sudo bash -s'" < script.sh`.
|
|
|
|
Un processus n'est tenu pour celui d'un nœud que si son PID, lu dans `qemu.pid`, désigne un
|
|
processus vivant dont la ligne de commande (`/proc/<pid>/cmdline`) contient `-name <nœud>`. Un
|
|
PID réutilisé par un autre programme n'est donc jamais signalé.
|
|
|
|
> [!WARNING]
|
|
> Le cache range une image sous son nom de fichier, et l'URL de Debian est `latest` : une
|
|
> nouvelle publication remplace le fichier, et les overlays existants pointeraient sur une base
|
|
> différente. `up` recrée toujours les disques, ce qui suffit avec un lab par serveur ; **ne pas
|
|
> relancer un QEMU à la main** à partir d'un `qemu.args` après un `up` ultérieur.
|
|
|
|
### Vérifié sur le serveur de lab
|
|
|
|
Avec le modèle 0.1 (voir la remarque précédente). Le 2026-10-04, sur un Xeon E5-2640 v3, Debian 12 et QEMU 7.2 sur le serveur, topologie à deux
|
|
hôtes :
|
|
|
|
| Vérification | Résultat |
|
|
|---|---|
|
|
| `ping -M do -s 8972` de hv1 à hv2 à travers le switch | passe |
|
|
| `ping -M do -s 8973` | refusé : `message too long, mtu=9000` |
|
|
| sortie Internet de hv1 | par le switch, HTTPS 200 ; aucune route IPv6 globale |
|
|
| hv1 vers un service TCP du serveur par `mgmt0` — sw1, témoin, y parvient (200) | refusé |
|
|
| hv1 vers Internet par `mgmt0`, route forcée via `10.0.2.2` — sw1 y parvient | refusé |
|
|
| `/dev/kvm` et `nested` dans hv1 | présent, `Y` |
|
|
| racine de hv1 (overlay de 20 Gio) | 20 Go : `growpart` agrandit la partition au premier démarrage |
|
|
| code de retour à travers `lab-host.sh ssh` et `labctl ssh`, sans terminal | propagé jusqu'au poste |
|
|
| `scripts/lab-host.sh ssh './labctl ssh hv1'` depuis un terminal | shell interactif |
|
|
| `labctl down` puis `labctl up` d'une autre topologie | conforme |
|
|
|
|
`labctl up` d'une topologie sans provision prend moins d'une minute, téléchargement et
|
|
vérification de l'image (427 Mio) compris : l'essentiel du temps d'une campagne est la livraison
|
|
du serveur et ce que les provisions installent.
|
|
|
|
## Facturation
|
|
|
|
> [!WARNING]
|
|
> Un serveur Elastic Metal est facturé **de sa création à sa suppression, éteint compris**.
|
|
> Éteindre ne suffit pas : il faut supprimer. La granularité n'est pas documentée par Scaleway —
|
|
> compter chaque heure entamée comme une heure pleine.
|
|
|
|
Ce que le script garantit :
|
|
|
|
- il ne commande **jamais** d'offre mensuelle : il exige une seule offre au nom demandé, en
|
|
facturation horaire, en stock et sans frais de mise en service, sinon il refuse avant toute
|
|
création. La CLI `scw` n'est pas utilisée pour cette raison : son `server create type=…`
|
|
choisit l'offre par son seul nom et peut tomber sur la mensuelle, qui engage un mois ;
|
|
- il refuse de créer un second serveur si un serveur de lab existe déjà ;
|
|
- `down` agit sur **tous** les serveurs portant le tag `labctl` dans le projet, et `session` y
|
|
ajoute l'identifiant reçu à la création : un serveur créé juste avant une interruption est
|
|
rattrapé ;
|
|
- une suppression refusée pendant la livraison ou l'installation est réessayée tant qu'elle dure,
|
|
dans la limite du délai d'installation augmenté du délai de suppression ;
|
|
- le serveur n'est déclaré supprimé qu'au 404 de l'API, jamais sur une erreur passagère ;
|
|
- un échec de suppression se termine par `SERVEUR(S) DE LAB TOUJOURS FACTURÉ(S)` et un code
|
|
d'erreur.
|
|
|
|
Ce qu'il ne peut pas garantir : un `SIGKILL`, une coupure de courant ou une mise en veille du
|
|
poste qui lance la session. En cas de doute, toujours :
|
|
|
|
```bash
|
|
scripts/lab-host.sh status
|
|
scripts/lab-host.sh down
|
|
```
|
|
|
|
## Diagnostic
|
|
|
|
**`aucune clé SSH active dans le projet`** — aucune clé SSH n'est enregistrée dans le projet de
|
|
lab. En ajouter une dans la console (projet → Clés SSH).
|
|
|
|
**`offre horaire EM-B420E-NVME : 0 correspondance(s)`** — l'offre n'existe pas dans la zone en
|
|
facturation horaire. Sans conséquence si une autre zone candidate la propose ; sinon, vérifier
|
|
`LAB_ZONES` et `LAB_OFFER`.
|
|
|
|
**`création incertaine`** — la création a échoué ou n'a pas rendu d'identifiant. Le serveur a pu
|
|
être créé malgré tout — cas typique : le quota (identité non validée), ou une réponse perdue. Le
|
|
script indique s'il voit un serveur de lab ; dans tous les cas, lancer `status` puis `down`.
|
|
|
|
**`SSH injoignable`** — l'installation est terminée mais SSH ne répond pas après 10 minutes. Avec
|
|
une clé matérielle (Yubikey), chaque connexion demande un PIN ou un toucher : utiliser la clé
|
|
dédiée du lab. Le serveur est toujours facturé : `down`.
|
|
|
|
**`SERVEUR(S) DE LAB TOUJOURS FACTURÉ(S)`** — la suppression n'a pas abouti dans les délais.
|
|
Relancer `down` ; si l'erreur persiste, supprimer depuis la console Scaleway.
|
|
|
|
**`HTTP 403 insufficient permissions`** — la clé d'API est authentifiée mais n'a pas le droit
|
|
demandé — en général la lecture des clés SSH du projet. Compléter la politique de la clé, limitée
|
|
au projet.
|
|
|
|
## Sécurité
|
|
|
|
- La clé secrète n'apparaît ni dans les arguments des processus (elle est passée à `curl` par
|
|
un descripteur de fichier), ni dans les journaux, ni dans l'environnement de `ssh`.
|
|
- **Ne jamais lancer le script sous** `bash -x` : la trace afficherait la clé.
|
|
- Le serveur n'expose que SSH, par clé.
|
|
- Une clé secrète qui a circulé ailleurs que dans `scaleway.env` (conversation, terminal
|
|
partagé, capture d'écran) se régénère.
|
|
- **Clé SSH des VM** : générée par `labctl up` sur le serveur, c'est la seule clé autorisée dans
|
|
les VM. Elle ne quitte jamais le serveur, n'ouvre que les VM du lab — qui n'écoutent qu'en
|
|
boucle locale — et disparaît avec lui. La clé publique du poste n'est jamais envoyée aux VM.
|
|
- **Segments isolés de l'hôte** : bridges et taps sans adresse (voir
|
|
[Réseau de l'hôte](#réseau-de-lhôte)) ; seuls les routeurs sortent, par le NAT de QEMU.
|
|
- **Clés d'hôte des VM non vérifiées** par `labctl ssh` (`known_hosts` jetable) : elles changent
|
|
à chaque `up`. Acceptable uniquement parce que la connexion reste sur la boucle locale d'un
|
|
serveur auquel on s'est authentifié.
|
|
- **Image** : `SHA512SUMS` vient de la même origine que l'image, en HTTPS. La vérification
|
|
protège contre la corruption, pas contre une origine compromise ; la signature GPG de Debian
|
|
(`SHA512SUMS.sign`) n'est pas encore vérifiée.
|
|
|
|
## Tests
|
|
|
|
```bash
|
|
go test ./...
|
|
bash scripts/lab-host_test.sh
|
|
```
|
|
|
|
Environ une minute et demie, sans réseau : la suite remplace `curl` par une fausse API Scaleway
|
|
qui se place dans le pire cas (offre mensuelle listée avant l'horaire, serveurs d'autres projets,
|
|
suppressions refusées, erreurs 503, serveur qui tarde à disparaître) et `ssh` par un faux client.
|
|
Elle tourne sous bash 5 comme sous le bash 3.2 de macOS.
|