Draft of a "getting started" document for the OCI #76
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,127 @@ | ||||||
| # 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 | ||||||
| well as general guidance on how to interact with the projects and specifications | ||||||
| found under the OCI umbrella. This document attempts to be that starting point | ||||||
| for those who may be new to the OCI, interested in participation, or who want to | ||||||
| understand if a project is a fit for inclusion or contribution to the OCI. | ||||||
|
|
||||||
| ## What is the OCI? | ||||||
|
|
||||||
| 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. |
||||||
| was to align Docker and other ecosystem players around a runtime and image | ||||||
| specification that would become an industry baseline for how images are packaged | ||||||
| and executed in OCI compliant runtimes. | ||||||
|
|
||||||
| Since that initial work, finalized in 1.0 specs in the summer of 2017, a | ||||||
| distribution specification is now underway, based on the HTTP API of the initial | ||||||
| Docker distribution (registry) project. 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. | ||||||
|
|
||||||
|
There was a problem hiding this comment.
suggest: |
||||||
| ## Who uses the OCI? | ||||||
|
|
||||||
| It makes the most sense to see consumers of OCI as fitting into a few specific | ||||||
| categories: contributors/members, implementors, and end users. | ||||||
|
|
||||||
| **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 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. There was a problem hiding this comment. Updated in latest commit. |
||||||
| Specifically, [artifacts](https://github.com/opencontainers/artifacts) expands the concept around the **what** when | ||||||
| discussing non-OCI image content (Helm charts, Singularity container images, | ||||||
| SPDX, source bundles, etc.) and registries. | ||||||
|
|
||||||
| **Implementors** own projects outside the OCI for which they have determined | ||||||
| value in being "OCI compliant"; whether that's a registry, a unique container | ||||||
| runtime, or an end-user tool that talks to registries. They take the OCI | ||||||
| specifications and implement support for them in their project, and potentially | ||||||
| will use the conformance suite within the OCI to validate their compliance to | ||||||
| the specification(s). | ||||||
|
|
||||||
| **End Users** tend to gain value from the OCI specifications in an indirect | ||||||
| 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.
Suggested change
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. |
||||||
| runtimes, images, and distributing images and artifacts across clouds and | ||||||
| platforms. | ||||||
|
|
||||||
| ## What Types of Projects Exist within the OCI? | ||||||
|
|
||||||
| There has been some growth in the nature and use of the OCI since those | ||||||
| initial meetings around the image and runtime specification in 2015. The | ||||||
| following subsections define project categories which exist in the OCI today. | ||||||
|
|
||||||
| ### 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 |
||||||
| reason for the existence of the OCI today. These standards are meant to | ||||||
| provide a baseline to follow for implementors of runtimes, registries, and | ||||||
| tools which interact with container images and registries. | ||||||
| - [Runtime spec](https://github.com/opencontainers/runtime-spec) | ||||||
| - [Image spec](https://github.com/opencontainers/image-spec) | ||||||
| - [Distribution spec](https://github.com/opencontainers/distribution-spec) | ||||||
|
|
||||||
| ### Spec Conformance Test | ||||||
|
|
||||||
| Conformance tests should provide a clear, end-user runnable test suite for | ||||||
| implementors to use to determine and demonstrate that an implementing project | ||||||
| or product meets the explicit definitions of the specification. | ||||||
| - [OCI Conformance](https://github.com/opencontainers/oci-conformance) | ||||||
|
|
||||||
| The most advanced conformance implementation to date is for the new distribution specification. Additional work on image and runtime conformance is ongoing. | ||||||
|
|
||||||
| ### 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. |
||||||
| have been accepted into the OCI. The common denominator for these libraries are | ||||||
| that they help implementors properly use features of the specifications: | ||||||
| - [go-digest](https://github.com/opencontainers/go-digest) | ||||||
| - [selinux](https://github.com/opencontainers/selinux) | ||||||
|
|
||||||
| Utilities and end-user UX-oriented code is most likely better targeted at other | ||||||
| more broad communities like the [CNCF](https://cncf.io). While there are not | ||||||
| explicit rules, a discussion with the TOB is warranted for projects looking to | ||||||
| contribute a library to OCI. | ||||||
|
|
||||||
| ### Reference Implementations | ||||||
|
|
||||||
| While theoretically a specification can have one or more reference | ||||||
| implementations, the OCI runtime spec and the program, `runc`, have gone | ||||||
| hand in hand simply due to the particulars around the founding of the OCI. | ||||||
|
|
||||||
| It is not inconceivable that more reference implementations would be | ||||||
| contributed and supported within the OCI, but at this point, the only | ||||||
| active and viable reference implementation within the OCI is the `runc` | ||||||
| implementation of the runtime specification, based around the contributed | ||||||
| **libcontainer** codebase contributed by Docker. | ||||||
| - [runc](https://github.com/opencontainers/runc) | ||||||
|
|
||||||
| Runc is also unique in that it is an open source reference implementation, | ||||||
| but also a core dependent ecosystem component underneath the majority of | ||||||
| container engine implementations in use today. | ||||||
estesp marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| 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 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 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. |
||||||
| authored and accepted as well. | ||||||
|
|
||||||
| ## Should my Project be in the OCI? | ||||||
|
|
||||||
| 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 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. |
||||||
| 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. 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:
There was a problem hiding this comment. This section is updated significantly; would love your re-review/comments. |
||||||
| 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:
There was a problem hiding this comment. Reworded this section and used some of your suggested text above. |
||||||
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.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good question; let's discuss on the TOB call.