Add a basic man page for each driver and a simple module doc #646
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add doc comments to the overlay, vfs, btrfs, and zfs storage driver packages describing their implementation approach: - overlay: Uses Linux OverlayFS with composefs option for integrity - vfs: Copies directories, attempting reflinks first for efficiency - btrfs: Uses native subvolumes and snapshots with qgroup quotas - zfs: Uses datasets and clones with mountpoint=legacy Assisted-by: OpenCode (Opus 4.5) Signed-off-by: Colin Walters <[email protected]>
Create dedicated documentation files for each storage driver: - containers-storage-driver-overlay.md (includes zstd:chunked and composefs) - containers-storage-driver-vfs.md - containers-storage-driver-btrfs.md - containers-storage-driver-zfs.md The composefs and zstd:chunked documentation is consolidated into the overlay driver doc since these are overlay-specific features. Assisted-by: OpenCode (Opus 4.5) Signed-off-by: Colin Walters <[email protected]>
cgwalters
force-pushed
the
driver-docs
branch
from
2e09ff5 to
6050320
Compare
|
Packit jobs failed. @containers/packit-build please check. |
| The on-disk file layout is an internal implementation detail and may change between versions. The only stable interface is the Go library API. | ||
| The description below is intended to aid debugging and recovery, but changing content directly is not supported. | ||
|
|
||
| The top-level overlay directory holds layers keyed by a [chain ID](https://github.com/opencontainers/image-spec/blob/main/config.md#layer-chainid) which identifies the precise sequence of parent layers leading to this one. A layer with the same DiffID can have multiple physical objects in this directory if it was created in different contexts (e.g. with or without zstd:chunked). |
Member
There was a problem hiding this comment.
Suggested change
| The top-level overlay directory holds layers keyed by a [chain ID](https://github.com/opencontainers/image-spec/blob/main/config.md#layer-chainid) which identifies the precise sequence of parent layers leading to this one. A layer with the same DiffID can have multiple physical objects in this directory if it was created in different contexts (e.g. with or without zstd:chunked). | |
| The top-level overlay directory holds layers keyed by a [chain ID](https://github.com/opencontainers/image-spec/blob/main/config.md#layer-chainid), which identifies the precise sequence of parent layers leading to this one. A layer with the same DiffID can have multiple physical objects in this directory if it was created in different contexts (e.g., with or without zstd:chunked). |
|
|
||
| ## RUNTIME | ||
|
|
||
| When a container needs its filesystem, the driver performs a `mount(2)` with type `overlay`, passing the layer's `diff` directory as the upperdir and all parent layers' `diff` directories as lowerdirs. The kernel's overlayfs merges these at access time — no data is copied, and layers remain independent on disk. Writes go to the upperdir via copy-up. The mount is placed at the layer's `merged` directory, and the `work` directory is used internally by overlayfs for atomic operations like rename. |
Member
There was a problem hiding this comment.
Suggested change
| When a container needs its filesystem, the driver performs a `mount(2)` with type `overlay`, passing the layer's `diff` directory as the upperdir and all parent layers' `diff` directories as lowerdirs. The kernel's overlayfs merges these at access time — no data is copied, and layers remain independent on disk. Writes go to the upperdir via copy-up. The mount is placed at the layer's `merged` directory, and the `work` directory is used internally by overlayfs for atomic operations like rename. | |
| When a container needs its filesystem, the driver performs a `mount(2)` with type `overlay`, passing the layer's `diff` directory as the upperdir and all parent layers' `diff` directories as lowerdirs. The kernel's overlayfs merges these at access time — no data is copied, and layers remain independent on disk. Writes go to the upperdir via copy-up. The mount is placed in the layer's `merged` directory, and the `work` directory is used internally by overlayfs for atomic operations such as rename. |
|
|
||
| ## RUNTIME | ||
|
|
||
| There is no mount involved. When a container needs its filesystem, `Get()` simply returns the layer's directory path. All layer merging happened at create time when the parent was copied, so the directory is already a complete filesystem tree. `Put()` is a no-op since there is nothing to unmount. |
Member
There was a problem hiding this comment.
Suggested change
| There is no mount involved. When a container needs its filesystem, `Get()` simply returns the layer's directory path. All layer merging happened at create time when the parent was copied, so the directory is already a complete filesystem tree. `Put()` is a no-op since there is nothing to unmount. | |
| There is no mount involved. When a container needs its filesystem, `Get()` simply returns the layer's directory path. All layer merging occurs at create time, when the parent is copied, so the directory is already a complete filesystem tree. `Put()` is a no-op since there is nothing to unmount. |
Member
TomSweeneyRedHat
left a comment
TomSweeneyRedHat
left a comment
There was a problem hiding this comment.
A few nitty suggestions for consideration or to be ignored. Otherwise:
LGTM
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is a redo of containers/storage#1933 but this time
Assisted-by: OpenCode (Opus 4.6). Main motivation is just helping people who need to look at this (e.g. debugging, forensics) without digging deep into source code, and obviously would be useful for PoC work like containers/composefs-rs#218