Les principales commandes de dsoxlab, dans l'ordre

Un lab dsoxlab se joue avec une douzaine de commandes, et elles se suivent toujours dans le même ordre : installer un catalogue, diagnostiquer le poste, fixer un contexte, lire le cours, préparer l'environnement, accomplir la mission, valider, puis suivre sa progression. Cette leçon prend chaque commande dans cet ordre, dit ce qu'elle fait et ce qu'elle suppose, et s'arrête sur les trois que l'on confond : run et start, status et infra status, check et submit. Elle décrit la version 0.2.5 de la CLI et s'adresse à qui a déjà joué le lab de démonstration.

Ce que vous allez apprendre

Installer, lister et activer un catalogue avec la famille catalog.
Fixer un contexte avec use, pour que les commandes suivantes cessent de demander.
Consulter un cours et une mission avec course, guide et challenge.
Jouer un lab avec run, ou toute la séquence avec start.
Valider avec check ou submit, puis suivre avec status, progress et scores.
Provisionner et démonter les machines d'un lab vm avec provision, ssh et destroy.

L'ordre des commandes, en une table

Rien ne vous dit qu'une commande en suppose une autre, sauf le message d'échec de celle que vous avez tapée trop tôt. La table ci-dessous est l'ordre complet, et chaque ligne renvoie à la section qui la détaille. Sur un lab shell, les lignes d'infrastructure n'existent tout simplement pas.

Étape	Commande	Ce qu'elle produit
1	`dsoxlab catalog add <id ou URL>`	Un catalogue cloné et rendu actif
2	`dsoxlab doctor`	Ce que ce catalogue exige, et ce qui manque
3	`dsoxlab use <section>`	Un contexte que les commandes suivantes réutilisent
4	`dsoxlab list-labs`, `dsoxlab show <id>`	Le catalogue, puis le détail d'un lab
5	`dsoxlab course <id>`	La leçon, dans le terminal
6	`dsoxlab instructor bootstrap`, `dsoxlab provision`	Les machines d'un lab `vm`
7	`dsoxlab run <id>`, ou `dsoxlab start <id>` qui enchaîne les étapes 2, 3, 6 et 7	L'environnement préparé, et une session ouverte dedans
8	`dsoxlab challenge <id>`, `dsoxlab hint <id>`	La mission, puis un indice payant
9	`dsoxlab check <id>` ou `dsoxlab submit <id>`	Les tests, la note, et son enregistrement
10	`dsoxlab status`, `dsoxlab progress`, `dsoxlab next`, `dsoxlab scores`	Où vous en êtes
11	`dsoxlab reset <id>`, `dsoxlab clean <id>`, `dsoxlab destroy`	Repartir de zéro, ou tout démonter

Dès qu'un lab est actif dans la session, son identifiant devient optionnel : dsoxlab check sait dans quel lab vous êtes. Les identifiants sont longs, et la leçon d'installation explique comment activer la complétion du shell.

Installer et choisir un catalogue

Les labs vivent dans leurs propres dépôts, publiés séparément du moteur, et la famille catalog les gère. catalog add accepte un identifiant du manifeste embarqué, linux, ansible ou terraform, ou n'importe quelle URL git, ce qui est la voie du catalogue Kubernetes. Le dépôt est cloné sous ~/.local/share/dsoxlab/catalogs/ et devient actif, c'est-à-dire celui que dsoxlab sert quand vous n'êtes pas dans un répertoire de catalogue.

dsoxlab catalog list            # les catalogues connus, et ceux installés
dsoxlab catalog add linux       # clone et active
dsoxlab catalog add https://github.com/stephrobert/kubernetes-dsoxlab-training
dsoxlab catalog use linux       # change le catalogue actif
dsoxlab catalog update          # met à jour tous les catalogues installés
dsoxlab catalog remove linux    # retire un catalogue installé

Un simple git clone fonctionne aussi, et alors le catalogue où vous vous trouvez est celui que la CLI sert : la découverte se fait depuis le répertoire courant, et le catalogue actif n'est que le repli. Retenez que la progression vit dans le catalogue lui-même, dans un fichier .dsoxlab.db à sa racine : retirer un catalogue retire son historique avec lui.

Diagnostiquer avec doctor

