Démarrer un lab dsoxlab avec dsoxlab start

30 min
Quiz · 8 questions

Par Stéphane Robert mis à jour le 9 novembre 2026

Améliorer cette page

Que voulez-vous signaler ?

L’issue s’ouvre déjà remplie avec le titre et l’adresse de cette page.

dsoxlab start <id> démarre un lab de bout en bout : il pose le contexte (la section de catalogue active), vérifie les prérequis, monte les machines quand le lab en demande, puis prépare le lab et ouvre la session. Il annonce chaque étape avec la commande qui la rejoue seule. Cette leçon s'adresse à qui a déjà joué le lab de démonstration et choisi un lab dans un catalogue. Vous y verrez ce que run fait et ne fait pas, ce que start enchaîne autour de lui, et comment lire l'échec d'une étape.

Ce que vous allez apprendre

Démarrer un lab avec dsoxlab start et lire chaque étape annoncée.
Dire ce que dsoxlab run prépare, et ce qu'il laisse de côté.
Savoir quelles étapes un lab shell n'a pas et pourquoi.
Rejouer seule l'étape qui a échoué avec la commande que start nomme.
Relancer start sans rien casser, et nettoyer le lab quand l'étape 4 le demande.

Prérequis

Il vous faut la CLI dsoxlab en version 0.8.0 ou plus récente, installée comme le décrit la leçon Installer dsoxlab en local, et un catalogue installé avec dsoxlab catalog add, comme le montre la leçon Installer et gérer ses catalogues de labs dsoxlab. La leçon Jouer son premier lab vous a fait jouer le lab de démonstration. Le choix du lab fait l'objet de la leçon Trouver son prochain lab : ici, vous avez un identifiant de lab sous la main, ou vous laissez next en choisir un.

Un lab vm, qui se joue sur des machines virtuelles, demande en plus la clé SSH du catalogue, le fichier ssh/id_ed25519 que crée dsoxlab instructor bootstrap. Sans elle, provision s'arrête, et doctor ne le signale pas.

Que fait dsoxlab run, et pourquoi ne suffit-il pas ?

dsoxlab run <id> prépare l'environnement du lab et ouvre une session dedans, mais il ne monte jamais les machines. Un lab a un runtime, son mode d'exécution : un lab shell se joue dans un répertoire de votre poste, un lab vm sur des machines virtuelles. Sur un lab shell, la session est un sous-shell dans le répertoire de travail, challenge/work/ par défaut, avec les fichiers de départ du lab (ses fixtures) copiés dedans. Sur un lab vm, c'est en général une session SSH sur la machine cible, ouverte une fois joué le playbook de préparation du lab (un script Ansible qui prépare la machine). Dans les deux cas, vous en sortez avec exit.

Voilà pourquoi un premier run sur un lab vm échoue quand les machines n'existent pas : run sort en code 2 et nomme provision, la commande qui monte l'infrastructure. Ce n'est pas une panne, mais une étape que personne ne vous avait dit de jouer avant. Voici ce que répond dsoxlab run sur le lab epreuve-livrer-une-image, un lab vm, tant qu'aucune machine du catalogue n'existe :

$ dsoxlab run epreuve-livrer-une-image
ℹ Démarrage du lab epreuve-livrer-une-image (runtime: vm)…
⠋ Running setup.yaml… ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 0/? 0:00:00
✘ Ce lab a besoin d'une VM, et aucune ne tourne : l'infrastructure du lab n'est
pas provisionnée.
Monte-la d'abord :
  dsoxlab provision

Regardez les deux dernières lignes : elles donnent la commande à taper, et la croix ✘ annonce que run s'est arrêté sans rien préparer. La ligne de progression ⠋ s'affiche un instant avant l'erreur, elle ne veut pas dire qu'une étape a réussi.

Dans le sous-shell d'un lab shell, dsoxlab check fonctionne comme depuis l'extérieur. Cela tient à un détail du démarrage : run prend un verrou d'écriture sur le catalogue (un jeton qui empêche deux commandes d'y écrire en même temps) pendant qu'il prépare le lab, puis le rend avant d'ouvrir la session. Sans cela, le dsoxlab check tapé dans la session serait refusé par sa propre session.

Sur un lab vm, dsoxlab n'existe pas sur la machine : tapez vos commandes dsoxlab dans un second terminal, ou après exit. Une fois la session ouverte, run note aussi quel lab est actif, ce qui permet de taper check sans identifiant.

Que fait dsoxlab start, étape par étape ?

dsoxlab start <id> joue la séquence complète que run suppose, et il annonce chaque étape au lieu de la jouer en silence. Le schéma ci-dessous montre ses décisions. Regardez les deux losanges du bas : l'étape d'infrastructure n'existe que pour un lab qui n'est pas de runtime shell, et elle est sautée quand les hôtes sont déjà debout et répondent.

