From 0beb1e23207639c11c113f79f18d35bf1308aa70 Mon Sep 17 00:00:00 2001 From: "W. Trevor King" Date: Wed, 16 Nov 2016 07:40:12 -0800 Subject: [PATCH] image-layout: Require blobs/refs to exist but allow them to be empty The previous wording ("has" and "contains") was not clear enough to avoid confusion [1]. I consider this PR to be a spec clarification, and not a spec change, but others will probably disagree [2] (which is why I think we need the clarification). If you cared about running images from the layout, you'd need "and there MUST be at least one unpackable ref" language. And then you have to match the oci-layout version with the media types that were unpackable when it was current (or is validity in the eye of the validator?)... This is a bowl that I do not want to fathom ;). Maybe folks are just using an image-layout to ship some missing blobs (and have refs empty). I don't see any incentive to image-authors to publish ref-less blobs and then pretend they are runnable, so I don't see a need to get into the business of restricting refs. Or maybe they're shipping some missing refs (and have blobs empty). Maybe they expect all blobs to be fetched via the descriptor's 'urls'. Those sound fine to me too, so I don't think we should be in the business of restricting blobs (and we already have "The blobs directory MAY be missing referenced blobs..."). I am fine with validation code *warning* users about either case (e.g. "this image-layout has no refs" or "refs a, b, and c require blobs which are not stored in this image-layout"), but I don't think the spec should block either of those. [1]: https://github.com/opencontainers/image-spec/issues/287 [2]: https://github.com/opencontainers/image-tools/pull/83#issuecomment-260841249 Signed-off-by: W. Trevor King --- image-layout.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/image-layout.md b/image-layout.md index 7dc415fbc..92d96c5c4 100644 --- a/image-layout.md +++ b/image-layout.md @@ -9,15 +9,18 @@ Given an image layout and a ref, a tool can create an [OCI Runtime Specification * [Applying the filesystem layers](layer.md#applying) in the specified order * Converting the [image configuration](config.md) into an [OCI Runtime Specification `config.json`](https://github.com/opencontainers/runtime-spec/blob/v1.0.0-rc2/config.md) -The image layout has two top level directories: +The image layout MUST contain two top level directories: -- "blobs" contains content-addressable blobs. A blob has no schema and should be considered opaque. -- "refs" contains [descriptors][descriptors]. Commonly pointing to an [image manifest](manifest.md#image-manifest) or an [image manifest list](manifest-list.md#oci-image-manifest-list-specification). +- `blobs` contains content-addressable blobs. + A blob has no schema and should be considered opaque. +- `refs` contains [descriptors][descriptors]. + Commonly pointing to an [image manifest](manifest.md#image-manifest) or an [image manifest list](manifest-list.md#oci-image-manifest-list-specification). +Both `blobs` and `refs` MAY be empty. -It also contains a file that is used to identify the layout version: +The image layout MUST also contain a file that is used to identify the layout version: -- "oci-layout" MUST contain a JSON object with a version field `{"imageLayoutVersion": "1.0.0"}` and MAY include additional fields. +- `oci-layout` MUST contain a JSON object with a version field `{"imageLayoutVersion": "1.0.0"}` and MAY include additional fields. This is an example image layout: