diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index be995b26b..68ce4e809 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -47,6 +47,7 @@ # Experimental features - [bootc image](experimental-bootc-image.md) +- [logically bound images](experimental-logically-bound-images.md) # More information diff --git a/docs/src/experimental-logically-bound-images.md b/docs/src/experimental-logically-bound-images.md new file mode 100644 index 000000000..3a09b8a67 --- /dev/null +++ b/docs/src/experimental-logically-bound-images.md @@ -0,0 +1,35 @@ +# Logically Bound Images + +Experimental features are subject to change or removal. Please +do provide feedback on them. + +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: + +- 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 + +## Using logically bound images + +Each image is defined in a [Podman Quadlet](https://docs.podman.io/en/latest/markdown/podman-systemd.unit.5.html) `.image` or `.container` file. An image is selected to be bound by creating a symlink in the `/usr/lib/bootc-experimental/bound-images.d` directory pointing to a `.image` or `.container` file. With these defined, during a `bootc upgrade` or `bootc switch` the bound images defined in the new bootc image will be automatically pulled via podman. + +An example Containerfile + +```Dockerfile +FROM quay.io/myorg/myimage:latest + +COPY ./my-app.image /usr/share/containers/systemd/my-app.image +COPY ./another-app.container /usr/share/containers/systemd/another-app.container + +RUN ln -s /usr/share/containers/systemd/my-app.image /usr/lib/bootc-experimental/bound-images.d/my-app.image && \ + ln -s /usr/share/containers/systemd/my-app.image /usr/lib/bootc-experimental/bound-images.d/my-app.image +``` + +## Limitations + +- Currently, only the Image field of a `.image` or `.container` file is used to pull the image. Any other field is ignored. +- There is no cleanup during rollback. +- Images are subject to default garbage collection semantics; e.g. a background job pruning images without a running container may prune them. They can also be manually removed via e.g. podman rmi.