dsoxlab doctor est la commande à taper après tout catalog add, parce que ce qu'elle rapporte dépend du catalogue : un catalogue fait de labs shell ne réclame jamais d'hyperviseur, et un catalogue de labs vm fait passer Terraform et l'hyperviseur en requis. Ses deux tableaux, ses options --fix, --strict et --json, et ses trois issues ok, failed et unknown sont détaillés dans la leçon Installer dsoxlab en local.

Fixer un contexte avec use

dsoxlab use pose un contexte actif pour le catalogue courant : une section, éventuellement un niveau, et trois réglages qui n'ont pas d'autre place. Sans lui, next n'a aucune section où chercher le lab suivant, et les commandes d'infrastructure ne savent pas quel provider employer quand le catalogue en propose plusieurs.

dsoxlab use l2                  # section active : les commandes suivantes s'y limitent
dsoxlab use linux --lang fr     # langue d'affichage, durablement pour ce catalogue
dsoxlab use --provider kvm      # l'hyperviseur, quand meta.yml en propose plusieurs
dsoxlab use --target ubuntu     # la machine cible par défaut d'un lab multi-hôtes
dsoxlab use --reset             # efface le contexte

Le contexte est écrit dans .dsoxlab-context.json, à la racine du catalogue. Deux variables d'environnement passent devant lui, le temps d'une commande : DSOXLAB_PROVIDER pour le provider et DSOXLAB_LANG pour la langue.

Parcourir le catalogue : list-labs, show, next

dsoxlab list-labs affiche une ligne par lab, avec sa section, son identifiant, son type, son runtime, sa durée estimée et son meilleur score. Quatre filtres le réduisent, --section, --level, --type et --bloc, et le contexte actif s'applique de lui-même. dsoxlab show <id> donne le détail d'un lab : compétences, distributions, runtime, cible, statut, et le seuil de réussite s'il s'agit d'un examen blanc.

dsoxlab list-labs --type capstone   # les seuls examens blancs
dsoxlab show cka-etcd-backup-restore
dsoxlab next                        # le premier lab sans résultat, dans l'ordre pédagogique

dsoxlab next recommande le lab suivant dans la section active, dans l'ordre que le meta.yml du catalogue déclare. Il rend all_done quand la section porte des labs et que tous ont un résultat, et sort en 1 sans contexte actif : c'est le cas le plus fréquent où il semble ne rien faire.

Lire le cours : course, guide, challenge

Deux commandes donnent la matière, et elles ne font pas la même chose. dsoxlab course affiche la leçon livrée avec le lab, dans le terminal ; sur les catalogues de ce site, elle renvoie vers la leçon correspondante. dsoxlab guide ouvre le guide en ligne du lab dans le navigateur, tel qu'il est publié, avec ses images et sa navigation ; --print imprime l'URL à la place, ce qu'il faut en session SSH. dsoxlab challenge affiche la mission, c'est-à-dire ce qui sera vérifié.

dsoxlab course l2-swap-management
dsoxlab guide l2-swap-management --print
dsoxlab challenge l2-swap-management

course et challenge passent par un pagineur dès que leur sortie dépasse la hauteur du terminal, less -R par défaut, remplaçable par la variable DSOXLAB_PAGER. Un tube ou une redirection n'est jamais paginé et reçoit le texte entier ; --no-pager affiche tout d'un coup. Quand le lab découpe son cours en sections, course en affiche une à la fois, avec --next, --prev et --section, et retient où vous vous êtes arrêté.

Jouer : run, start, hint

dsoxlab run <id> prépare l'environnement du lab et y ouvre une session. Sur un lab shell, c'est un sous-shell dans le répertoire de travail, challenge/work/ par défaut, avec les fixtures du lab copiées dedans. Sur un lab vm, c'est une session SSH sur la machine cible, après que le playbook de préparation du lab a été joué. Dans les deux cas, on en sort par exit, et dsoxlab check fonctionne depuis cette session comme depuis l'extérieur.

Ce que run ne fait pas explique la plupart des premiers échecs : il ne provisionne pas les machines. Sur un lab vm dont l'infrastructure n'existe pas, il sort en code 2 et nomme provision. C'est pour cette raison que dsoxlab start <id> existe : il joue toute la séquence, contexte, prérequis, infrastructure si le lab en veut, puis préparation et session, en annonçant chaque étape avec la commande qui la rejoue seule.

