docs: guide de référence repris de two
All checks were successful
Tests / test (push) Successful in 3m28s
All checks were successful
Tests / test (push) Successful in 3m28s
Signed-off-by: GnomeZworc <nicolas.boufidjeline@g3e.fr>
This commit is contained in:
parent
ef7392f09b
commit
ac08803fcc
2 changed files with 541 additions and 0 deletions
|
|
@ -9,6 +9,8 @@ que l'on veut tester. Le plan est **déterministe** : même fichier, mêmes adre
|
|||
VM). `scripts/lab-host.sh` loue et prépare un tel hôte à l'heure chez Scaleway (Elastic Metal) ;
|
||||
c'est un exemple de fournisseur, pas une dépendance.
|
||||
|
||||
Référence détaillée, choix et vérifications : [`docs/guide.md`](docs/guide.md).
|
||||
|
||||
## Installer
|
||||
|
||||
Depuis une release : télécharger `labctl_linux_amd64` (et `lab-host.sh` si besoin) **et vérifier**
|
||||
|
|
|
|||
539
docs/guide.md
Normal file
539
docs/guide.md
Normal file
|
|
@ -0,0 +1,539 @@
|
|||
# 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
|
||||
portés par un switch). Exemple livré : [`examples/evpn-2hv/topology.yml`](../examples/evpn-2hv/topology.yml).
|
||||
|
||||
Chaque nœud non-switch est relié au switch de chacun de ses segments par un câble virtuel QEMU ;
|
||||
le switch met ces câbles dans un bridge et porte la passerelle du segment.
|
||||
|
||||
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`** — `switch` (un nœud de rôle `switch`), `cidr` IPv4 entre `/8` et `/30`, `mtu`
|
||||
facultatif — 9000 par défaut, entre 1280 et 9000. Nom : 12 caractères au plus, minuscules et
|
||||
chiffres, parce qu'il devient le nom d'interface dans les VM et, préfixé de `br-`, celui du
|
||||
bridge (15 caractères au plus sous Linux).
|
||||
|
||||
**`nodes`** — `role` (`switch`, `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 switch ne déclare ni `segments` ni
|
||||
`addresses` : il porte ceux dont il est le `switch`. 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. Sur un switch, elles vont sur le bridge du segment ;
|
||||
- `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 de son premier segment,
|
||||
qui porte la route par défaut) 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 — script du switch 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.
|
||||
|
||||
Ce que l'outil en déduit, de façon déterministe — même fichier, même plan :
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Passerelle d'un segment | la première adresse du CIDR, portée par le switch sur `br-<segment>` |
|
||||
| Adresse d'un nœud | les suivantes, **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 |
|
||||
| Câbles | un par couple (segment, nœud), segments puis nœuds dans l'ordre de déclaration ; le câble *i* utilise les ports UDP `20000 + 2i` (côté nœud) et `20001 + 2i` (côté switch) |
|
||||
| MAC | `02:4c:<nœud>:<nœud>:<segment>:<côté>` — préfixe localement administré, rang du nœud sur deux octets, rang du segment, `00` côté nœud et `01` côté switch |
|
||||
| Interfaces | côté nœud, le nom du segment ; côté switch, `p<i>`, du rang du câble |
|
||||
| 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 et les
|
||||
> ports**. C'est assumé pour un lab ; `labctl plan` montre le résultat avant tout lancement.
|
||||
|
||||
Limites : 1000 nœuds, 256 segments, et autant de câbles que la plage UDP le permet (22 768).
|
||||
|
||||
`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 4, segments 1, cables 3
|
||||
|
||||
nodes
|
||||
name role image cpus memory ssh
|
||||
sw1 switch debian12 2 1024 MiB 127.0.0.1:2200
|
||||
rr1 rr debian12 1 1024 MiB 127.0.0.1:2201
|
||||
hv1 host debian12 2 2048 MiB 127.0.0.1:2202
|
||||
hv2 host debian12 2 2048 MiB 127.0.0.1:2203
|
||||
|
||||
roles
|
||||
name loopback secondary frr provision post_provision files services
|
||||
sw1 - underlay 169.254.0.1/28 sw1.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, switch sw1, bridge br-underlay, gateway 192.168.14.1
|
||||
node interface address mac udp switch port mac udp
|
||||
rr1 underlay 192.168.14.2/24 02:4c:00:01:00:00 20000 <-> sw1 p0 02:4c:00:01:00:01 20001
|
||||
hv1 underlay 192.168.14.11/24 02:4c:00:02:00:00 20002 <-> sw1 p1 02:4c:00:02:00:01 20003
|
||||
hv2 underlay 192.168.14.12/24 02:4c:00:03:00:00 20004 <-> sw1 p2 02:4c:00:03:00:01 20005
|
||||
```
|
||||
|
||||
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 switch
|
||||
segment underlay: cidr 10.250.0.0/31 prefix length out of range [/8, /30]
|
||||
node sw1: switch carries no segment
|
||||
```
|
||||
|
||||
## 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 le switch et le route reflector —, 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 switch, 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 switch du lab est un routeur 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 — extrait réel, côté réseau :
|
||||
|
||||
```text
|
||||
-netdev
|
||||
user,id=mgmt0,restrict=on,ipv6=off,hostfwd=tcp:127.0.0.1:2202-:22
|
||||
-device
|
||||
virtio-net-pci,netdev=mgmt0,mac=02:4d:00:02:00:00,romfile=
|
||||
-netdev
|
||||
dgram,id=underlay,local.type=inet,local.host=127.0.0.1,local.port=20002,remote.type=inet,remote.host=127.0.0.1,remote.port=20003
|
||||
-device
|
||||
virtio-net-pci,netdev=underlay,mac=02:4c:00:02: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 le switch** : 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) ;
|
||||
- **câbles** : `dgram` sur `127.0.0.1`, les deux extrémités d'un câble se répondent (port local
|
||||
de l'une = port distant de l'autre), `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, `p<i>`),
|
||||
`dhcp4: false` partout, `mgmt0` en `10.0.2.15/24` **sans passerelle** ; connexion SSH par
|
||||
clé seulement, utilisateur `debian`, `root` désactivé, mot de passe refusé ;
|
||||
- **un nœud** : adresse sur chaque segment, MTU du segment, route par défaut et DNS
|
||||
(`1.1.1.1`, `8.8.8.8`) sur son **premier** segment — la sortie Internet passe par le switch ;
|
||||
- **le switch** : route par défaut par `mgmt0` ; un service `lab-switch` crée un bridge
|
||||
`br-<segment>` par segment (STP désactivé, MTU du segment), y branche ses ports, porte la
|
||||
passerelle, active le routage et masque (NAT nftables) les segments vers `mgmt0`. Le service
|
||||
est rejoué à chaque démarrage.
|
||||
|
||||
### Vérifié sur de vraies VM
|
||||
|
||||
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. démarre les QEMU, **switchs d'abord**, détachés (`-daemonize`) : ils survivent à la session
|
||||
SSH qui les a lancés ;
|
||||
6. 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.
|
||||
|
||||
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.
|
||||
|
||||
**`labctl down`** — arrête chaque QEMU par `SIGTERM`, puis `SIGKILL` au bout de 30 s. Les disques
|
||||
sont conservés jusqu'au prochain `up`, qui les recrée.
|
||||
|
||||
**`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
|
||||
|
||||
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.
|
||||
- **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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue