From 4ac5364f669ec63837f3a2e426d35d3133c41f23 Mon Sep 17 00:00:00 2001 From: Colin Walters Date: Thu, 30 May 2024 13:02:34 -0400 Subject: [PATCH] docs: Add `containers-storage-architecture.md` I'd find it really useful to have a document with the implementation details of containers-storage (really just the overlay driver). I started on this, using some of the source code. Is there already Signed-off-by: Colin Walters --- docs/containers-storage-architecture.md | 76 +++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 docs/containers-storage-architecture.md diff --git a/docs/containers-storage-architecture.md b/docs/containers-storage-architecture.md new file mode 100644 index 0000000000..2eb3172546 --- /dev/null +++ b/docs/containers-storage-architecture.md @@ -0,0 +1,76 @@ +## containers-storage 1 "May 2024" + +## NAME +containers-storage-architecture - The implementation of containers-storage + +NOTE: These are implementation details subject to change. This document +is intended to be used only as an aid for debugging and development +of the containers-storage system. Do *not* directly access the filesystem +components below from external code, only from the Go API. + +## DESCRIPTION +The *containers/storage* library manages the following object types: + +- layer: A filesystem tree, along with metadata +- image: A reference to a layer, along with metadata +- container: A layer whose parent is an image + +## Layer storage + +### `overlay/` + +The `overlay/` directory contains a set of layers, named +by their digest (note, this is the "diffid" or *uncompressed* +digest, not the compressed one). + +### layer: + +A layer has the following components: + +- `diff/`: The expanded filesystem tree +- `work/`: A directory used by `overlayfs` mounts +- `merged/`: This will be a mount point when a layer is mounted. +- `link`: A regular file; this contains a unique string for the layer; see `l/` below. +- `lower`: Contains all the lower layer mounts separated by ":" and ordered from uppermost to lowermost layers. + +### `l/`: Layer shortlinks + +The`l` directory at the root there will be a symbolic link +with that unique string pointing the "diff" directory for layers. +The symbolic links are used to reference lower layers in the "lower" +file and on mount. The links are used to shorten the total length +of a layer reference without requiring changes to the layer identifier +or root directory. Mounts are always done relative to root and +referencing the symbolic links in order to ensure the number of +lower directories can fit in a single page for making the mount +syscall. A hard upper limit of 500 lower layers is enforced to ensure +that mounts do not fail due to length. + +### `overlay-layers/` + +This directory contains metadata for layers. + +#### `layers.lock` + +Lockfile protecting reads and writes to this directory. + +#### `${layerid}.tar-split.gz` + +Each layer will have a `${layerid}.tar-split.gz` file containing the +original input tar stream without file content; this is necessary +to be able to reconstruct the original tar stream exactly after +a layer content has been unpacked into `diff/`. More in + + +#### `layers.json` + +Global list of metadata associated with layers. + +#### `volatile-layers.json` + +Like `layers.json`, but used for layers which are defined not to +persist across reboots. + +### storage.lock + +A cross-process lockfile, protecting overall layer state.