Expand description
Docker housekeeping — dangling and stale images, idle build cache, and optionally volumes — followed by handing the freed blocks back to the host when the daemon lives in a VM.
docker is a daemon on the other end of a socket, which is why none of this is on by default:
a sweep that talks to it runs a command with side effects on state voom did not scan. The
design is in adrs/0017-docker-housekeeping.md; the rules that matter here are:
- Nothing a container touches. Stopped containers are never removed, because they can hold state; an image any container was made from, running or not, is kept; a volume any container mounts is kept. Volumes are data and are off unless asked for twice over.
- A dry run is the same plan.
prunebuilds the lane plans from onedocker system df -vinventory whether or not it will run them, and the dry run withholds only the commands. - It never fails the sweep. A missing binary, a stopped daemon or a refused socket is a
Skipwith a one-line reason; a prune that errors is a failed lane in the report.
Like crate::bazel this is machine-global and shares nothing with the sweep, so it runs
beside it and reports after.
Structs§
- Docker
Prune Options - What to prune, and under what conditions.
- Docker
Prune Result - Everything one round produced.
- Lane
- One lane’s plan beside what came of it.
- Lane
Plan - One independent unit of work: what it would remove, and the commands that do it.
- Skip
- Why nothing was done. Always a reason to say and move on, never an error.
- Totals
- The footer’s numbers.
- Trim
- What happened, or would happen, to the guest’s free blocks.
Enums§
- Backend
- Where the daemon runs.
- Lane
Kind - The three things a prune can reclaim.
- Lane
Outcome - What happened in one lane.
- Trim
Outcome - The result of a trim.
- Volume
Scope - Which volumes
--docker-volumesand--docker-volumes-allmay remove.
Constants§
- DEFAULT_
MAX_ AGE - How old an unused image or an idle cache record must be before it is pruned.
- DEFAULT_
TIMEOUT - How long one prune command or the VM trim may run. Pruning tens of gigabytes of layers, or trimming a large sparse disk, is minutes; an hour would be a hung daemon.
- DISK_
IMAGES_ ENV - Replaces the guessed host disk image paths, a platform path list (
:on Unix). The measurement is the only thing it changes; which command trims is still decided by the backend. - SCHEMA_
VERSION - The JSON shape’s version, versioned separately from the sweep’s because it is a separate document sharing only the envelope.
Functions§
- allocated_
bytes - Bytes the host actually has allocated for these files, summed:
st_blocks, not the apparent length, because a sparse disk image’s length never changes.Nonewhen none exist or the platform has no such measure. - document
- Builds the JSON document.
- prune
- Inventories the daemon, then prunes what
DockerPruneOptionsallows, then trims the VM. - render_
human - Renders the subcommand’s human report. A skipped run is one line.
- render_
json - Renders the document as pretty-printed JSON.