From 2ae379bf22b5ad0331494bfd5889cfac6fa25b6e Mon Sep 17 00:00:00 2001 From: Phil Estes Date: Tue, 12 May 2020 19:22:59 -0400 Subject: [PATCH 1/2] Draft of a "getting started" document for the OCI Signed-off-by: Phil Estes --- GETTING_STARTED.md | 127 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 GETTING_STARTED.md diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md new file mode 100644 index 0000000..b5c7432 --- /dev/null +++ b/GETTING_STARTED.md @@ -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 +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. + +## 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. +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 +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 +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 +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. + +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 +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. + 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. From 13ba1d079f32c23296c8812db1d52cbaf4944136 Mon Sep 17 00:00:00 2001 From: Phil Estes Date: Thu, 4 Jun 2020 15:36:52 -0400 Subject: [PATCH 2/2] Updates based on May 2020 comments/reviews Signed-off-by: Phil Estes --- GETTING_STARTED.md | 108 +++++++++++++++++++++++++++++++-------------- 1 file changed, 75 insertions(+), 33 deletions(-) diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index b5c7432..6e315d9 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -7,14 +7,19 @@ 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. +**Note:** If there are any perceived or real conflicts between this document +and the OCI Charter, the OCI Charter takes precedence as the official governing +document of the Open Container Initiative. + ## 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 -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. +The [OCI website](https://opencontainers.org) has since inception carried a +mission statement that defined us as "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 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 @@ -33,10 +38,12 @@ 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. -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. +of OCI into ongoing support of additional types within registries and related +cloud native tools. 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, and allows for further experimentation with arbitrary file types +within the context of this stable andd well-defined capability. **Implementors** own projects outside the OCI for which they have determined value in being "OCI compliant"; whether that's a registry, a unique container @@ -69,6 +76,14 @@ tools which interact with container images and registries. - [Image spec](https://github.com/opencontainers/image-spec) - [Distribution spec](https://github.com/opencontainers/distribution-spec) +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. + - [Artifacts](https://github.com/opencontainers/artifacts) + ### Spec Conformance Test Conformance tests should provide a clear, end-user runnable test suite for @@ -94,34 +109,61 @@ 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. +The OCI does not require that its specifications have reference +implementations, and any project which aims to be adopted by the OCI as a +reference implementation has to be judged on its own merits. Reference +implementations should be generally usable as a building block for other +programs (thus should not be *overly opinionated*) and should have their +features limited to the set of features outlined by the relevant specification. +In addition, the popularity of the project (especially in production use-cases) +should be taken into consideration: reference implementations should be +battle-tested, after all. + +The first (and currently only viable) reference implementation included in the +OCI was runc, as a reference implementation of the OCI runtime specification. +This project's inclusion is a slight oddity of history, having been a +production-ready project predating the OCI's formation and was included in the +OCI as part of the original draft runtime specification. However this strange +history does not preclude the addition of any new reference implementations, +merely that this is a process which is not well-established in the OCI and thus +any proposed projects need to have significant justification for inclusion. -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. - -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 -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. - 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. +intangible goal. However, the following considerations are provided +to help guide potential submissions. + + * The OCI is not directly chartered for the advancement, marketing, and + support of general cloud native software projects. As our charter states: *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.* + * The project should be a piece of "**boring core container infrastructure**". + While this is partially subjective criterion, the key factors towards + fulfilling this requirement are: + 1. The project should be as un-opinionated and extensible as is reasonably + possible. + 2. Rather than being a complete solution or framework, the project should be + usable as a building-block for larger solutions and frameworks. + 3. Projects consumed via a UI and/or including a significant end user + experience component may be one clear sign of a lack of fit with the OCI + as one example. + * Proposed projects should fit logically into the scope and mission of the + OCI: a home for open standards and tools which underpin the wider container + ecosystem. Proposed additions to the OCI should not conflict with existing OCI + projects, nor should they 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. + +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 +or grow a community around an untested or experimental new project is highly +unlikely to fit the more narrow scope and mission of the OCI. We recommend +the CNCF as a much more suitable target for such projects given the maturity +model and sandbox starting point within that community.