Working group for Reference Spec #114
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| # OCI Working Group: Reference Spec | ||
|
|
||
| ## Reference Spec OCI Working Group - Governance Charter | ||
|
|
||
| This document describes the basic governance principles for the Reference Spec Working Group (the “WG”). | ||
|
|
||
| The WG operates as an OCI Working Group under the [Open Container Initiative (OCI) Charter](https://github.com/opencontainers/tob/blob/master/CHARTER.md), which describes the responsibilities of the OCI Technical Oversight Board (the "TOB”). The WG is established by the TOB as an OCI Working Group pursuant to the OCI Charter. Accordingly, the WG will operate in accordance with the OCI Charter and OCI's other policies and procedures, supplemented by the details below. | ||
|
|
||
| ## Purpose | ||
|
|
||
| References are a string that is used by runtimes and other OCI registry clients to retrieve a container image. | ||
| They are currently a convention, used by many clients, adopted from Docker and implemented in distribution/distribution. | ||
| This WG seeks to define the syntax and parsing of a reference as an OCI spec. | ||
|
|
||
| ## Scope | ||
sudo-bmitch marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| * Document the existing convention used by runtimes and other OCI registry clients. | ||
| * Specify the syntax for references to an [OCI Image Layout](https://github.com/opencontainers/image-spec/blob/7b36cea86235157d78528944cb94c3323ee0905c/image-layout.md) manifest, including support for a tag, digest, or a full registry/repository name. | ||
| * Define how the syntax can be extended to support other use cases, including: | ||
| * Alternate layer formats | ||
| * Immutable tags | ||
| * Selecting an artifact that refers to another manifest (e.g. signature or SBOM) | ||
| * Querying content from a pull through cache serving multiple registries (see [distribution-spec PR #66](https://github.com/opencontainers/distribution-spec/pull/66)) | ||
|
Comment on lines
+18
to
+23
There was a problem hiding this comment. This is all what I'd describe as "Referrers 2.0" (the cautionary tales I referenced earlier) - stretch goals that look more like designing a new thing than documenting an existing thing, and I'm pretty strongly opposed to including these in the first pass of explicit spec language for "references" in the OCI. Let's start smaller and just have an explicit spec for the thing that currently exists and has seen wide adoption for ~10+ years, then we can talk about expansion possibilities with less fog. There was a problem hiding this comment. I agree here. There are many places that could refer to a spec documenting the existing state, that would be, for backward compatibility reasons with handling existing inputs, ~unable to adopt new many plausible new syntaxes (there are only so many ASCII characters, and for readability, some are more attractive than others, so conflicts are likely). The list above is also unclear about the target user — some seem to be relevant to running containers, some to building them, some for, I guess, managing a registry, some for… I don’t know, guessing, purely internal uses within a build system/registry? Philosophically, there are many data transfer / RPC mechanism that can be used to add such parameters to operations where the parameters make sense; and clear separation between data/metadata is essential. I strongly think that adding a field is almost always preferable to adding extra syntax within an existing string field. The one exception is if the string field is so extremely widespread that adding a field everywhere we have the existing string is unfeasible. [E.g. we have ended up with the concept of a “slash-separated [0-terminated] file path” although that is, in many ways, flawed.] But, such a widespread use almost always implies that the specifics of the format are hard-coded in many places, and various extensions / other string formats assume that the format will not change. I can imagine an effort to add features / drive a cross-vendor consensus for a single specific use case. E.g., maybe there is some feature that would be really valuable to have in K8s pod specs, and equivalent container image references in other “run a container from this image” orchestration systems. That is a reasonably bounded problem where clear benefits can be articulated. I think add ing features that could benefit various sort-of-related but rather different use cases like (running / publishing / downloading / SBOMs / graph queries), where most of the proposed features would be irrelevant to any single user but many interoperability / backward compatibility concerns would be a concern for many such users, seems unlikely to succeed. There was a problem hiding this comment.
If the thing specified cannot be extended, there will be no "then". This isn't defining the possible extensions, just making it possible for extensions to be created. The result is likely limiting the character set for various fields so that characters are available to mark future extensions.
I see a reference more as a URI than as a pointer to a tag on a registry. The tag pointer was already extended to allow for pointers to a digest. With referrers and people mounting OCI volumes, I can see a request for a reference to a referrer to an image. This is going to keep happening, e.g. with a pull through proxy that can proxy multiple registries, we will lose the ability to directly pull content from the proxy using the current reference syntax. |
||
| * Provide backwards compatibility by using the existing reference convention from [distribution/reference](https://github.com/distribution/reference) when feasible. | ||
|
There was a problem hiding this comment. This increases my confusion -- we're trying to talk about "backwards compatibility" but we're explicitly trying to design a whole new thing? There was a problem hiding this comment. We're defining something that can be an in-place upgrade for tooling that currently uses the distribution/reference strings. v1.0 may end up being the current state of distribution/reference, but v* should avoid changes that break users who depend on the current string syntax. New features should be additive in a way that can be distinguished from current use cases, without ambiguity. |
||
|
|
||
| ## Out of Scope | ||
|
|
||
| * This WG will be limited to the creation of a new spec, and is not expected to impact other OCI specs. | ||
|
There was a problem hiding this comment. As noted above, I strongly disagree with this conclusion, but also believe it's premature to decide that this should be a completely net-new spec.
This isn't very big, and I don't think we should encourage it to be. There was a problem hiding this comment. I don't think the size of the work should determine whether it's a new spec, but rather whether it fits within the definition of an existing spec. Looking at image-spec:
I don't think we fit there. And for distribution-spec:
We only fit there if we are deciding in advance to only allow references to content on a registry, and not to any other way of storing images, e.g. the OCI Image Layout. |
||
|
|
||
| ## Intended work product | ||
|
|
||
| * Create a `reference-spec` with a formal specification for parsing a reference string. | ||
| * Provide a Go implementation of the spec. | ||
|
|
||
| ## Proposed Owners | ||
|
|
||
| The following have agreed to participate in the working group, review progress, report progress back to the OCI community, and present the results to the TOB once the working group has completed its objectives. | ||
|
|
||
| * Akihiro Suda | ||
| * Brandon Mitchell | ||
| * James Hewitt | ||
| * Vishal Choudhary | ||
| * **additional volunteers needed** | ||
sudo-bmitch marked this conversation as resolved.
Show resolved
Hide resolved
sudo-bmitch marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Stakeholders | ||
|
|
||
| OCI Projects, non-OCI projects, or organizations sponsoring the working group and participating in the implementation and use case validation of the work done by the group. | ||
|
|
||
| * buildkit | ||
| * containerd | ||
| * distribution | ||
| * nerdctl | ||
| * moby | ||
| * regclient | ||
| * **additional volunteers needed** | ||
|
There was a problem hiding this comment. containerd, nerdctl, Moby, BuildKit can be added here? There was a problem hiding this comment. Is that a question to your co-maintainers or a request for me to add it? |
||
|
|
||
| ## Governance | ||
|
|
||
| * **Working Group**: | ||
| * The TOB is establishing the WG as an OCI Working Group, pursuant to [section 6(p)](https://github.com/opencontainers/tob/blob/master/CHARTER.md#6-technical-oversight-board-tob) of the OCI Charter. | ||
| * **Owners**: | ||
| * The WG proposal to the TOB will specify one or more initial "owners" of the WG. | ||
| * The current owners will be listed in the [OCI Working Group documentation](https://github.com/opencontainers/tob/blob/master/WG-INFO.md). | ||
| * The owners shall be responsible for: | ||
| * scheduling regular meetings of the WG community; | ||
| * facilitating open discussion among WG community participants; | ||
| * coordinating and managing the development of the WG work product and outputs; | ||
| * recording decisions that are reached by the WG community; and | ||
| * keeping the TOB regularly informed about the status of the WG’s efforts, including when the WG has readied the work product and outputs for TOB approval. | ||
| * **Maintainers**: | ||
| * If the WG owners request the TOB to approve a draft specification as a released OCI Specification, the request shall include a list of proposed "maintainers" of the OCI Specification. | ||
| * The current maintainers will be listed in the [OCI Working Group documentation](https://github.com/opencontainers/tob/blob/master/WG-INFO.md). | ||
| * The maintainers shall be responsible for continuing the work of overseeing updates, improvements and changes to a released OCI Specification on an ongoing basis. | ||
| * **Meetings**: | ||
| * Meetings of the WG shall be open to the public. | ||
| * Participants in the meetings shall comply with the [OCI Code of Conduct](https://github.com/opencontainers/.github/blob/master/CODE_OF_CONDUCT.md) and all other policies of OCI and The Linux Foundation. | ||
| * **TOB Approval**: | ||
| * The WG shall operate pursuant to the procedures set forth in [section 6(p)](https://github.com/opencontainers/tob/blob/master/CHARTER.md#6-technical-oversight-board-tob) of the OCI Charter, with regards to obtaining TOB approval for initial release of the work product and outputs as an OCI Specification or other OCI Project, and for subsequent maintenance activities thereafter. | ||
| * **Amendments**: | ||
| * The owners of the WG may from time to time propose to the TOB (1) amendments to this WG Governance Document, and/or (2) changes to the composition of the owners or maintainers of the WG. | ||
| * As set forth in the OCI Charter, the TOB may, in its discretion by a two-thirds vote, approve or reject the requested amendments or changes. | ||
| * As set forth in the OCI Charter, the TOB may also disband the WG by a two-thirds vote. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
"define" is a loaded word for me here, given the pre-existing nature of the relevant format -- would prefer a word like "document"
Also, "in the OCI" instead of "as an OCI spec" (because as I've noted prior, I don't think this should be new a spec, but declaring that it will be a new spec right off the bat in the WG proposal is definitely premature).
or