▶ 1/4 · contexte actif  (dsoxlab use l2)
▶ 2/4 · prérequis  (dsoxlab doctor)
  16 contrôles requis, tous verts
▶ 3/4 · infrastructure  (dsoxlab provision)
▶ 4/4 · préparation et session  (dsoxlab run l2-swap-management)

Quand une étape échoue, start la nomme avec sa commande, ne tente rien au-delà, et rend le code de sortie de cette étape, jamais un code inventé pour lui. Il est idempotent : il lit l'état Terraform et saute le provisionnement quand les hôtes déclarés ont déjà une adresse. Sans identifiant, il prend le lab que next suggère. Ce qu'il raccourcit, c'est la frappe et l'ordre à retenir, jamais la compréhension : chaque commande unitaire fonctionne exactement comme avant.

dsoxlab hint <id> donne l'indice suivant, dans l'ordre où l'auteur les a écrits, et son coût est déduit de la note finale. Un indice pris est enregistré immédiatement : il ne se rend pas.

Valider : check, submit, status

dsoxlab check <id> exécute les tests du lab, calcule la note, hints déduits, l'enregistre, et affiche le détail de chaque test. Il sort en 1 quand un test échoue, ce qui concerne votre travail, et en 2 quand il n'a pas pu s'exécuter, ce qui concerne votre installation. On peut le relancer autant de fois qu'on veut : chaque passage enregistre un résultat, et le meilleur devient le best_score que show et list-labs affichent.

dsoxlab check l2-swap-management
dsoxlab check drill-storage --target ubuntu   # tester la cible choisie d'un lab multi-hôtes
dsoxlab submit l2-swap-management             # même chose, puis clore la session

dsoxlab submit fait la même chose puis clôt la session : il faut ensuite taper exit. Sur un lab qui déclare un seuil de réussite, un examen blanc, submit rend en plus un verdict, réussi ou échoué, exprimé en pourcentage du barème. L'option --target de check compte sur les labs qui proposent plusieurs distributions : sans elle, un tel lab ne teste jamais que son hôte par défaut.

dsoxlab status dit où en est le lab actif, ou celui qu'on nomme, par un état stable : not_started, ready, in_progress, validated, ou degraded quand un service déclaré ne tourne plus. Il ne parle jamais des machines : c'est le rôle d'infra status, décrit plus bas, et les deux ont porté le même nom jusqu'en 0.1.67, ce qui explique qu'on les confonde encore.

Suivre sa progression : progress, scores

dsoxlab progress affiche l'avancement par bloc : labs complétés, score moyen, challenges et capstones. C'est le point de vue qui manque le plus sur une formation longue, savoir ce qui reste à prouver, et il suit l'ordre pédagogique du meta.yml. dsoxlab scores liste l'historique complet des notes enregistrées, tentatives ratées comprises, et porte une colonne Verdict sur les catalogues qui déclarent au moins un examen.

dsoxlab progress
dsoxlab scores --top 10

Les deux acceptent --json, comme list-labs, show, next, check, status, doctor, validate-structure et support. Le document rendu porte un champ schema, et les verdicts s'y lisent dans des jetons stables, jamais dans un libellé traduit : une intégration filtre sur state, pas sur « validé ».

Repartir : reset, clean

Deux commandes défont ce qu'un lab a fait, et elles ne vont pas aussi loin l'une que l'autre. dsoxlab reset <id> remet le lab à son état initial : sur un lab vm, il rejoue le playbook de nettoyage puis celui de préparation, ou revient au point de reprise disque quand le lab en exige un. dsoxlab clean <id> supprime toutes les ressources créées par le lab, y compris les conteneurs de ses services et le point de reprise. Ni l'une ni l'autre ne touche à votre historique de notes.

Les commandes d'infrastructure des labs vm

Ces commandes n'existent que pour un catalogue qui déclare un bloc infra: ; sur le catalogue Terraform, elles n'ont pas d'objet. Elles lisent le meta.yml et rien d'autre, ce qui permet d'ailleurs de se servir de dsoxlab comme d'un simple fournisseur de VM jetables, sans le moindre exercice.

