Starting over or cleaning up a dsoxlab lab: reset, clean, destroy

Three commands undo what a lab has done, and they do not go equally far: reset puts the lab back in its starting state and erases the hints taken, clean deletes what the lab created, and destroy takes the machines down. None of them touches your recorded marks. This lesson is for anyone who plays labs and wants to start from scratch without losing their history, or to finish a session without leaving machines that consume memory and disk.

What you will learn

• Choose between reset, clean and destroy according to what you want to undo.
• Say what each command leaves in place: hints, marks, machines.
• Start from scratch on a shell lab and on a vm lab.
• Confirm or refuse a deletion, at the keyboard or with --yes.
• Recognise the orphan machines that destroy removes.

Prerequisites

You need the dsoxlab CLI in version 0.8.0 or newer and a lab already played, as the lesson Getting your work checked with dsoxlab check and submit describes. For destroy, you need a catalogue of vm labs whose machines were brought up by dsoxlab provision or dsoxlab start, as the lesson Starting a dsoxlab lab with dsoxlab start explains.

Which command undoes what: reset, clean or destroy?

reset puts the lab back to zero so you can replay it, clean removes what it created, destroy is not about the lab but about the machines. The table below says, for each command, what it undoes and what it leaves. A mark is here the score that check recorded. Read the "Recorded marks" column: it is the reason why you can use them without fear for your history.

Command	Lab state	Hints taken	Recorded marks	Machines
dsoxlab reset <id>	Put back in its initial state, then prepared again	Erased	Kept	Kept
dsoxlab clean <id>	Resources created by the lab deleted	Left	Kept	Kept
dsoxlab destroy	Nothing left to play without provisioning again	Left	Kept	Destroyed

Swipe to see more

Three commands, on the other hand, take your marks away with the rest: dsoxlab demo --force, dsoxlab catalog remove and dsoxlab catalog add --force, since the progress lives in the catalogue's .dsoxlab.db file. They also erase the hints taken.

A practical rule sums up the choice: to start the same lab over, type reset; to free what the lab left behind without replaying it, type clean; to end the session of a vm lab, type destroy.

How do you start from scratch with dsoxlab reset?

dsoxlab reset <id> puts the lab back in the state where run left it at the start, and erases the hints you had taken. It therefore erases more than clean, which leaves the hints. On a shell lab, it is worth a clean followed by a restart: the working directory is deleted then recreated with the lab's starting files (its fixtures), which also empties your files, reponses/ for the premiers-pas demonstration lab.