Un lab shell n'a pas d'étape d'infrastructure : la numérotation annoncée ne compte que les étapes qui existent pour ce lab. Source · SVG

Chaque étape s'annonce avec son rang, son nom et, entre parenthèses, la commande qui la rejoue seule. Voici un premier start sur le lab epreuve-livrer-une-image, un lab vm du catalogue containers, joué avec dsoxlab 0.8.0 alors qu'aucune machine n'existait. Les sorties de Terraform et d'Ansible, très longues, sont abrégées par [...] ; la ligne retournée à 80 colonnes est celle de la sortie réelle :

$ dsoxlab start epreuve-livrer-une-image
Démarrage de epreuve-livrer-une-image : 4 étapes, chacune annoncée avec sa
commande.

▶ 1/4 · contexte actif  (dsoxlab use containers)
  section posée sur « containers »

▶ 2/4 · prérequis  (dsoxlab doctor)
  17 contrôles requis, tous verts

▶ 3/4 · infrastructure  (dsoxlab provision)
ℹ Provisionnement de l'infrastructure (provider : kvm)…
[...]
✔ Socle en place (bootstrap.yaml). Les labs peuvent désormais le supposer.
✔ Provisionnement terminé : 2 hôte(s) prêt(s).
ℹ   docker-client.lab → 10.10.120.12
ℹ   docker.lab → 10.10.120.11

▶ 4/4 · préparation et session  (dsoxlab run epreuve-livrer-une-image)
ℹ Démarrage du lab epreuve-livrer-une-image (runtime: vm)…
[...]
✔ Lab epreuve-livrer-une-image prêt. Vous êtes connecté à docker.lab.

Lisez la parenthèse de chaque ligne : c'est la commande que vous taperiez à la main pour rejouer cette étape seule. Ici, le contexte a changé de section (« section posée »), l'étape 3 a monté deux machines (docker.lab et docker-client.lab, avec leurs adresses) et posé le socle du catalogue, puis l'étape 4 a préparé le lab. Le tout a pris environ trois minutes sur le poste de test. Voici le rôle de chaque étape.

