docs: Add (not installed) man pages for composefs and zstd:chunked
These aren't installed yet so they'll just live in the git repository but hopefully we can expand them and use them as a central reference point for "how do I do (zstd:chunked)|(composefs)". We have copies of that kind of instruction in other downstream places but I think here makes the most sense. Signed-off-by: Colin Walters <walters@verbum.org>
This commit is contained in:
parent
39d469c34c
commit
0b440b9b56
|
|
@ -0,0 +1,38 @@
|
||||||
|
## containers-storage 1 "August 2024"
|
||||||
|
|
||||||
|
## NAME
|
||||||
|
containers-storage-composefs - Information about composefs and containers/storage
|
||||||
|
|
||||||
|
|
||||||
|
## DESCRIPTION
|
||||||
|
|
||||||
|
To enable composefs at a baseline requires the following configuration in `containers-storage.conf`:
|
||||||
|
|
||||||
|
```
|
||||||
|
[storage.options.overlay]
|
||||||
|
use_composefs = "true"
|
||||||
|
```
|
||||||
|
|
||||||
|
However at the current time, composefs requires zstd:chunked images, so first
|
||||||
|
you must be sure that zstd:chunked is enabled. For more, see [zstd:chunked](containers-storage-zstd-chunked.md).
|
||||||
|
|
||||||
|
Additionally, not many images are in zstd:chunked format. In order to bridge this gap,
|
||||||
|
`convert_images = "true"` can be specified which does a dynamic conversion; this adds
|
||||||
|
latency to image pulls.
|
||||||
|
|
||||||
|
Putting these things together, the following is required (in addition to the above config).
|
||||||
|
|
||||||
|
```
|
||||||
|
pull_options = {enable_partial_images = "true", use_hard_links = "false", ostree_repos="", convert_images = "true"}
|
||||||
|
```
|
||||||
|
|
||||||
|
## BUGS
|
||||||
|
|
||||||
|
- https://github.com/containers/storage/issues?q=is%3Aissue+is%3Aopen+label%3Aarea%2Fcomposefs
|
||||||
|
|
||||||
|
## FOOTNOTES
|
||||||
|
The Containers Storage project is committed to inclusivity, a core value of open source.
|
||||||
|
The `master` and `slave` mount propagation terminology is used in this repository.
|
||||||
|
This language is problematic and divisive, and should be changed.
|
||||||
|
However, these terms are currently used within the Linux kernel and must be used as-is at this time.
|
||||||
|
When the kernel maintainers rectify this usage, Containers Storage will follow suit immediately.
|
||||||
|
|
@ -0,0 +1,43 @@
|
||||||
|
## containers-storage 1 "August 2024"
|
||||||
|
|
||||||
|
## NAME
|
||||||
|
containers-storage-zstd-chunked - Information about zstd:chunked
|
||||||
|
|
||||||
|
|
||||||
|
## DESCRIPTION
|
||||||
|
|
||||||
|
The traditional format for container image layers is [application/vnd.oci.image.layer.v1.tar+gzip](https://github.com/opencontainers/image-spec/blob/main/layer.md#gzip-media-types).
|
||||||
|
More recently, the standard was augmented with zstd: [application/vnd.oci.image.layer.v1.tar+zstd](https://github.com/opencontainers/image-spec/blob/main/layer.md#zstd-media-types)
|
||||||
|
which is a more modern and efficient compression format.
|
||||||
|
|
||||||
|
`zstd:chunked` is a variant of the `application/vnd.oci.image.layer.v1.tar+zstd` media type that
|
||||||
|
uses zstd [skippable frames](https://github.com/facebook/zstd/blob/dev/doc/zstd_compression_format.md#skippable-frames)
|
||||||
|
to include additional metadata (especially a "table of contents") that includes the SHA-256 and offsets of individual chunks of files.
|
||||||
|
Additionally chunks are compressed separately. This allows a client to dynamically fetch only content which
|
||||||
|
it doesn't already have using HTTP range requests.
|
||||||
|
|
||||||
|
To enable zstd:chunked requires the following changes to `containers-storage.conf`:
|
||||||
|
|
||||||
|
```
|
||||||
|
pull_options = {enable_partial_images = "true", use_hard_links = "false", ostree_repos=""}
|
||||||
|
```
|
||||||
|
|
||||||
|
This option may or may not be enabled by default in your distribution/operating system.
|
||||||
|
|
||||||
|
## INTERNALS
|
||||||
|
|
||||||
|
At the current time the format is not officially standardized or documented beyond
|
||||||
|
the comments and code in the reference implementation. At the current time
|
||||||
|
the file with the most information is [pkg/chunked/internal/compression.go](https://github.com/containers/storage/blob/39d469c34c96db67062e25954bc9d18f2bf6dae3/pkg/chunked/internal/compression.go).
|
||||||
|
The above is a permanent link for stability, but be sure to check to see if there are newer changes too.
|
||||||
|
|
||||||
|
## BUGS
|
||||||
|
|
||||||
|
- https://github.com/containers/storage/issues?q=is%3Aissue+label%3Aarea%2Fzstd%3Achunked+is%3Aopen
|
||||||
|
|
||||||
|
## FOOTNOTES
|
||||||
|
The Containers Storage project is committed to inclusivity, a core value of open source.
|
||||||
|
The `master` and `slave` mount propagation terminology is used in this repository.
|
||||||
|
This language is problematic and divisive, and should be changed.
|
||||||
|
However, these terms are currently used within the Linux kernel and must be used as-is at this time.
|
||||||
|
When the kernel maintainers rectify this usage, Containers Storage will follow suit immediately.
|
||||||
Loading…
Reference in New Issue