Create logically bound images

You can create logically bound images by using podman Quadlet .image or .container files to link application container images to the lifecycle of a base bootc image. This allows you to manage applications and the operating system as a cohesive unit.

Before you begin

  • The container-tools meta-package is installed.

Procedure

  1. Select the image that you want to logically bound.
  2. Create a Containerfile:
    $ cat Containerfile
    FROM quay.io/<namespace>/<image>:latest
    COPY ./<app_1>.image /usr/share/containers/systemd/<app_1>.image
    COPY ./<app_2>.container /usr/share/containers/systemd/<app_2>.container
    
    RUN ln -s /usr/share/containers/systemd/<app_1>.image \
    	/usr/lib/bootc/bound-images.d/<app_1>.image && \
        ln -s /usr/share/containers/systemd/<app_2>.container \
        	/usr/lib/bootc/bound-images.d/<app_2>.container
  3. In the .container definition, use:
    GlobalArgs=--storage-opt=additionalimagestore=/usr/lib/bootc/storage

    In the Containerfile example, the image is selected to be logically bound by creating a symlink in the /usr/lib/bootc/bound-images.d directory pointing to either an .image or a .container file.

  4. Run the bootc upgrade command.
    $ bootc upgrade

    The bootc upgrade performs the following overall steps:

    1. Fetches the new base image from the image repository. See Configure container pull secrets.
    2. Reads the new base image root file system to discover logically bound images.
    3. Automatically pulls any discovered logically bound images defined in the new bootc image into the bootc-owned /usr/lib/bootc/storage image storage.
  5. Make the bound images become available to container runtimes such as Podman. For that, you must explicitly configure bound images to point to the bootc storage as an "additional image store". For example:
                podman --storage-opt=additionalimagestore=/usr/lib/bootc/storage run <image>
              
    Important

    Do not attempt to globally enable the /usr/lib/bootc/storage image storage in /etc/containers/storage.conf. Only use the bootc storage for logically bound images. The bootc image store is owned by bootc. The logically bound images will be garbage collected when they are no longer referenced by a file in the /usr/lib/bootc/bound-images.d directory.