Clarify when non-distributable layer policies should be enforced

[stevvooe]

This came up in this discussion: moby/moby#28903 (comment).

For docker, the mediaType for a nondistributable layer is only enforced on push, leaving the mediaType ignored on pull. On pull, the urls field is used instead. While this specification doesn't define push and pull, we should clarify that it is important that these operations be only enforced on the correct data flow direction.

This is very subtle, but preserving this behavior ensures flexibility.

[jonboulle]

I'm not sure we want to be any more prescriptive than what's already in https://github.com/opencontainers/image-spec/blob/master/layer.md#non-distributable-layers but feel free to tweak the wording?

[stevvooe]

@jonboulle If you read back to that issue, restrictive type checking on pull can lead to inflexibility. Something like:

The nondistributable policy SHOULD only be enforced when pushing layers. URLs should only be used when pulling.

Without saying "pushing" and "pulling". Perhaps, we can define these input and output operations as part of #467. This really falls in the camp of implementation wisdom, but that kind of thing is important for a complete specification.

Again, this is subtle and I may need help with the wording. Let me know if I need to further explain the exact issue.

[wking]

On Wed, Nov 30, 2016 at 01:43:11PM -0800, Stephen Day wrote: Something like: > The nondistributable policy SHOULD only be enforced when pushing > layers. URLs should only be used when pulling.

‘urls’ is already pull-only [1]: This OPTIONAL property specifies a list of URIs from which this object MAY be downloaded. which says nothing about uploading. The nondistributable docs have “Typically” and “MAY” hints for downloading from ‘urls’, and they leave the uploading implementation-defined [2]. Reading over moby/moby#28892, moby/moby#29001 seems like a more appropriate solution (when you don't have or can't rely on a manifest list to handle the platform compatibility check earlier in the DAG). moby/moby#28903 looks like it's currently blocking descriptors which set ‘urls’ entirely on Linux, which is too harsh. And it sounds like a previous version of moby/moby#28903 was blocking descriptors pointing at nondistributable layers, which is also too harsh. [1]: https://github.com/opencontainers/image-spec/blame/9fa054359da9ea748b5e623ff36e1484d88b2c20/descriptor.md#L39 [2]: https://github.com/opencontainers/image-spec/blob/9fa054359da9ea748b5e623ff36e1484d88b2c20/layer.md#non-distributable-layers

[jonboulle]

@stevvooe I honestly don't know exactly what you'd like to see here - IMO the existing wording is pretty clear that they can be downloaded but probably-shouldn't-be uploaded. I do agree that we can further qualify those verbs though. In any case want to put up some strawman wording we can iterate on?

[stevvooe]

The nondistributable policy SHOULD only be enforced when pushing layers. URLs should only be used when pulling.

I honestly thought the above was a solid strawman.

The implication here is that if you use urls for applying push policy, there are cases where the nondistributable policy applied will prevent usage of urls without nondistributable. Opposite to that, using the nondistributable policy for a layer type on pull, other than registering the type, will prevent systems from working where they choose not to apply the policy.

The linked PR, moby/moby#28903 (comment), attempts to do the latter, with unfortunate results.

@jonboulle Does that help to clarify?

[jonboulle]

@stevvooe not really :-). Taken a stab in #483, ptal.