dsoxlab instructor bootstrap    # génère ssh/id_ed25519 dans le catalogue, si absente
dsoxlab provision               # terraform apply sur le provider courant, puis attente SSH
dsoxlab provision --host alma-rhcsa-1.lab   # une seule machine ; option répétable
dsoxlab infra status            # qui répond en SSH, et pourquoi les muets se taisent
dsoxlab ssh alma-rhcsa-1.lab    # une session interactive sur un hôte
dsoxlab destroy                 # tout démonter, machines hors state comprises
dsoxlab destroy --yes           # sans confirmation

instructor bootstrap se joue une fois par clone, apprenants compris : un catalogue publié n'embarque aucune clé SSH, et provision refuse de démarrer sans la moitié privée. Le mot « instructor » nomme la commande, pas son public. provision recopie les templates Terraform empaquetés vers ~/.local/state/dsoxlab/<catalog-id>/, génère les variables depuis le meta.yml, applique, puis attend que chaque hôte réponde en SSH.

destroy retire aussi les machines qu'un provision en échec a laissées hors du state Terraform, après confirmation, et sort en non-zéro s'il en reste une. C'est l'habitude à prendre après chaque séance : ces machines consomment mémoire et disque bien après la fin du lab. infra status vérifie la joignabilité SSH de chaque hôte déclaré et nomme la cause quand l'un reste muet, une machine éteinte par exemple, plutôt que de rendre un délai d'attente nu.

Les options qui valent pour toutes les commandes

Trois options se placent avant la commande : --verbose ou -v, répétable, --debug, équivalent à -vv, et --version. Quelle que soit la verbosité, le journal complet est écrit dans ~/.local/state/dsoxlab/dsoxlab.log, jamais sur la sortie standard : inutile de rejouer une commande pour savoir ce qu'elle a fait, et --json reste lisible par un programme même en mode bavard.

dsoxlab -vv provision
dsoxlab --version
dsoxlab fullhelp                 # le guide complet de la plateforme, dans le terminal
dsoxlab <commande> --help        # les options d'une commande

Le reste de la CLI, validate-structure, new, support et completion, sert l'auteur de catalogue et le diagnostic, et a sa place dans les leçons suivantes de ce parcours.

Dépannage

Ces quatre cas sont des erreurs d'ordre, pas des pannes : la commande tapée en supposait une autre. Le message le dit chaque fois, et start les évite toutes.

Symptôme	Cause	Solution
`run` sort en 2 sur un lab `vm` et nomme `provision`	Les machines n'existent pas encore	`dsoxlab provision`, ou `dsoxlab start <id>` qui l'enchaîne
`provision` sort en 1 sans démarrer, faute de clé	Aucune clé SSH dans `ssh/` du catalogue, jamais commitée	`dsoxlab instructor bootstrap`, une fois par clone
`next` sort en 1 et ne suggère rien	Aucune section active	`dsoxlab use <section>`
`provision` refuse d'avancer et parle de choix de provider	Le `meta.yml` en propose plusieurs et aucun n'est choisi	`dsoxlab use --provider kvm`, ou `DSOXLAB_PROVIDER=kvm` le temps d'une commande

À retenir

L'ordre est toujours le même : catalog add, doctor, use, course, puis run, challenge, check, et progress pour savoir où l'on en est.
start enchaîne use, doctor, provision et run en annonçant chaque étape avec la commande qui la rejoue seule ; en cas d'échec, il rend le code de l'étape.
run prépare et ouvre une session, un sous-shell ou une session SSH ; il ne provisionne jamais.
check enregistre une note et se relance à volonté ; submit fait de même puis clôt la session, avec un verdict sur un examen blanc.
status parle du lab, infra status parle des machines.
Sur un lab vm : instructor bootstrap une fois par clone, provision avant, destroy après.
Le journal complet est toujours dans ~/.local/state/dsoxlab/dsoxlab.log, quelle que soit la verbosité.

Pour aller plus loin

Créer un cours et ses challenges de A à Z : Ce que validate-structure et new font pour l'auteur, et comment un lab déclare ses tests.
Monter l'infrastructure des labs vm : provision, infra status et destroy vus du côté de celui qui déclare les machines.