From f973869a42dd83c62d150c262836c1409da3b33c Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Thu, 18 Nov 2021 13:45:38 -0800 Subject: [PATCH 1/4] Proposal: working group for reference types Signed-off-by: Steve Lasker --- proposals/wg-reference-types.md | 86 +++++++++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 proposals/wg-reference-types.md diff --git a/proposals/wg-reference-types.md b/proposals/wg-reference-types.md new file mode 100644 index 0000000..a6bf46f --- /dev/null +++ b/proposals/wg-reference-types.md @@ -0,0 +1,86 @@ +# Working Group Proposal: Reference Types + +Proposal created from [OCI WG template](https://github.com/opencontainers/tob/blob/master/WG-TEMPLATE.md). + +Proposal copied from [Proposal: Working Group for Reference Types #96](https://github.com/opencontainers/tob/issues/96) + +## Reference Types OCI Working Group - Governance Charter + +This document describes the basic governance principles for the Reference Types 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 + +As cloud native development continues to grow, there is increased interest in evolving registries to natively store, discover, and pull a graph of content associated with specific container images in a registry. Use cases for said associated artifacts include but are not limited to Software Bill of Materials (SBoM), security scan results, and signing. Having a native way to store and discover artifacts associated with other artifacts enables end-users to answer the question of: “What SBOMs or signatures are associated with this container image?” + +## Scope + +* Define and deliver the capability to store, discover, and pull a graph of artifacts associated with a specific artifacts to OCI distribution compliant registries. These set of capabilities has been commonly known as "reference types" or "references". + * Define supported use cases + * Document impact to existing user-facing tools and registries + * Define the method for creating, distributing, and discovering referenced objects + * Document user expectations for promoting an artifact between registries with its references + * Document onboarding process for registries and user-facing tools to adopt reference types + * Defined expectations for artifact reference lifecycle management + * Deliver a reference implementation of the reference types proposal + +## Out of Scope + +* Identified out of scope items will be listed here as WG progresses + + +## Intended work product + +* Referrers API specification that provides the ability to discover references to existing container images. These include listing signatures, SBoMs, security scan results that refer to the digest of a manifest. The referrers API specification will sit within or along side the Distribution specification. +* Identify, and document the pros and cons for versioning the existing manifests, compared with creating a new manifest to support reference types. + +## Proposed Owners +* Lachlan Evenson (@lachie83) +* Justin Cormack (@justincormack) +* Michael Brown (@michaelb990) +* Derek McGowan (@dmcgowan) +* Jon Johnson (@jonjohnsonjr) + +## Sponsors + +* Microsoft +* AWS +* Docker + +## Related issues/PRs + +* https://github.com/opencontainers/tob/issues/96 +* https://github.com/opencontainers/artifacts/pull/27 +* https://github.com/opencontainers/artifacts/pull/29 +* https://github.com/opencontainers/artifacts/pull/37 +* https://github.com/opencontainers/image-spec/issues/827 +* https://github.com/opencontainers/image-spec/pull/828 +* https://github.com/oras-project/artifacts-spec/ + +## 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. \ No newline at end of file From fddaf1564ec354309d0af125d1c28de2e05e6d7d Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Mon, 22 Nov 2021 09:16:45 -0800 Subject: [PATCH 2/4] Changing sponsors to stakeholders, per PR feedback Signed-off-by: Steve Lasker --- proposals/wg-reference-types.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/proposals/wg-reference-types.md b/proposals/wg-reference-types.md index a6bf46f..8f242dd 100644 --- a/proposals/wg-reference-types.md +++ b/proposals/wg-reference-types.md @@ -29,20 +29,20 @@ As cloud native development continues to grow, there is increased interest in ev * Identified out of scope items will be listed here as WG progresses - ## Intended work product * Referrers API specification that provides the ability to discover references to existing container images. These include listing signatures, SBoMs, security scan results that refer to the digest of a manifest. The referrers API specification will sit within or along side the Distribution specification. * Identify, and document the pros and cons for versioning the existing manifests, compared with creating a new manifest to support reference types. ## Proposed Owners + * Lachlan Evenson (@lachie83) * Justin Cormack (@justincormack) * Michael Brown (@michaelb990) * Derek McGowan (@dmcgowan) * Jon Johnson (@jonjohnsonjr) -## Sponsors +## Stakeholders * Microsoft * AWS From 54eb9b71f755fcd9ace6146477d76b327d9db838 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Wed, 1 Dec 2021 10:34:59 -0800 Subject: [PATCH 3/4] Incorporate typo, linting feedback Signed-off-by: Steve Lasker --- proposals/wg-reference-types.md | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/proposals/wg-reference-types.md b/proposals/wg-reference-types.md index 8f242dd..cc499f4 100644 --- a/proposals/wg-reference-types.md +++ b/proposals/wg-reference-types.md @@ -2,7 +2,7 @@ Proposal created from [OCI WG template](https://github.com/opencontainers/tob/blob/master/WG-TEMPLATE.md). -Proposal copied from [Proposal: Working Group for Reference Types #96](https://github.com/opencontainers/tob/issues/96) +Proposal copied from [Proposal: Working Group for Reference Types #96](https://github.com/opencontainers/tob/issues/96). ## Reference Types OCI Working Group - Governance Charter @@ -12,22 +12,24 @@ The WG operates as an OCI Working Group under the [Open Container Initiative (OC ## Purpose -As cloud native development continues to grow, there is increased interest in evolving registries to natively store, discover, and pull a graph of content associated with specific container images in a registry. Use cases for said associated artifacts include but are not limited to Software Bill of Materials (SBoM), security scan results, and signing. Having a native way to store and discover artifacts associated with other artifacts enables end-users to answer the question of: “What SBOMs or signatures are associated with this container image?” +As cloud native development continues to grow, there is increased interest in evolving registries to natively store, discover, and pull a graph of content associated with specific container images in a registry. +Use cases for said associated artifacts include but are not limited to Software Bill of Materials (SBoM), security scan results, and signing. +Having a native way to store and discover artifacts associated with other artifacts enables end-users to answer the question of: “What SBOMs or signatures are associated with this container image?” ## Scope -* Define and deliver the capability to store, discover, and pull a graph of artifacts associated with a specific artifacts to OCI distribution compliant registries. These set of capabilities has been commonly known as "reference types" or "references". +* Define and deliver the capability to push, discover, and pull a graph of artifacts within OCI distribution compliant registries. These set of capabilities have been commonly known as "reference types" or "references". * Define supported use cases - * Document impact to existing user-facing tools and registries - * Define the method for creating, distributing, and discovering referenced objects - * Document user expectations for promoting an artifact between registries with its references + * Document impact to existing implementations + * Define the method for creating, distributing, discovering, and traversing a graph of referenced objects + * Document user expectations for promoting an artifact and its references between registries * Document onboarding process for registries and user-facing tools to adopt reference types - * Defined expectations for artifact reference lifecycle management + * Define expectations for artifact reference lifecycle management * Deliver a reference implementation of the reference types proposal ## Out of Scope -* Identified out of scope items will be listed here as WG progresses +* Identified out of scope items will be listed here as WG progresses. ## Intended work product From 0e68daac7640625e43e4ad8c2e6419eb3ececfcf Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Wed, 1 Dec 2021 11:18:00 -0800 Subject: [PATCH 4/4] Incorporate pr feedback around extending existing or creating a new manifest Signed-off-by: Steve Lasker --- proposals/wg-reference-types.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/wg-reference-types.md b/proposals/wg-reference-types.md index cc499f4..2129f46 100644 --- a/proposals/wg-reference-types.md +++ b/proposals/wg-reference-types.md @@ -35,6 +35,7 @@ Having a native way to store and discover artifacts associated with other artifa * Referrers API specification that provides the ability to discover references to existing container images. These include listing signatures, SBoMs, security scan results that refer to the digest of a manifest. The referrers API specification will sit within or along side the Distribution specification. * Identify, and document the pros and cons for versioning the existing manifests, compared with creating a new manifest to support reference types. +* Proposal to extend existing manifests or create a new manifest to support reference types. ## Proposed Owners