dsoxlab conserve son état à deux endroits, et nulle part ailleurs : dans le catalogue que vous jouez, pour la progression, et sous votre répertoire personnel, pour le journal, les caches et le state Terraform. Cette page de référence liste chaque fichier, chaque variable d'environnement et chaque code de sortie de la version 0.2.5, avec le geste que chacun appelle. Elle s'adresse à qui veut sauvegarder sa progression, retrouver un journal après un échec, ou appeler dsoxlab depuis un script. Ces emplacements sont tenus en accord avec le code par un test du projet : ils ne dérivent pas en silence.
Ce que vous allez apprendre
Section intitulée « Ce que vous allez apprendre »- Situer la base de progression et le contexte, qui vivent dans le catalogue.
- Retrouver le journal, les caches et le state Terraform sous votre répertoire personnel.
- Régler la langue, le provider ou le délai d'attente par variable d'environnement.
- Interpréter chaque code de sortie, et distinguer un « non » d'un « impossible ».
- Exploiter la sortie
--jsonsans dépendre d'un libellé traduit.
Dans le catalogue que vous jouez
Section intitulée « Dans le catalogue que vous jouez »La progression appartient au catalogue, pas à la machine. Deux catalogues côte à côte gardent des historiques séparés, copier le répertoire d'un catalogue copie votre historique avec lui, et le supprimer supprime le sien. C'est ce qui rend une sauvegarde triviale : un seul fichier à copier.
| Chemin | Contenu | Écrit par |
|---|---|---|
<catalogue>/.dsoxlab.db | Base SQLite : les notes (results) et les indices pris (hint_requests) | check, submit, hint |
<catalogue>/.dsoxlab-context.json | Section, niveau, langue, lab, cible et provider actifs, plus la position de lecture du cours | use, run, course |
<catalogue>/ssh/id_ed25519 et .pub | La paire de clés SSH déployée sur les machines des labs vm | instructor bootstrap |
Les deux premiers sont à ignorer dans le .gitignore du catalogue, et les
catalogues publiés le font. La paire de clés n'est jamais commitée non
plus : la privée ne doit pas l'être, et la publique ne sert à rien sans elle,
d'où la règle d'une paire par clone, produite sur chaque machine qui
provisionne.
Sous votre répertoire personnel
Section intitulée « Sous votre répertoire personnel »Tout le reste suit les conventions XDG et se déplace avec les trois
variables correspondantes. <catalog-id> est le repo.id du meta.yml du
catalogue, ce qui fait que deux clones du même catalogue partagent un seul
state Terraform et un seul verrou.
| Chemin | Contenu | Déplacé par |
|---|---|---|
~/.local/state/dsoxlab/dsoxlab.log | Journal complet de chaque commande, quelle que soit la verbosité | XDG_STATE_HOME |
~/.local/state/dsoxlab/<catalog-id>/terraform/<provider>/ | Répertoire de travail et state Terraform, un par provider | XDG_STATE_HOME |
~/.local/state/dsoxlab/<catalog-id>/cloud-init/ | Templates cloud-init recopiés depuis l'outil pour le provisionnement | XDG_STATE_HOME |
~/.local/state/dsoxlab/<catalog-id>/dsoxlab.lock | Verrou d'écriture de ce catalogue | XDG_STATE_HOME |
~/.local/state/dsoxlab/<catalog-id>/labs/ | Empreintes du répertoire de travail, prises par run, pour distinguer un lab prêt d'un lab en cours | XDG_STATE_HOME |
~/.local/state/dsoxlab/catalogue-actif | Identifiant du catalogue actif | XDG_STATE_HOME |
~/.cache/dsoxlab/<catalog-id>/inventory.json | Inventaire Ansible généré | XDG_CACHE_HOME |
~/.cache/dsoxlab/<catalog-id>/ssh_config | Configuration OpenSSH générée pour les hôtes du lab | XDG_CACHE_HOME |
~/.cache/dsoxlab/version-check.json | Dernière version vue sur PyPI, et sa date | XDG_CACHE_HOME |
~/.local/share/dsoxlab/demo/ | Catalogue de démonstration installé par dsoxlab demo | XDG_DATA_HOME |
~/.local/share/dsoxlab/catalogs/ | Catalogues installés par catalog add, un sous-répertoire par identifiant | XDG_DATA_HOME |
~/.ssh/config.d/<catalog-id>.conf | Fragment SSH des hôtes du lab, pour que ssh, scp et votre IDE les atteignent par leur nom | aucune |
Deux de ces fichiers sont des caches, et les perdre ne coûte qu'une
régénération : inventory.json et ssh_config sont reconstruits à la
prochaine commande qui en a besoin. Tout ce qui pointerait sur le ssh_config
généré, un Include ou un profil d'IDE, doit donc tolérer sa disparition. Le
fragment de ~/.ssh/config.d/ est celui qui est stable, à condition que
~/.ssh/config porte un Include de ce répertoire avant tout bloc Host :
dsoxlab n'écrit pas cette ligne à votre place, et le signale à chaque
provision tant qu'elle manque.
Le state Terraform est délibérément hors du catalogue : un state posé dans
un dépôt de labs finit commité, et un state commité ment. La complétion
du shell écrit en dehors de ces deux familles, une fois : ~/.zfunc/_dsoxlab
plus une ligne dans ~/.zshrc, ou ~/.bash_completion.d/dsoxlab plus une
ligne dans ~/.bashrc.
Ce qui n'existe pas
Section intitulée « Ce qui n'existe pas »Trois chemins ont été documentés par le passé et figurent ici pour que
personne ne les cherche à nouveau. Il n'existe aucun
~/.config/dsoxlab/config.yaml, ni aucun fichier de configuration
utilisateur : ce qui se règle passe par le contrat du meta.yml, par le
contexte actif de dsoxlab use, ou par une variable d'environnement. Il
n'existe aucun ~/.local/share/dsoxlab/progress.db : les notes vivent dans
<catalogue>/.dsoxlab.db. Et XDG_CONFIG_HOME n'est lue nulle part : les
trois variables XDG citées plus haut sont les seules que dsoxlab honore.
Variables d'environnement
Section intitulée « Variables d'environnement »Une variable d'environnement vaut le temps d'un appel, ou d'une session de shell, et passe devant le fichier de contexte du catalogue. C'est le bon outil pour un essai ponctuel, une commande dans un script, ou un délai à allonger sur une machine lente.
| Variable | Effet |
|---|---|
LAB_HOME | Racine du catalogue à jouer, au lieu de la détection automatique |
DSOXLAB_LANG | Langue d'affichage, en ou fr, prioritaire sur le fichier de contexte |
DSOXLAB_PROVIDER | Provider d'infrastructure, prioritaire sur dsoxlab use --provider |
DSOXLAB_TARGET | Cible par défaut d'un lab vm, quand la session n'en fixe aucune |
DSOXLAB_PAGER | Pagineur de course et challenge, puis PAGER, défaut less -R |
DSOXLAB_LOG | DSOXLAB_LOG=debug équivaut à -vv |
DSOXLAB_HOST_READY_TIMEOUT | Secondes d'attente d'un hôte fraîchement provisionné, défaut 180 |
DSOXLAB_NO_UPDATE_CHECK | À 1, coupe l'avis quotidien de nouvelle version |
DSOXLAB_OUTSCALE_PROFILE, DSOXLAB_AWS_PROFILE | Profil d'identifiants de ces providers |
Deux autres sont posées par dsoxlab pour que les tests d'un lab les
lisent, et ne se règlent pas à la main : DSOXLAB_TARGET_HOST, l'hôte que les
tests doivent inspecter, ce qui permet à un lab multi-distributions de valider
la cible choisie, et DSOXLAB_LAB_SESSION, l'identifiant du lab dans la
session ouverte par run.
Les codes de sortie
Section intitulée « Les codes de sortie »Un code de sortie est le contrat le plus dur que l'outil expose : un document JSON peut gagner un champ, une phrase traduite peut changer de mot, mais un code, une fois qu'un script le lit, ne peut plus bouger sans casser cet appelant en silence. Ils vivent tous au même endroit du code, dans un énuméré, et deux tests tiennent la table honnête : aucune valeur ne sert deux fois, et chaque code doit figurer dans la documentation.
| Code | Ce qu'il veut dire | Le geste qu'il appelle |
|---|---|---|
0 | La commande a fait ce qu'on lui demandait | Rien |
1 | La commande a tourné, et la réponse est non : identifiant de lab inconnu, test rouge, hôte qui ne répond pas, aucun contexte actif | Lire le message ; la réponse porte sur votre travail, pas sur votre installation |
2 | La commande n'a pas pu s'exécuter : infrastructure non provisionnée, provider non empaqueté, fixture déclarée absente, point de reprise exigé impossible | Préparer quelque chose ; ce n'est pas une faute dans votre travail |
3 | Terraform n'est pas installé, donc provision et destroy n'ont aucun moyen d'agir | L'installer |
4 | Terraform a répondu, et il a échoué | Lire sa sortie ; dsoxlab nomme les causes qu'il reconnaît, comme un pool de stockage plein ou absent |
5 | Un provision a laissé des machines orphelines, définies sur l'hyperviseur mais absentes du state, ou en a trouvé avant de commencer | Jouer la ligne virsh undefine que le message affiche |
6 | Un destroy n'a pas pu retirer ces orphelines | Les retirer à la main, puis rejouer destroy |
7 | Une autre commande dsoxlab tient déjà le verrou de ce catalogue | Réessayer ; c'est le seul code où réessayer est juste, et le message nomme le processus qui le détient |
8 | Un provision a rendu la main sans que tous les hôtes ciblés répondent | dsoxlab status dit lequel et pourquoi ; souvent plus de temps ou plus de vCPU |
9 | doctor --strict : un contrôle requis a échoué, c'est établi | Réparer ce que le tableau nomme |
10 | doctor --strict : un contrôle requis n'a pas pu être mesuré | Remesurer ; rien n'est conclu, donc rien n'est validé |
127 | Un exécutable attendu n'est pas dans le PATH | L'installer ; 127 est le code que le shell rend lui-même ici |
130 | Un Ctrl-C | Le message donne le geste de reprise |
Trois distinctions sont délibérées, et ce sont elles qui justifient cette
table. Le 7 est le seul code sur lequel réessayer, parce que sa cause est
temporaire par nature ; tous les autres décrivent un état qui ne changera pas
de lui-même. Le 9 et le 10 sont séparés parce que les gestes diffèrent,
réparer contre remesurer, et quand les deux coexistent, 9 l'emporte : une
certitude est plus forte qu'une ignorance. Le 1 et le 2 séparent
« non » de « impossible » : un check qui échoue sort en 1, l'outil a
travaillé ; un run dont une fixture manque sort en 2, rien n'a été mesuré.
doctor sans --strict sort en 0 quoi qu'il trouve, délibérément : pour
un humain, un diagnostic n'est pas un échec, et le verdict vit dans le champ
ok de --json. C'est --strict, et non --json, qui traduit le
diagnostic en 9 ou 10.
La sortie machine, en trois règles
Section intitulée « La sortie machine, en trois règles »Tout ce que dsoxlab affiche est fait pour des yeux, des tableaux dont la
largeur suit le terminal, des couleurs, des barres de progression, et c'est
fait pour bouger. --json rend un document à la place, et trois règles le
gouvernent. La sortie standard porte le document et rien d'autre : le
rappel du contexte, les astuces et l'avis de mise à jour partent sur la sortie
d'erreur. Chaque document porte un champ schema, son premier, dont la
valeur courante est 1. Et un verdict se lit dans une clé et un jeton
stable, key, state, kind, status, cause, jamais dans un libellé
traduit posé à côté pour l'affichage.
Une conséquence mérite d'être dite à part : --json change la forme de la
sortie, jamais le verdict ni le code de retour. Un check sur un lab en échec
sort en 1 avec ou sans lui, et rend son document d'abord, pour qu'un appelant
recevant un code non nul puisse lire ce qui n'allait pas. Lisez le code de
retour en premier, le document ensuite.
dsoxlab list-labs --json | jq '.count'dsoxlab doctor --json --strict; echo "code : $?"dsoxlab check premiers-pas --json | jq '.check.ok'doctor --json --fix est refusé, et le dit sur la sortie d'erreur : les
commandes de remédiation écrivent sur la sortie standard, et le document en
deviendrait illisible. On lit le diagnostic d'abord, on agit ensuite.
À retenir
Section intitulée « À retenir »- La progression vit dans
<catalogue>/.dsoxlab.db, par catalogue : un fichier à copier pour la sauvegarder. - Le journal complet est toujours dans
~/.local/state/dsoxlab/dsoxlab.log, et le state Terraform sous~/.local/state/dsoxlab/<catalog-id>/. - Il n'existe aucun fichier de configuration utilisateur : contrat, contexte actif ou variable d'environnement.
- Une variable
DSOXLAB_*passe devant le fichier de contexte, le temps d'un appel. - 7 se réessaie, 9 se répare, 10 se remesure ; 1 est un « non », 2 un « impossible ».
--jsonchange la forme, jamais le verdict ni le code ; on lit le code en premier.
Pour aller plus loin
Section intitulée « Pour aller plus loin »- Monter l'infrastructure des labs vm : Les codes 5, 6 et 8 vus du formateur, avec le verrou par catalogue et le fragment SSH stable.