Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

be more explicit about multiple image references for oci #1416

Closed
wants to merge 1 commit into from
Closed

be more explicit about multiple image references for oci #1416

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/containers-transports.5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ The _algo:digest_ refers to the image ID reported by docker-inspect(1).
### **oci:**_path[:reference]_

An image compliant with the "Open Container Image Layout Specification" at _path_.
Using a _reference_ is optional and allows for storing multiple images at the same _path_.
Using a _reference_ is optional for a single image reference but required for storing multiple images at the same _path_.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not quite precise. It’s accessing an image from a multi-image archive that requires providing a disambiguating name; the code will happily enough add (untagged/unnamed) images to an archive, as the motivating bug report demonstrates.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mtrmac would you prefer an additional sentence and/or an example in the docs for clarifying the github issue case? Something like pulling multiple images without specification of reference will not preserve all references ?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

pulling multiple images without specification of reference will not preserve all references ?

I’m not quite sure what that means. (It’s a general principle of skopeo copy that names used in the source reference don’t affect names in the destination reference; it’s not something specific to this transport. So, copies by skopeo copy never “preserve” names/references in that sense — OTOH Podman does have various heuristics of that kind.)

The general kinds information we probably want to convey for the two transports:

  • (Maybe: The reference value corresponds to the org.opencontainers.image.ref.name annotation.)
  • When reading images from oci: or oci-archive:, if path contains multiple images, a reference must be specified to disambiguate; otherwise, the only image is implied.
  • When writing images, reference is optional and set on the written image [to allow disambiguating reads]
  • Repeated image writes to oci: don’t overwrite pre-existing images, whether or not reference is provided (but every reference will only point to one image).
  • Repeated image writes to oci-archive: overwrite the whole archive; only one image, the last written one, is included. (Do we want to guarantee that? Probably, ambiguity doesn’t help anyone, but I’m not 100% sure.)

(Warning: I didn’t actually test any of this right now, just reading the code.)


### **oci-archive:**_path[:reference]_

Expand Down