A shell lab costs nothing beyond your own machine; a vm lab costs the sum
of the machines its catalogue declares, because dsoxlab provision brings
them all up at once. The Kubernetes catalogue thus declares two
machines, 6656 MB of memory and 4 virtual CPUs, the Linux catalogue three
machines and 5120 MB. This lesson reads those figures at the source, the
meta.yml file of each catalogue, and explains what dsoxlab doctor does with
them, in version 0.2.5, before letting you provision. It is written for anyone
who wants to know, before installing a hypervisor, whether their machine will
be enough.
What you will learn
- Tell
shelllabs, which are free, fromvmlabs, which bring up machines. - Read in a
meta.ymlwhat a catalogue requires, and the contract's default values. - Quantify the Linux, Ansible, Kubernetes and Terraform catalogues, as published.
- Understand why the declared disk is not the disk consumed.
- Plan the margin the CPU imposes, and what
doctorrefuses.
Two kinds of labs, and only the first is free
A shell lab is played in a directory of your machine: the demonstration
lab is one, and so is the whole Terraform catalogue. It requires neither a
hypervisor nor reserved memory. A vm lab starts real virtual machines
next to you, because what it makes you prove, an AppArmor profile, a
kubeadm upgrade, a systemd service that survives a reboot, cannot be
proved in a container that shares the host's kernel.
A third situation exists, halfway between the two: a shell lab that declares
services in containers, such as a cloud emulator or a database, requires
Docker without requiring a hypervisor. Eleven labs of the Terraform
catalogue are in that case, and it is for them that doctor classes Docker as
required there.
Where to read what a catalogue requires
Everything is written in the infra: block of the meta.yml, at the root
of the catalogue's repository, and nowhere else: a catalogue ships no
Terraform, it declares its hosts and dsoxlab does the rest. Every entry of
infra.hosts carries four figures, and the contract sets their
default value when the author does not write them:
| Field | Default | What it declares |
|---|---|---|
ram_mb | 1024 | The machine's memory, in MB |
vcpu | 1 | The number of virtual CPUs |
disk_gb | 10 | The size of the system disk, in GB |
extra_disk_gb | 0 | A second disk, for labs that require a real block device: partitioning, LVM, RAID, quotas |
The Kubernetes catalogue, for instance, declares its control plane this way, and comments its choice: kubeadm refuses to initialise below two CPUs, and the control plane carries etcd, the API server and, during the diagnosis labs, Pods that are broken on purpose.
# meta.yml of the kubernetes-dsoxlab-training catalogue, excerptinfra: provider: - kvm - incus network: lab-k8s hosts: - name: k8s-cp.lab distro: ubuntu24 role: control-plane ram_mb: 4096 vcpu: 2 disk_gb: 25 - name: k8s-w1.lab distro: ubuntu24 role: worker ram_mb: 2560 vcpu: 2 disk_gb: 20Two commands save you from opening the file. dsoxlab doctor carries a
RAM / disk resources check that adds up those declarations and compares
them with what the machine offers; dsoxlab show <id> says, for a given lab,
its runtime and its target. The first decides, the second informs.
What each catalogue declares
The totals below come from the published meta.yml files, read on
2026-09-26. They count all the machines of the catalogue, because
dsoxlab provision applies the whole plan by default: a three-host catalogue
brings up three machines, even if today's lab only targets one. The disk is the
sum of the disk_gb and extra_disk_gb values, and it reads as a ceiling,
for the reason explained right after.
| Catalogue | Labs | Machines | Memory | vCPU | Declared disk | Providers |
|---|---|---|---|---|---|---|
Linux (linux) | 86, of which 66 vm | 3: two AlmaLinux 10, one Ubuntu 24.04 | 5120 MB | 4 | 65 GB, of which 15 GB of extra disks | kvm, incus, outscale |
Ansible (ansible) | 113, of which 88 vm | 4: one control node and three managed nodes, all AlmaLinux 9 | 5632 MB | 5 | 60 GB, of which 5 GB extra | kvm |
| Kubernetes (by URL) | 64, all vm | 2: one control plane and one worker, Ubuntu 24.04 | 6656 MB | 4 | 45 GB | kvm, incus |
Terraform (terraform) | 88, all shell | none | none | none | none | no infra: block |
The Terraform catalogue has no infra: block, by design: Terraform runs
on the learner's machine, so all its labs are shell and dsoxlab provision
is never called there. Its prerequisites are of another kind, and its
meta.yml names them: terraform on the PATH for every lab, libvirt and
the dmacvicar/libvirt provider for the single section on first
infrastructures, and floci, a local AWS emulator, for the AWS section.
The declared disk is not the disk consumed
The KVM template packaged in dsoxlab creates qcow2 volumes backed by a base image, and a qcow2 volume is allocated on demand: the 25 GB declared for the Kubernetes control plane are a ceiling the machine only reaches if it fills them. The measurement that set this rule comes from a user of the Linux catalogue: 65 GB declared for 3.2 GB actually used, on a machine that provisioned without the slightest hitch.
What really takes up space is first the base image of each distribution, downloaded once into the storage pool and shared by every machine that uses it, then the writes of each lab. A lab that formats a 10 GB extra disk or installs a cluster consumes more than a lab that edits three files, but none reaches the declared ceiling.
dsoxlab doctor takes that into account, and it is useful to know when reading
its report: it adds up the declared sizes and announces them as a
ceiling allocated on demand, but it does not turn it into a verdict. A
healthy installation is therefore not painted red because its volumes could in
theory fill the pool. Memory, on the other hand, keeps its verdict:
MemAvailable on one side, the sum of the ram_mb values on the other,
and the check fails when the second exceeds the first.
The CPU decides the delay, not only the speed
Memory is computed, the CPU is measured. After terraform apply,
dsoxlab provision waits for each host to answer over SSH, within a window of
180 seconds by default, adjustable through the DSOXLAB_HOST_READY_TIMEOUT
variable. A host that does not answer within that delay makes the command exit
with code 8: the infrastructure exists, but it is not usable as it stands,
and dsoxlab status says which one and why.
That is where the number of CPUs counts. The appliance is sized for 4 vCPU and 8 GB, and that is not a comfort margin: the three hosts of the Linux catalogue share 5120 MB of memory, but it is the CPU that decides whether they all answer inside the window allowed. A guest with 2 vCPU has already been seen reporting a host ready at 181 seconds, one second after the window closed. The remedy, when code 8 appears, is often more time or more vCPU, never a reinstall.
Planning your machine, by what you play
The total to plan for is made of three parts: the catalogue's machines,
the system that hosts them, and what you keep open next to them. In the
appliance, imported with 8192 MB, the 6656 MB of the Kubernetes catalogue
leave 1536 to the appliance's own system: playable, but with no margin, and
doctor will say so if MemAvailable drops below the demand. On a Linux
machine with KVM, the same arithmetic applies to the free memory of the whole
machine.
| What you want to play | What the machine hosting dsoxlab has to offer |
|---|---|
The demonstration lab, the Terraform catalogue, the shell labs of the other catalogues | No hypervisor; Docker for the eleven Terraform labs that declare a service |
The Linux or Ansible catalogue in vm labs | 4 vCPU and 8 GB for the guest that provisions; 5120 MB or 5632 MB of free memory for the machines themselves |
| The Kubernetes catalogue | The same 4 vCPU, and 6656 MB of free memory for the two machines, so an appliance or a machine that still has them after its own system |
| Several catalogues at once | The memory adds up: Linux and Kubernetes together is 11776 MB of machines. Each catalogue has its own libvirt network and its own Terraform state, so they coexist, but dsoxlab destroy on one before provisioning the other remains the cheapest habit |
On a computer with 8 GB in total, the appliance documentation is blunt:
bring the VM down to 4096 MB, play the shell labs, and leave the vm
labs to a better-equipped machine. With 16 GB or more, every published
catalogue fits, one at a time.
Troubleshooting
The three cases below are those where the machine, not the lab, is at fault. Each carries a message that names the gesture, and none is fixed by reinstalling dsoxlab.
| Symptom | Cause | Solution |
|---|---|---|
doctor says "RAM: … available for … declared" as a required check | Free memory is below the sum of the catalogue's ram_mb values | Close what consumes, enlarge the VM hosting dsoxlab, or play shell labs |
provision exits with code 8, a host did not answer | The CPU was not enough to start every host within 180 seconds | Run provision again, give the machine more vCPU, or lengthen DSOXLAB_HOST_READY_TIMEOUT |
provision fails on Pool Not Found | On a fresh libvirt installation, no default storage pool exists | dsoxlab doctor prints the commands that create it; or declare storage_pool under infra.providers.kvm in the meta.yml |
Key points
- A
shelllab costs nothing; avmlab costs every machine of the catalogue, brought up at once byprovision. - The figures live in
infra.hostsof themeta.yml, with 1024 MB, 1 vCPU and 10 GB by default when the author says nothing. - Read on 2026-09-26: Linux 5120 MB and 4 vCPU on 3 machines, Ansible 5632 MB and 5 vCPU on 4, Kubernetes 6656 MB and 4 vCPU on 2, Terraform nothing at all.
- The declared disk is a ceiling: qcow2 volumes allocated on demand, 65 GB declared for 3.2 GB used on the Linux catalogue.
- Memory decides the verdict of
doctor, the CPU decides whether the hosts answer within 180 seconds. - An appliance at 8192 MB plays Kubernetes with no margin; a machine with 8 GB
sticks to
shelllabs.
Next steps
- Files, environment variables and exit codes: code 8, the
DSOXLAB_HOST_READY_TIMEOUTvariable and the location of the Terraform state, explained one by one. - Bringing up the infrastructure of vm labs: the
infra:block from the author's side, the choice of provider and the libvirt storage pool.