clarification about nested index #716

AkihiroSuda · 2017-07-28T04:23:03Z

Signed-off-by: Akihiro Suda [email protected]

jonjohnsonjr · 2017-07-28T04:56:46Z

What is meant by required? For whom?

There is pretty specific language here:
https://github.com/opencontainers/image-spec/blob/master/image-index.md

I don't see any reason to forbid an image index referencing another image index, but I'm curious what the use case would be.

AkihiroSuda · 2017-07-28T05:02:10Z

https://github.com/opencontainers/image-spec/blob/9e2ed30b411505b510b4ab080c4035d71bd56b44/image-layout.md says "This REQUIRED file"

jonjohnsonjr · 2017-07-28T05:46:05Z

Ah, thanks! My apologies, please ignore me :)

I guess I don't quite understand what is meant by "image providers" here:

While the use of an image index is OPTIONAL for image providers, image consumers SHOULD be prepared to process them.

Does that just refer to distribution in general? (I don't mean to hijack your PR but it seems like the <<optional>> bit traces back to this sentence, so it might be worth clarifying/removing as part of this PR?)

jonboulle · 2017-07-31T10:22:48Z

I also don't understand the use case for an image index to reference another image index. Notably this is not called out here in the actual index specification: https://github.com/opencontainers/image-spec/blame/master/image-index.md#L35

https://github.com/opencontainers/image-spec/blame/9e2ed30b411505b510b4ab080c4035d71bd56b44/image-layout.md#L148

I'm wondering if this line snuck in accidentally as the original context is very different:
9bb56d8#diff-99bfcb610f238b942638d49d1ff2eaf4R46

Here it refers to blobs in the ref directory, not the descriptors in the index file.

AkihiroSuda · 2017-07-31T12:45:23Z

@jonboulle

Yes, I'm +1 for removing nested index if it was introduced by accident.
WDYT about necessity of index?

jonboulle · 2017-07-31T13:34:46Z

I don't see a need for it but could be proven wrong.

AkihiroSuda · 2017-08-02T06:08:50Z

opened #718 and #719

AkihiroSuda · 2017-08-03T06:19:04Z

#718 and #719 were rejected.

Let me reopen this PR with updated docs.

AkihiroSuda · 2017-08-03T06:21:00Z

@jonboulle @stevvooe @vbatts @philips

wking · 2017-08-03T18:29:57Z

image-index.md

@@ -2,6 +2,7 @@

 The image index is a higher-level manifest which points to specific [image manifests](manifest.md), ideal for one or more platforms.
 While the use of an image index is OPTIONAL for image providers, image consumers SHOULD be prepared to process them.
+Also, the top-level index (`index.json`) is a REQUIRED file in [the image layout](image-layout.md).


I'd rather not have this line. This file/section is about defining the application/vnd.oci.image.index.v1+json media type, and should not be about where that media type is used.

I'd also encourage dropping the previous line for the same reason. Instead, requirements about what providers may/should/must supply and what consumers may/should/must consume should be handled in the referencing location. For example, you can see that application/vnd.oci.image.index.v1+json consumers MUST handle application/vnd.oci.image.manifest.v1+json in the context of manifests. And you'd see that consumers of image-layout v1.0.0 MUST handle application/vnd.oci.image.index.v1+json in the context of index.json around here (what I think you should be adding in this PR). And you'd see that consumers need not handle v1.0.0 image layouts here (which I think you should also be adding in this PR).

Yes, this doesn't belong in this file.

wking · 2017-08-03T18:32:55Z

image-layout.md

@@ -149,6 +149,7 @@ This index provides an established path (`/index.json`) to have an entry point f
 * Future versions of the spec MAY use a different mediatype (i.e. a new versioned format).
 * An encountered `mediaType` that is unknown SHOULD be safely ignored.

+Note that while `index.json` is a REQUIRED file, the use of an image index is OPTIONAL for image providers.


I'd shift this line up to the opening section and rephrase it to something like:

Consumers MAY support OCI Image Layout and MAY also support other mechanisms for distributing image content.

The optionality of image-layout support is important enough that I'd rather not bury it 150 lines into the file ;).

We already state this in a clear manner in another doc.

wking · 2017-08-03T18:34:20Z

image-layout.md


+The first named reference (`"stable-release"`) points to another index that might contain multiple references with several platform specification and annotations.


Backticks and quotes seems like overkill. Can we use stable-release here (and v1.0 below)? Those are the names; the quotes are just part of representing strings in JSON.

Also probably “several platform sepecification” → “distinct platforms” or some such.

wking · 2017-08-03T18:35:43Z

image-layout.md


+The first named reference (`"stable-release"`) points to another index that might contain multiple references with several platform specification and annotations.
+Note that the `org.opencontainers.image.ref.name` annotation SHOULD only be considered valid when on descriptors on `index.json`.


Maybe link to annotations.md for this so folks can see that we're referencing a requirement defined there.

stevvooe · 2017-08-04T00:02:40Z

@AkihiroSuda It would be good if you could file an issue stating the problem before filing PRs. I am not sure that these are correct and they seem redundant with other statements that are already present.

What is the problem that you are trying to address here?

AkihiroSuda · 2017-08-04T05:42:21Z

Opened #720 for the problem: The fact that "Image Layout is OPTIONAL" is not explicitly documented and causing confusion about necessity of index.json.

I modified this PR to limit its scope to nested index examples. PTAL.

AkihiroSuda · 2017-08-04T05:45:02Z

image-layout.md


+The first named reference (`stable-release`) points to another index that might contain multiple references with distinct platforms and annotations.
+Note that the [`org.opencontainers.image.ref.name` annotation](annotations.md) SHOULD only be considered valid when on descriptors on `index.json`.


Note: This redundant sentence is intentionally added for better human understandability.

wking · 2017-08-04T13:49:18Z

image-layout.md

+The first named reference (`stable-release`) points to another index that might contain multiple references with distinct platforms and annotations.
+Note that the [`org.opencontainers.image.ref.name` annotation](annotations.md) SHOULD only be considered valid when on descriptors on `index.json`.
+
+The second named reference ("`v1.0`") points to a manifest that is specific to the linux/ppc64le platform.


You still have both backticks and quotes here.

AkihiroSuda · 2017-08-12T07:29:04Z

Fixed quotation

wking · 2017-08-12T14:03:41Z

img/media-types.dot

@@ -6,6 +6,7 @@ digraph G {
    layer [shape=note, label="Layer tar archive\napplication/vnd.oci.image.layer.v1.tar\napplication/vnd.oci.image.layer.v1.tar+gzip\napplication/vnd.oci.image.layer.nondistributable.v1.tar\napplication/vnd.oci.image.layer.nondistributable.v1.tar+gzip"]
  }

+  imageIndex -> imageIndex [label="1..*"]


If we're going to draw this loop in here, I think we also want to SHOULD support for indexes here (for both providers and consumers), at least for the index in index.json.

AkihiroSuda · 2017-11-13T08:14:07Z

Updated, anyone PTAL?

AkihiroSuda · 2017-11-16T04:50:17Z

lint failure on travis is unrelated: #735

stevvooe · 2017-11-21T01:43:48Z

LGTM

The main use case I see is an archive that has multiple multi-platform images.

Signed-off-by: Akihiro Suda <[email protected]>

AkihiroSuda · 2018-01-17T04:58:23Z

ping @opencontainers/image-spec-maintainers

cyphar · 2018-03-11T09:48:14Z

LGTM.

/cc @opencontainers/image-spec-maintainers

vbatts · 2018-04-11T14:50:36Z

LGTM

This was referenced Aug 2, 2017

image-layout: remove support for nested index #718

Closed

image-layout: make index.json OPTIONAL #719

Closed

AkihiroSuda closed this Aug 2, 2017

AkihiroSuda reopened this Aug 3, 2017

AkihiroSuda force-pushed the index-is-required branch from 1301924 to cf8277f Compare August 3, 2017 06:18

AkihiroSuda changed the title ~~dot: index is required and can be referred from another index~~ clarification about index Aug 3, 2017

wking reviewed Aug 3, 2017

View reviewed changes

AkihiroSuda mentioned this pull request Aug 4, 2017

Clarify that "Image Layout" is OPTIONAL #720

Open

AkihiroSuda force-pushed the index-is-required branch from cf8277f to 318014e Compare August 4, 2017 05:40

AkihiroSuda changed the title ~~clarification about index~~ clarification about nested index Aug 4, 2017

AkihiroSuda commented Aug 4, 2017

View reviewed changes

wking reviewed Aug 4, 2017

View reviewed changes

AkihiroSuda force-pushed the index-is-required branch from 318014e to 1de1632 Compare August 12, 2017 07:28

wking reviewed Aug 12, 2017

View reviewed changes

AkihiroSuda force-pushed the index-is-required branch from 1de1632 to a2fa9b2 Compare November 13, 2017 08:13

clarification about nested index

c4c9dec

Signed-off-by: Akihiro Suda <[email protected]>

AkihiroSuda force-pushed the index-is-required branch from a2fa9b2 to c4c9dec Compare November 25, 2017 06:39

vbatts merged commit e562b04 into opencontainers:master Apr 11, 2018

sudo-bmitch mentioned this pull request Sep 25, 2022

Update 1.0 branch for 1.0.3 release #955

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

clarification about nested index #716

clarification about nested index #716

AkihiroSuda commented Jul 28, 2017 •

edited

Loading

jonjohnsonjr commented Jul 28, 2017

AkihiroSuda commented Jul 28, 2017

jonjohnsonjr commented Jul 28, 2017

jonboulle commented Jul 31, 2017 •

edited

Loading

AkihiroSuda commented Jul 31, 2017

jonboulle commented Jul 31, 2017

AkihiroSuda commented Aug 2, 2017

AkihiroSuda commented Aug 3, 2017

AkihiroSuda commented Aug 3, 2017

wking Aug 3, 2017

stevvooe Aug 4, 2017

wking Aug 3, 2017

stevvooe Aug 4, 2017

wking Aug 3, 2017

wking Aug 3, 2017

stevvooe commented Aug 4, 2017

AkihiroSuda commented Aug 4, 2017 •

edited

Loading

AkihiroSuda Aug 4, 2017

wking Aug 4, 2017

AkihiroSuda commented Aug 12, 2017

wking Aug 12, 2017

AkihiroSuda commented Nov 13, 2017

AkihiroSuda commented Nov 16, 2017

stevvooe commented Nov 21, 2017 •

edited by caniszczyk

Loading

AkihiroSuda commented Jan 17, 2018

cyphar commented Mar 11, 2018 •

edited by caniszczyk

Loading

vbatts commented Apr 11, 2018 •

edited by caniszczyk

Loading


		The first named reference (`"stable-release"`) points to another index that might contain multiple references with several platform specification and annotations.


		The first named reference (`"stable-release"`) points to another index that might contain multiple references with several platform specification and annotations.
		Note that the `org.opencontainers.image.ref.name` annotation SHOULD only be considered valid when on descriptors on `index.json`.


		The first named reference (`stable-release`) points to another index that might contain multiple references with distinct platforms and annotations.
		Note that the [`org.opencontainers.image.ref.name` annotation](annotations.md) SHOULD only be considered valid when on descriptors on `index.json`.

clarification about nested index #716

clarification about nested index #716

Conversation

AkihiroSuda commented Jul 28, 2017 • edited Loading

jonjohnsonjr commented Jul 28, 2017

AkihiroSuda commented Jul 28, 2017

jonjohnsonjr commented Jul 28, 2017

jonboulle commented Jul 31, 2017 • edited Loading

AkihiroSuda commented Jul 31, 2017

jonboulle commented Jul 31, 2017

AkihiroSuda commented Aug 2, 2017

AkihiroSuda commented Aug 3, 2017

AkihiroSuda commented Aug 3, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

stevvooe commented Aug 4, 2017

AkihiroSuda commented Aug 4, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

AkihiroSuda commented Aug 12, 2017

Choose a reason for hiding this comment

AkihiroSuda commented Nov 13, 2017

AkihiroSuda commented Nov 16, 2017

stevvooe commented Nov 21, 2017 • edited by caniszczyk Loading

AkihiroSuda commented Jan 17, 2018

cyphar commented Mar 11, 2018 • edited by caniszczyk Loading

vbatts commented Apr 11, 2018 • edited by caniszczyk Loading

AkihiroSuda commented Jul 28, 2017 •

edited

Loading

jonboulle commented Jul 31, 2017 •

edited

Loading

AkihiroSuda commented Aug 4, 2017 •

edited

Loading

stevvooe commented Nov 21, 2017 •

edited by caniszczyk

Loading

cyphar commented Mar 11, 2018 •

edited by caniszczyk

Loading

vbatts commented Apr 11, 2018 •

edited by caniszczyk

Loading