diff --git a/docs/src/experimental-logically-bound-images.md b/docs/src/experimental-logically-bound-images.md index 306c9a2a2..224c90974 100644 --- a/docs/src/experimental-logically-bound-images.md +++ b/docs/src/experimental-logically-bound-images.md @@ -7,7 +7,18 @@ Tracking issue: ## About logically bound images -This experimental feature enables an association of container "app" images to a bootc system image. A similar approach to this is [physically bound](https://github.com/containers/bootc/issues/644) images. There are some trade-offs between the two approaches. Some benefits of logically bound images are: +This experimental feature enables an association of container "app" images to a base bootc system image. Use cases for this include: + +- Logging (e.g. journald->remote log forwarder container) +- Monitoring (e.g. [Prometheus node_exporter](https://github.com/prometheus/node_exporter)) +- Configuration management agents +- Security agents + +These types of things are commonly not updated outside of the host, and there's a secondary important property: We *always* want them present and available on the host, possibly from very early on in the boot. In contrast with default usage of tools like `podman` or `docker`, images may be pulled dynamically *after* the boot starts; requiring functioning networking, etc. For example if the remote registry is unavailable temporarily, the host system may run for a longer period of time without log forwarding or monitoring, which can be very undesirable. + +Another simple way to say this is that logically bound images allow you to reference container images with the same confidence you can with `ExecStart=` in a systemd unit. + +The term "logically bound" was created to contrast with [physically bound](https://github.com/containers/bootc/issues/644) images. There are some trade-offs between the two approaches. Some benefits of logically bound images are: - The bootc system image can be updated without re-downloading the app image bits. - The app images can be updated without modifying the bootc system image, this would be especially useful for development work @@ -42,7 +53,19 @@ GlobalArgs=--storage-opt=additionalimagestore=/usr/lib/bootc/storage Images are fetched using the global bootc pull secret by default (`/etc/ostree/auth.json`). It is not yet supported to configure `PullSecret` in these image definitions. +## Garbage collection + +The bootc image store is owned by bootc; images will be garbage collected when they are no longer referenced +by a file in `/usr/lib/bootc/bound-images.d`. + ## Limitations -- Currently, only the Image field of a `.image` or `.container` file is used to pull the image; per above not even `PullSecret=` is supported. -- Images are not yet garbage collected +The *only* field parsed and honored by bootc currently is the `Image` field of a `.image` or `.container` file. + +Other pull-relevant flags such as `PullSecret=` for example are not supported (see above). +Another example unsupported flag is `Arch` (the default host architecture is always used). + +There is no mechanism to inject arbitrary arguments to the `podman pull` (or equivalent) +invocation used by bootc. However, many properties used for container registry interaction +can be configured via [containers-registries.conf](https://github.com/containers/image/blob/main/docs/containers-registries.conf.5.md) +and apply to all commands operating on that image.