Logically-bound image pull reliability improvements

[jeckersb]

Discussed in #2011

^{Originally posted by csssuf February 18, 2026}
As I've been working with logically-bound images, I've encountered a couple of challenges around reliability. These can more or less be summed up by saying that errors pulling LBIs are not really handled, which makes it tough to rely on bootc switch/upgrade when LBIs are involved.

The two main challenges are:

• If an LBI cannot be pulled, there is no clean way to retry it.
• If any LBIs fail to be pulled, the new deployment is still staged for next boot.

These two issues combine to make updates with any LBI changes nearly impossible to apply atomically - we expect LBIs to be available immediately on boot, but we cannot retry them if the initial fetch fails. Right now, we're working around this by using physically-embedded images, but this is painful for other reasons (we lose the layering from the embedded images, so updates are huge, and loading images into c/storage is fallible at boot-time).

I'm not sure what the best option here is - off the top of my head, it seems safest to unstage a deployment (if this is possible) if we can't fetch its LBIs; that way, we're back in the state we started in and it's up to the caller to retry the bootc operation that failed.

[p5]

(Not a bootc maintainer)

If any LBIs fail to be pulled, the new deployment is still staged for next boot.

Just from my usage of LBIs, I believe this is the right behaviour if the LBIs are referencing mutable tags (i.e. :latest, :stable etc) that match the image in local storage, rather than the specific image digest. The desired state defined in the LBI is still satisfied by the already cached image.

However if the LBI references a specific digest or a tag which differs to the one currently in storage, and that image cannot be pulled, the desired state for the update is not met, and the deployment should not be staged. I have not checked how this situation behaves currently.

In other words
If the .image file points to registry.com/image:latest
and the locally cached image is registry.com/image:latest@sha256:123
and the new remote image is registry.com/image:latest@sha256:456
then the update should continue if the pull failed.

If the .image file points to registry.com/image:v1.2.3
and the locally cached image is registry.com/image:v1.2.2
and the new remote image is registry.com/image:v1.2.3
then the update should fail.