Le contexte pose la section du lab (dsoxlab use <section>), mais seulement si elle diffère de celle déjà active. L'étape s'affiche quand même quand il n'y a rien à poser, pour que le total ne bouge pas entre deux exécutions du même lab.
Les prérequis rejouent dsoxlab doctor. Si un contrôle requis échoue, start liste ce qui manque et sort en code 2, sans rien tenter au-delà.
L'infrastructure rejoue dsoxlab provision, et n'existe que pour un lab qui n'est pas de runtime shell. Elle est sautée quand les hôtes déclarés ont une adresse dans l'état Terraform (la liste des machines que Terraform a créées) et répondent sur le port 22 de SSH. Une adresse seule ne suffit pas : une machine éteinte en a une aussi. Quand elle monte les machines, elle pose aussi le socle du catalogue (le bootstrap.yaml, ici l'installation du moteur Docker), pour que les labs puissent le supposer.
La préparation et la session jouent dsoxlab run, qui fait son travail entier : verrou, barres de progression, ouverture de la session.

Un lab shell n'a donc pas d'étape d'infrastructure, et start ne l'annonce pas : il n'y a rien à monter, donc rien à sauter. Voici start sur le lab shell lire-du-code, du catalogue dev-pour-ops : trois étapes au lieu de quatre, et aucune machine.

$ dsoxlab start lire-du-code
Démarrage de lire-du-code : 3 étapes, chacune annoncée avec sa commande.

▶ 1/3 · contexte actif  (dsoxlab use fil-rouge)
  section posée sur « fil-rouge »

▶ 2/3 · prérequis  (dsoxlab doctor)
  6 contrôles requis, tous verts

▶ 3/3 · préparation et session  (dsoxlab run lire-du-code)
ℹ Démarrage du lab lire-du-code (runtime: shell)…
✔ Lab lire-du-code prêt. Vous êtes dans challenge/work/, votre répertoire de
travail isolé.
[...]

Comparez avec le lab vm : le compteur annonce « 3 étapes », et la dernière ligne dit que vous êtes dans le répertoire de travail du lab, pas sur une machine. Le nombre de contrôles de doctor (six ici, dix-sept pour le catalogue containers) dépend du catalogue, pas du type de lab. Le [...] remplace le panneau « Comment fonctionne ce lab ».

Sans identifiant, start prend le lab que dsoxlab next suggérerait, et le dit avant de continuer. L'option --target est la même que celle de run : elle choisit la machine cible d'un lab qui en déclare plusieurs. start raccourcit la frappe et l'ordre à retenir ; chaque commande prise seule fonctionne exactement comme avant.

Que faire quand une étape de start échoue ?

Quand une étape échoue, start la nomme avec sa commande et ne tente rien au-delà. Vous ne cherchez donc jamais laquelle de use, doctor, provision ou run vous avez sautée. Les étapes 3 (provision) et 4 (run) rendent leur propre code de sortie. L'étape 2 fait exception : doctor sort en 0 (ou en 9 avec --strict) même quand un contrôle requis manque, c'est donc start qui impose alors le code 2. Voici l'échec de l'étape des prérequis, sur un poste où Terraform et ansible-playbook ne sont pas dans le PATH (la liste des dossiers où le shell cherche les programmes) :

$ dsoxlab start epreuve-livrer-une-image
Démarrage de epreuve-livrer-une-image : 4 étapes, chacune annoncée avec sa
commande.

▶ 1/4 · contexte actif  (dsoxlab use containers)
  déjà sur « containers », rien à poser

▶ 2/4 · prérequis  (dsoxlab doctor)
  il manque : Terraform, ansible-playbook
✘ L'étape 2/4 (prérequis) a échoué. Rien au-delà n'a été tenté.
ℹ Rejoue cette étape seule : dsoxlab doctor

La commande est sortie en code 2, celui que start impose quand un prérequis manque. Regardez la dernière ligne : elle donne la commande qui rejoue cette étape seule. Tapez-la, corrigez ce que doctor signale (dsoxlab doctor --fix répare ce qui l'est sans risque), puis relancez start.

Sur un lab vm, l'étape d'infrastructure peut elle aussi échouer. Si provision sort en code 8, les hôtes existent mais n'ont pas répondu dans le délai : l'infrastructure n'est pas utilisable en l'état. Relancez dsoxlab provision, qui reprend sans rien recréer, et allongez le délai si la machine est lente avec DSOXLAB_HOST_READY_TIMEOUT=360 dsoxlab provision.

Quand vous relancez start, il sonde les hôtes avant de déclarer l'infrastructure prête. Le message « les hôtes déclarés ont une adresse » abrège ce contrôle : start vérifie que chaque hôte a une adresse, puis tente une connexion TCP sur son port 22 (2 secondes au plus par hôte), et ne saute l'étape que si tous répondent. Le montage des machines est expliqué dans la leçon dsoxlab côté formateur : monter l'infrastructure des labs vm.

Pourquoi un second start échoue-t-il à l'étape 4 ?

Relancer start ne remonte pas les machines, mais l'étape 4 rejoue la préparation du lab, et certains labs refusent de la rejouer sur un atelier déjà posé. Un atelier est le dossier que la préparation crée sur la machine pour votre travail. C'est le cas du lab epreuve-livrer-une-image : relancé sans avoir rien défait, il passe les trois premières étapes sans rien faire, puis s'arrête sur une tâche du playbook de préparation :

$ dsoxlab start epreuve-livrer-une-image
Démarrage de epreuve-livrer-une-image : 4 étapes, chacune annoncée avec sa
commande.

▶ 1/4 · contexte actif  (dsoxlab use containers)
  déjà sur « containers », rien à poser

▶ 2/4 · prérequis  (dsoxlab doctor)
  17 contrôles requis, tous verts

▶ 3/4 · infrastructure  (dsoxlab provision)
  déjà provisionnée : les hôtes déclarés ont une adresse, rien à remonter

▶ 4/4 · préparation et session  (dsoxlab run epreuve-livrer-une-image)
ℹ Démarrage du lab epreuve-livrer-une-image (runtime: vm)…
[...]
  ✔ docker-client.lab: Refuser d'écraser un atelier existant (ok)
  ✔ docker.lab: Refuser d'écraser un atelier existant (ok)
  ✘ docker.lab: Exiger un atelier propre
    /opt/lab-livraison existe déjà ; jouez `dsoxlab clean` d'abord.
  ✘ docker-client.lab: Exiger un atelier propre
    /opt/lab-livraison existe déjà ; jouez `dsoxlab clean` d'abord.
⠴ Tâche : Exiger un atelier propre ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 12/? 0:00:03
✘ setup.yaml a échoué pour epreuve-livrer-une-image sur la target « cible »
(rc=2, status=failed).
[...]
✘ L'étape 4/4 (préparation et session) a échoué. Rien au-delà n'a été tenté.
ℹ Rejoue cette étape seule : dsoxlab run epreuve-livrer-une-image

Lisez le message sous la tâche en échec, répété pour chaque machine : il vous dit de jouer dsoxlab clean pour retirer l'atelier de la tentative précédente. Le premier [...] remplace les tâches réussies avant, le second les récapitulatifs par hôte et le chemin du journal complet d'Ansible. La commande est sortie en code 2.

Une fois le lab nettoyé (la leçon Recommencer ou nettoyer détaille clean), relancez start. Voici ce que donne ce second start, joué sur le lab docker-premier-conteneur du même catalogue containers, après un dsoxlab clean (l'énoncé et le panneau qui terminent la sortie sont coupés) :

$ dsoxlab start docker-premier-conteneur
Démarrage de docker-premier-conteneur : 4 étapes, chacune annoncée avec sa
commande.

▶ 1/4 · contexte actif  (dsoxlab use containers)
  déjà sur « containers », rien à poser

▶ 2/4 · prérequis  (dsoxlab doctor)
  17 contrôles requis, tous verts

▶ 3/4 · infrastructure  (dsoxlab provision)
  déjà provisionnée : les hôtes déclarés ont une adresse, rien à remonter

▶ 4/4 · préparation et session  (dsoxlab run docker-premier-conteneur)
ℹ Démarrage du lab docker-premier-conteneur (runtime: vm)…
  ✔ docker.lab: Gathering Facts (ok)
[...]
  ● docker.lab: Lancer le conteneur que l'apprenant devra ARRÊTER (changed)
  ● docker.lab: Créer le conteneur que l'apprenant devra SUPPRIMER (changed)
[...]
✔ Lab docker-premier-conteneur prêt. Vous êtes connecté à docker.lab.
[...]
✔ Session terminée pour docker-premier-conteneur. Retour à votre répertoire
d'origine.

Regardez d'abord les trois premières étapes : la première ne pose rien, la deuxième passe ses contrôles, la troisième saute le montage des machines, et aucune ne refait de travail. Regardez ensuite l'étape 4 : elle rejoue run, donc la préparation du lab. Une puce pleine ● marque une tâche qui a changé quelque chose, une coche ✔ une tâche déjà conforme. Ici, les deux ● montrent que les conteneurs retirés par clean sont recréés. La commande sort en code 0, et le lab est de nouveau dans son état de départ, sans que vous ayez retapé provision ni run.

Dépannage

Aucun de ces cas n'est une panne de l'outil : l'étape signalée attend un geste que le message nomme.

Symptôme	Cause	Solution
`start` s'arrête à l'étape « prérequis » avec « il manque : … »	Un contrôle requis de `doctor` échoue pour ce catalogue	`dsoxlab doctor`, puis `dsoxlab doctor --fix` pour ce qui se répare sans risque
`run` sort en 2 et nomme `provision`	Lab `vm` lancé sans que les machines existent	`dsoxlab provision`, ou `dsoxlab start <id>`
`provision` sort en 1 et dit de lancer d'abord `dsoxlab instructor bootstrap`	Le catalogue n'a pas de clé SSH `ssh/id_ed25519`, et `doctor` ne la contrôle pas	`dsoxlab instructor bootstrap`, puis `dsoxlab provision` ou `dsoxlab start <id>`
`provision` sort en 8	Les hôtes existent mais n'ont pas répondu dans le délai	Relancer `dsoxlab provision`, et allonger `DSOXLAB_HOST_READY_TIMEOUT` si besoin
`start` sans identifiant sort en 1	`next` ne trouve aucun lab à suggérer dans le périmètre actif	`dsoxlab use --reset`, puis `dsoxlab list-labs`
`start` s'arrête à l'étape 4 sur « Exiger un atelier propre »	L'atelier de la tentative précédente existe encore sur la machine	`dsoxlab clean <id>`, puis `dsoxlab start <id>`

À retenir

run prépare l'environnement et ouvre la session, sans jamais monter les machines.
start enchaîne contexte, prérequis, infrastructure et run, en annonçant chaque étape avec sa commande.
Un lab shell n'a pas d'étape d'infrastructure.
L'infrastructure est sautée seulement si les hôtes ont une adresse et répondent en SSH.
Quand une étape échoue, start la nomme et donne la commande qui la rejoue ; il sort en 2 si c'est l'étape des prérequis, et rend le code de provision ou de run pour les étapes 3 et 4.
Relancer start ne remonte pas les machines ; l'étape 4 peut pourtant refuser un atelier existant, et dsoxlab clean le retire.
Sans identifiant, start prend le lab que dsoxlab next suggère.

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

8 questions

6 min.

70% requis

Informations

Le chronomètre démarre au clic sur Démarrer
Questions à choix multiples, vrai/faux et réponses courtes
Vous pouvez naviguer entre les questions
Les résultats détaillés sont affichés à la fin

Démarrer un lab dsoxlab avec dsoxlab start

Ce que vous allez apprendre

Prérequis

Que fait dsoxlab run, et pourquoi ne suffit-il pas ?

Que fait dsoxlab start, étape par étape ?

Que faire quand une étape de start échoue ?

Pourquoi un second start échoue-t-il à l'étape 4 ?

Dépannage

À retenir

Contrôle de connaissances

Contrôle de connaissances

Informations

Vérification

Score par domaine

Bilan

Points forts

Points faibles

À faire ensuite