be more explicit about multiple image references for oci #1416
Conversation
[CI:DOCS] Signed-off-by: Lokesh Mandvekar <[email protected]>
lsm5
force-pushed
the
oci-image-ref-doc-update
branch
from
66cb164
to
2d03682
Compare
|
does [CI:DOCS] need to be in the commit title? I added it to the commit message body, but it's still going through CI. |
| @@ -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_. | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
@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 ?
There was a problem hiding this comment.
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.nameannotation.) - When reading images from
oci:oroci-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.)
|
The core of this PR has since been documented by #2042 ; #1416 (comment) contains a few more items that might be worth highlighting. |
I have filed #2468 for the missing part. Thanks for this PR! |
Signed-off-by: Lokesh Mandvekar [email protected]
@mtrmac @vrothberg @rhatdan PTAL.
RE: containers/skopeo#1513