On a vm lab, reset replays the cleanup playbook then the preparation one. When the lab requires a disk restore point (a snapshot of the machine's disk), it brings the machine back to that point then replays the preparation.

dsoxlab reset epreuve-livrer-une-image

Before touching anything, reset asks a question and waits for your answer. Here is what is displayed on the vm lab epreuve-livrer-une-image when you answer n. The outputs of this lesson were captured with DSOXLAB_LANG=fr, so the messages are in French: the same messages exist in English.

$ dsoxlab reset epreuve-livrer-une-image
Réinitialiser le lab epreuve-livrer-une-image ? Le travail en cours est perdu. [y/N]: n
Aborted.

The question recalls that the work in progress is lost ("Le travail en cours est perdu"), and [y/N] says that the default answer is no: just pressing Enter cancels too. The command then exits with code 1, and nothing has been undone. With --yes, the question disappears and the full run is displayed. On this vm lab, the output is long: it is abridged here to show the shape:

$ dsoxlab reset epreuve-livrer-une-image --yes
ℹ Réinitialisation de epreuve-livrer-une-image…
  ✔ docker-client.lab: Gathering Facts (ok)
  ✔ docker.lab: Gathering Facts (ok)
  ✔ docker.lab: Retirer les conteneurs et les images de l'épreuve (ok)
[...]
  ✔ docker.lab: Retirer l'atelier et le relevé du banc (ok)
  ✔ docker-client.lab: Retirer l'atelier et le relevé du banc (ok)
  ✔ docker-client.lab: Gathering Facts (ok)
  ✔ docker.lab: Gathering Facts (ok)
  ✔ docker.lab: Installer les outils bornés (ok)
[...]
  ● docker.lab: Créer le fichier de livraison, vide, que la mission demande de
remplir (changed)
⠋ cleanup.yaml terminé ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 53/? 0:00:21
✔ Lab réinitialisé.

Read the run in two stages: the cleanup tasks ("Retirer…", Remove…) pass first, then the preparation ones ("Installer…", "Créer…", Install…, Create…) start again from zero. This is the order announced above: reset replays the cleanup, then the preparation. The solid bullet ● marks a task that changed something, the tick ✔ a task that was already in the right state. The command took about twenty-one seconds on the test machine.

On a shell lab such as lire-du-code, the output fits in two lines:

$ dsoxlab reset lire-du-code --yes
ℹ Réinitialisation de lire-du-code…
✔ Lab réinitialisé.

In both cases, the success criterion is the message "Lab réinitialisé" (Lab reset): the lab is back in its starting state.

reset does not touch the marks: dsoxlab status displays the same thing before and after, and a lab already marked stays "validé" (validated) with its best mark (100 / 100 for lire-du-code). Since the hints are erased, the cost of hint starts again from zero for the next check runs; the attempts already recorded nevertheless keep the list of the hints you had seen at their date.

How do you delete what the lab created with dsoxlab clean?

dsoxlab clean <id> deletes all the resources the lab created, including the containers of its services, and touches neither the hints nor the marks. On a shell lab, it plays the lab's cleanup.yaml if there is one, then deletes the working directory. On a vm lab, it plays the cleanup playbook on the target machine and, when the lab requires a disk restore point, removes that point: the machine itself stays in place. A vm lab with no cleanup playbook makes the command fail with code 2, with a message that names the expected cleanup.yaml file.

dsoxlab clean epreuve-livrer-une-image

The question asked beforehand is "Supprimer les ressources du lab" (Delete the lab's resources) followed by the lab's name. Here is the n answer on the vm lab epreuve-livrer-une-image, then the actual cleanup with --yes:

$ dsoxlab clean epreuve-livrer-une-image
Supprimer les ressources du lab epreuve-livrer-une-image ? [y/N]: n
Aborted.

$ dsoxlab clean epreuve-livrer-une-image --yes
ℹ Nettoyage de epreuve-livrer-une-image…
  ✔ docker-client.lab: Gathering Facts (ok)
  ✔ docker.lab: Gathering Facts (ok)
  ✔ docker-client.lab: Retirer les conteneurs et les images de l'épreuve (ok)
  ✔ docker.lab: Retirer les conteneurs et les images de l'épreuve (ok)
  ✔ docker.lab: Retirer le cache de construction, qui survivrait aux images (ok)
  ✔ docker-client.lab: Retirer le cache de construction, qui survivrait aux
images (ok)
  ✔ docker-client.lab: Rendre les deux images publiques du banc (ok)
  ✔ docker.lab: Rendre les deux images publiques du banc (ok)
  ● docker-client.lab: Retirer la confiance installée pour le moteur (changed)
  ● docker.lab: Retirer la confiance installée pour le moteur (changed)
  ● docker-client.lab: Retirer la résolution du registre (changed)
  ● docker.lab: Retirer la résolution du registre (changed)
  ● docker.lab: Retirer l'atelier et le relevé du banc (changed)
  ● docker-client.lab: Retirer l'atelier et le relevé du banc (changed)
⠹ cleanup.yaml terminé ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 14/? 0:00:03
✔ Nettoyage terminé.

Look at the ● lines: they are the tasks that actually removed something, the trust installed for the engine, the registry resolution and the workshop. Run again right afterwards, the same clean --yes passes all its tasks as ✔ (ok), and concludes with the same "Nettoyage terminé" (Cleanup finished): clean can be replayed without risk.

It is also clean that removes /opt/lab-livraison, the workshop that the lab's setup.yaml refuses to find already in place. The lesson Starting a dsoxlab lab with dsoxlab start shows this refusal at step 4 of start.

On a shell lab, the output is shorter:

$ dsoxlab clean lire-du-code --yes
ℹ Nettoyage de lire-du-code…
✔ Nettoyage terminé.

clean does not touch the marks either, and status does not change: a lab already marked stays "validé" (validated) with its best mark, and a lab with no mark stays "en cours" (in progress), since the preparation marker survives the cleanup. So do not read status as an indicator of the machine's state: it says where your mark stands.

The difference between reset and clean is read on the machine, not in status. reset puts the lab back at its start, ready to replay. clean frees it without replaying it.

How do you take the machines down with dsoxlab destroy?

dsoxlab destroy destroys the catalogue's infrastructure, after confirmation, orphan machines included. An orphan machine is a machine that a failed provision left outside the Terraform state, that is, outside the list that Terraform keeps of its machines. It is the end-of-session command on a vm lab: without it, the machines consume memory and disk long after the lab is over. The question asked names the provider (what runs the machines, here kvm), and --yes suppresses it.

dsoxlab destroy
dsoxlab destroy --yes
dsoxlab destroy --host docker.lab

Here is the question, with the n answer, then the actual destruction with --yes on the two machines of the containers catalogue:

$ dsoxlab destroy
Détruire toute l'infrastructure du provider kvm ? Les données des VM seront perdues [y/N]: n
Aborted.

$ dsoxlab destroy --yes
ℹ Destruction de l'infrastructure (provider : kvm)…

  ✔ host["docker.lab"] (1s)
  ✔ host["docker-client.lab"] (1s)
  ✔ cloudinit["docker.lab"] (0s)
  ✔ cloudinit["docker-client.lab"] (0s)
  ✔ host["docker-client.lab"] (0s)
  ✔ host["docker.lab"] (0s)
  ✔ host["docker-client.lab"] (0s)
  ✔ host["docker.lab"] (0s)
  ✔ lab (0s)
  ✔ base_image["debian13"] (0s)
  Destroying terminé ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 10/10 0:00:02
ℹ Fragment SSH de containers-dsoxlab-training retiré : il pointait des machines
détruites.
ℹ Le socle du catalogue est oublié : le prochain provision le reposera.
✔ Infrastructure détruite.

Look at the last three lines. The catalogue's SSH fragment is removed (ssh <machine> no longer works), the catalogue's foundation is forgotten, so the next provision replays it, and the infrastructure is destroyed. The 10/10 counter counts the Terraform resources destroyed, machines included.

The command first purges the disk restore points, then plays terraform destroy. It then checks the hypervisor (the software that runs the virtual machines): Terraform does not see the orphan machines, but destroy removes them too, after a separate confirmation. It names the machines, asks for confirmation (unless --yes) and, if one of them cannot be removed, exits with code 6 giving the sudo virsh undefine command to type by hand. A destroy that announced success while leaving machines up would be worse than a failure.

The --host option targets one machine, and you need to know what it really promises: Terraform destroys the target and everything that depends on it. Since volumes and disks are chained to the machines, targeting one host can take the others with it, and the command warns you before acting. destroy never erases your marks or your hints: status says "validé, 75 / 100" again on a lab marked before the machines were destroyed.

How do you confirm without a terminal, with --yes?

reset, clean and destroy ask for confirmation, and --yes (or -y) answers in your place. In a script, with no terminal to answer, reset and clean without --yes do nothing: they explain that they need --yes and exit with code 2. Here is clean, run with the standard input connected to a pipe:

$ dsoxlab clean epreuve-livrer-une-image
✘ Cette commande demande une confirmation, et il n'y a pas de terminal pour la
donner. Relancez-la avec --yes pour confirmer sans question.

The message says the cause (no terminal) and the remedy (--yes), and the command exits with code 2. In a script, therefore, add --yes to the three commands (the first two here target the premiers-pas demonstration lab):

dsoxlab reset premiers-pas --yes
dsoxlab clean premiers-pas --yes
dsoxlab destroy --yes

Keep --yes for scripts and for cases where you know exactly what will be deleted. At the keyboard, the question is a useful protection: a destroy typed in the wrong repository would erase the whole fleet without it.

One last point: these three commands take a write lock on the catalogue, after the confirmation. If another dsoxlab command is already writing to the same catalogue, you get code 7 and the message names that command, which you just have to wait for.

Troubleshooting

None of these cases is a breakdown: the command asks for a confirmation, a lock or a file that the lab does not declare.

Symptom	Cause	Solution
clean or reset exits with code 2 and talks about --yes	No terminal to answer the confirmation	Run again with --yes
clean of a vm lab fails	The lab declares no cleanup.yaml playbook	Report it to the catalogue's author; destroy takes the machines down
destroy exits with code 6	An orphan machine could not be removed	Type the sudo virsh undefine command that the message gives
A command exits with code 7	Another dsoxlab command is writing to this catalogue	Wait for the named command to finish, then run again
The hints disappeared after reset	reset erases the lab's hints	This is intended; clean would have left them
The history disappeared	demo --force, catalog remove or catalog add --force	Be warned: these commands take the .dsoxlab.db with the marks

Swipe to see more

Key points

• reset puts the lab back in its initial state and erases the hints taken; clean deletes what the lab created and leaves the hints.
• Neither reset, nor clean, nor destroy touches the recorded marks.
• demo --force, catalog remove and catalog add --force take marks and hints away.
• destroy takes the machines down, orphans included, and exits with code 6 if any remain.
• destroy --host is not a fine-grained target: Terraform also destroys what depends on the target.
• --yes answers the confirmation; with no terminal and no --yes, reset and clean exit with code 2.
• After destroy, the next provision replays the catalogue's foundation.

Knowledge check

Check that you have the essentials of this guide. The questions only cover what has just been explained here.

Knowledge check

Check what you have learned with this interactive quiz

8 questions

6 min

70% to pass

How it works

• The timer starts when you click Start
• Multiple choice, true/false and short answer questions
• You can move between questions
• Detailed results are shown at the end

Start the quiz

Starts the quiz and the timer

×

See in the glossary →