Draft of a "getting started" document for the OCI #76
Conversation
Signed-off-by: Phil Estes <[email protected]>
|
/cc: @opencontainers/tob |
GETTING_STARTED.md
Outdated
|
|
||
| For any future reference implementation to be adopted by the OCI, it would | ||
| need to be kept in sync with the specification it implements. For a change | ||
| to be accepted to the spec, the equivalent implementation would need to be |
There was a problem hiding this comment.
I think it'd be worth articulating the converse here as well; for a change to be accepted to the reference implementation, the equivalent change would need to be adopted in the spec as well. Runc hasn't followed this, and that means that integrators with runc may be integrating with its specific behavior rather than with the behavior defined by the spec.
There was a problem hiding this comment.
Maybe, but there is a necessary balance here.
It would be a mistake to accept changes into a specification if they haven't been tested "in the wild" (or at the very least, implemented at least once). The image-spec had this exact problem -- no reference implementation (at least, until umoci) made it so that we had to do some pretty large reworks during the release-candidate phase of 1.0.
That being said, I think that we made too much of a concession to runc in the runtime-spec (though I would argue this is also historically driven -- runc was ready and in wide use quite a while before the spec was). There are many things in runc which really should be in the spec, and I am constantly frustrated to see that many implementations of the runtime-spec spend more of their time reading the runc source code than they do the spec.
Maybe we should make it so that no release of the project should have any major not-in-the-spec features, which would allow for experimentation and development without risking people becoming dependent on the feature. Unfortunately runc's behaviour doesn't really break this rule (because it breaks the entire concept of releases given that we've been doing 1.0 release candidates for 4 years now) -- but I think it's fair to say that this is something which no other OCI project will or should repeat.
There was a problem hiding this comment.
Given this section was updated due to further review below from @cyphar, there is no more commentary on spec vs. ref. implementation alignment. Not that it isn't an important topic in general, but maybe it didn't fit in this document anyway? Feedback welcome.
GETTING_STARTED.md
Outdated
| scope of the OCI. Currently this is of course limited to specifications around | ||
| runtime, image, and distribution of containers. The artifacts repository and | ||
| project is related to both image and distribution and is a natural expansion | ||
| of OCI into ongoing experimentation with registries and cloud native tooling. |
There was a problem hiding this comment.
The word experimentation is creating angst amongst some that see this as experimentation of registries that gives them the belief this will change.
What I think you're trying to say is supporting other types, not as an experiment, but a commitment to support other types, enables others to experiment on a stable capability.
There was a problem hiding this comment.
Updated in latest commit.
GETTING_STARTED.md
Outdated
| guide future potential submissions. | ||
|
|
||
| 1. The OCI, unlike the CNCF, is not directly chartered for the advancement, marketing, and support of general cloud native software projects. | ||
| 2. Projects consumed via a UI and/or with a significant end user experience component are unlikely to be a good fit for the OCI model. |
There was a problem hiding this comment.
1 really helps scope what you get with OCI.
I'm struggling with 2. I think I see what you're saying isn't a good solution. Could we focus on what would? Supportive libraries or tools that enable the OCI specs, that need some level of endorsement to gain acceptance.
There was a problem hiding this comment.
I think that this boils down to the "dirt" or "boring infrastructure" question -- we should phrase this as effectively saying "only boring projects make sense within the OCI" (though obviously without sounding so pessimistic about the prospect). There actually is text in the OCI Charter which mentions that this was the intention of the OCI from the outset:
The Open Container Initiative does not seek to be a marketing organization, define a full stack or solution requirements, and will strive to avoid standardizing technical areas undergoing innovation and debate.
There was a problem hiding this comment.
This section is updated significantly; would love your re-review/comments.
There was a problem hiding this comment.
Do we also need to capture something around number of people with diversity for the maintainers of a project? This would avoid OCI being an endorsement for a single companies project. It would also make sure we have a set of people that can carry a project forward.
| # Getting Started | ||
|
|
||
| While the [OCI Charter](./CHARTER.md) is our official governing document, many | ||
| people have asked for a gentler introduction to the Open Container Initiative as |
There was a problem hiding this comment.
While you do say that the OCI Charter is our governing document, I would include an explicit comment along the lines of "if there are any conflicts between this document and the OCI Charter, the Charter takes precedence". Another question is whether changing this document means changing the guidelines for admission of new projects -- should that require a 2/3 TOB vote (as amending the OCI Charter does)? Note that a 2-LGTM "vote" is less than is required for a project to be admitted.
There was a problem hiding this comment.
Good question; let's discuss on the TOB call.
GETTING_STARTED.md
Outdated
|
|
||
| As our [website](https://opencontainers.org) states, chiefly the OCI is "an open | ||
| governance structure for the express purpose of creating open industry standards | ||
| around container formats and runtime." Created in 2015, the core initial purpose |
There was a problem hiding this comment.
With #77 this mission statement should be updated.
There was a problem hiding this comment.
Reworded to make this paragraph hopefully just a brief history statement and not tied to whatever we might change the mission statement to today or someone else does in the future. Let me know if it reads that way to you.
GETTING_STARTED.md
Outdated
| guide future potential submissions. | ||
|
|
||
| 1. The OCI, unlike the CNCF, is not directly chartered for the advancement, marketing, and support of general cloud native software projects. | ||
| 2. Projects consumed via a UI and/or with a significant end user experience component are unlikely to be a good fit for the OCI model. |
There was a problem hiding this comment.
I think that this boils down to the "dirt" or "boring infrastructure" question -- we should phrase this as effectively saying "only boring projects make sense within the OCI" (though obviously without sounding so pessimistic about the prospect). There actually is text in the OCI Charter which mentions that this was the intention of the OCI from the outset:
The Open Container Initiative does not seek to be a marketing organization, define a full stack or solution requirements, and will strive to avoid standardizing technical areas undergoing innovation and debate.
GETTING_STARTED.md
Outdated
| intangible goal. However, we list the following considerations to help | ||
| guide future potential submissions. | ||
|
|
||
| 1. The OCI, unlike the CNCF, is not directly chartered for the advancement, marketing, and support of general cloud native software projects. |
There was a problem hiding this comment.
I don't think you need to mention the CNCF here. We could just add it at the end of the list, as a general tip that the CNCF may better fit projects which don't match these criteria.
There was a problem hiding this comment.
I presume it means enterprise-like support, but the CNCF doesn't provide that either...? @estesp?
There was a problem hiding this comment.
I specifically was thinking of the project support staff provided by the CNCF along with a special service desk which provides help with website development, cloud/infrastructure cost coverage/free credits, social media reports for member projects, etc. etc. I think the careful line here is that the OCI has a budget for some of these items as well, but the point is that it isn't as clearly in line with the mission of OCI to gain a large # of projects and then provide that support for their maintainers/communities as it seems to be specifically in line with the CNCF mission.
GETTING_STARTED.md
Outdated
|
|
||
| 1. The OCI, unlike the CNCF, is not directly chartered for the advancement, marketing, and support of general cloud native software projects. | ||
| 2. Projects consumed via a UI and/or with a significant end user experience component are unlikely to be a good fit for the OCI model. | ||
| 3. The OCI has an small but active and vibrant group of participants today; however the specifications and related projects are a small niche of the overall cloud native world, and seeking out the OCI to validate or grow a community around a young project is unlikely to be a viable model. The CNCF is much more suited to that aim given the sandbox and maturity model. |
There was a problem hiding this comment.
I think this should be merged into (2) as being part of the "boring infrastructure" point. In fact, I think most of the guidelines could be considered to be part of the "boring infrastructure" point -- maybe we should break it down like this:
The OCI receives proposals suggesting additions to the current suite of project types listed above. We understand that a perfect framework for determining inclusion or rejection of these proposals is an intangible goal. However, we list the following considerations to help guide the review of future project submissions.
The project should be a piece of "boring core container infrastructure". This is a partially subjective criterion, but the key factors that make something fulfill this requirement are:
- The project should be as un-opinionated and extensible as is reasonably possible.
- Rather than being a complete solution or framework, the project should be usable as a building-block for larger solutions and frameworks.
- (probably more things go here...)
It should fit logically into the scope and mission of the OCI -- to provide a home for open standards and tools which underpin the wider container ecosystem. This means that it should not conflict with existing OCI projects, nor should be it be completely unrelated to existing OCI projects. The precise scope of the OCI is defined by the OCI Charter, but the TOB may choose to expand the scope if they feel it is within the mission of the OCI.
There was a problem hiding this comment.
Reworded this section and used some of your suggested text above.
Signed-off-by: Phil Estes <[email protected]>
|
Changelog for 4 June 2020:
Thanks to @SteveLasker, @AkihiroSuda, @cyphar, and @samuelkarp for comments/review! |
There was a problem hiding this comment.
Thanks for working on this @estesp! I left a few suggestions.
|
|
||
| **Contributors**, including the project maintainers, and member companies have a | ||
| vested interest in bringing forward the "state of the art" with respect to the | ||
| scope of the OCI. Currently this is of course limited to specifications around |
| runtime, image, and distribution of containers. The artifacts repository and | ||
| project is related to both image and distribution and is a natural expansion | ||
| of OCI into ongoing support of additional types within registries and related |
There was a problem hiding this comment.
| runtime, image, and distribution of containers. The artifacts repository and | |
| project is related to both image and distribution and is a natural expansion | |
| of OCI into ongoing support of additional types within registries and related | |
| runtime, image, and distribution of containers. The artifacts repository and | |
| project expands the scope of OCI to support different types of content in | |
| concert with the image and distribution specifications. |
| (Helm charts, Singularity container images, SPDX, source bundles, etc.) and | ||
| registries, and allows for further experimentation with arbitrary file types | ||
| within the context of this stable andd well-defined capability. |
There was a problem hiding this comment.
| (Helm charts, Singularity container images, SPDX, source bundles, etc.) and | |
| registries, and allows for further experimentation with arbitrary file types | |
| within the context of this stable andd well-defined capability. | |
| (Helm charts, Singularity container images, SPDX, source bundles, etc.) in | |
| registries, and allows for further experimentation with arbitrary file types | |
| within the context of this stable andd well-defined capability. |
| way: they will expect projects and products that claim OCI compliance to | ||
| interoperate smoothly with other projects and products which are OCI compliant. | ||
| They will look to the OCI to continue maturing conformance and specifications | ||
| to best support the cloud native ecosystem's goal of interoperability for |
There was a problem hiding this comment.
nit: I'd avoid "cloud native" as I think it's important for us to consider OCI in the context of non-cloud use-cases.
| to best support the cloud native ecosystem's goal of interoperability for | |
| to best support the container ecosystem's goal of interoperability for |
There was a problem hiding this comment.
Not sure cloud native is really tied to the cloud, per se. Yes, literally the word is there. But, is someone using CNCF projects on-prem not "cloud native"? :) This is also the tension we're seeing around OCI being tightly coupled to containers, while the distribution-spec and artifacts enable us to store additional non-container artifacts in a cloud-native/container centric deployment model.
Anyway, just suggesting this wording cloud native helps our broader cause here.
|
|
||
| In summary, the OCI has a small but active and vibrant group of participants | ||
| today. However the OCI specifications and related OCI projects are but a small | ||
| niche of the overall cloud native world, and seeking out the OCI to validate |
There was a problem hiding this comment.
| niche of the overall cloud native world, and seeking out the OCI to validate | |
| niche of the overall container world, and seeking out the OCI to validate |
|
|
||
| ### Specifications | ||
|
|
||
| Clearly the image, runtime, and distribution specifications are the key |
There was a problem hiding this comment.
nit: remove "Clearly"; it doesn't really add anything to the sentence
| Artifacts is not a standalone specification, but fits within this category | ||
| as it is a repository which serves as the extension point for media types | ||
| which include the core media types found within the image spec, as well as | ||
| connecting those and additional media types with the distribution spec as | ||
| the means for storage, query, and delivery of a growing list of well-defined | ||
| artifact types defined within the project. |
There was a problem hiding this comment.
I'm having a really hard time parsing this. Would something like this make sense?
Artifacts is not a standalone specification, but provides additional guidance on top of the image and distribution specifications for formatting and distributing content.
| a full stack or solution requirements, and will strive to avoid standardizing | ||
| technical areas undergoing innovation and debate.* | ||
| * The project should be a piece of "**boring core container infrastructure**". | ||
| While this is partially subjective criterion, the key factors towards |
There was a problem hiding this comment.
| While this is partially subjective criterion, the key factors towards | |
| While this is a subjective criterion, the key factors towards |
| approved by the TOB and will be used to define other artifact types (in addition | ||
| to OCI images) which may be defined and stored in registries conforming to the | ||
| OCI distribution spec. | ||
|
|
There was a problem hiding this comment.
In 2019, an "artifacts" project was approved by the TOB and will be used to define other artifact types (in addition to OCI images) which may be defined and stored in registries conforming to the OCI distribution spec.
suggest:
In 2019, an "artifacts" project was approved by the TOB enabling other artifact types (in addition to OCI images). Supporting additional artifacts acknowledges containers are core to modern workflows, while enabling additional artifact types to be stored in registries conforming to the OCI distribution spec
| ### Libraries | ||
|
|
||
| While hosting library code is not a common goal of the OCI, there are a few | ||
| specific cases where small, non-end user focused, and tightly scoped libraries |
There was a problem hiding this comment.
Defining "small" here is kind of difficult. I would like to see language here specifying that these libraries should have no or minimal dependencies. If a library is depending on an even larger project or library, it can't really be "small". I think the two libraries below are good examples of "no or minimal dependencies".
There was a problem hiding this comment.
I somewhat agree with putting more text about what "small" means, but I don't think this needs to be a legal document in terms of specificity. After all, the TOB decides whether a project meets the criteria we outline here and in the charter text.
I would also point out that in my view, what defines a library as small is its scope (though that is covered by "tightly scoped" so maybe this "small" does refer to size). As an obvious example, glibc doesn't have any dependencies, but it isn't a small library.
|
Last activity June 11, 2020 .. @opencontainers/tob do we want to merge this as is? @estesp is this still a draft/WIP? |
Draft of a document based on our March and April TOB calls/discussion
Please note that I'm not proposing this is the exact spot for this, but I find the GH review cycle maybe more helpful than continuing in HackMD. We can determine appropriate location for this after discussion on the content.
Signed-off-by: Phil Estes [email protected]