├── CODEOWNERS ├── GOVERNANCE.md ├── LICENSE ├── README.md ├── docs ├── PERSONAS.md ├── REQUIREMENTS.md ├── RUBRIC.md ├── TEMPLATE.md ├── UPGRADING.md └── proposals │ ├── PROPOSAL_A.md │ ├── PROPOSAL_B.md │ ├── PROPOSAL_C.md │ ├── PROPOSAL_D.md │ ├── PROPOSAL_E.md │ └── PROPOSAL_F.md └── minutes ├── 2022-03-08.md ├── 2022-03-15.md ├── 2022-03-22.md ├── 2022-03-29.md ├── 2022-04-05.md ├── 2022-04-12.md ├── 2022-04-19.md ├── 2022-04-26.md ├── 2022-05-03.md ├── 2022-05-10.md ├── 2022-05-17.md ├── 2022-05-24.md ├── 2022-05-31.md ├── 2022-06-07.md ├── 2022-06-14.md ├── 2022-06-26.md ├── 2022-07-05.md ├── 2022-07-12.md ├── 2022-07-19.md ├── 2022-07-26.md ├── 2022-08-02.md ├── 2022-08-09.md └── 2022-08-16.md /CODEOWNERS: -------------------------------------------------------------------------------- 1 | * @dmcgowan @imjasonh @jdolitsky @jonjohnsonjr @justincormack @lachie83 @michaelb990 @nishakm @stevelasker @sudo-bmitch 2 | -------------------------------------------------------------------------------- /GOVERNANCE.md: -------------------------------------------------------------------------------- 1 | # Reference Types Working Group Governance 2 | 3 | ## Discussion 4 | 5 | - Discussions take place on GitHub's [discussion board](https://github.com/opencontainers/wg-reference-types/discussions) and during [weekly meetings](https://github.com/opencontainers/wg-reference-types/blob/main/README.md#meetings). 6 | - Notes taken during the community meetings are recorded in [this hackmd document](https://hackmd.io/bGIxKAxPROi8KlwZMQioXQ), and later migrated to the [minutes](./minutes) folder via pull request. 7 | 8 | Discussions shall follow the [documented personas](https://github.com/opencontainers/wg-reference-types/blob/main/docs/PERSONAS.md) previously decided by this working group. Changes to the framework are encouraged via GitHub discussions, issues, and pull requests. 9 | 10 | Working group members and maintainers shall follow the [OCI code of conduct](https://github.com/opencontainers/.github/blob/master/CODE_OF_CONDUCT.md) 11 | 12 | ## Documentation 13 | 14 | - Meeting minutes shall be published on this GitHub repository. 15 | - A notetaker shall be identified to take notes during the meetings. 16 | - The notetaker shall either transfer the notes to the GitHub repository or work with a maintainer to transfer notes. 17 | - Notes for each day shall be recorded in markdown with the name of the form `yyyy-mm-dd.md` and submitted to the [minutes](./minutes) folder using a pull request. 18 | - Consensus shall be documented in the form of GitHub issues that can be referenced in pull requests. 19 | 20 | ## Maintainer Operations 21 | 22 | The list of current maintainers shall be recorded in the [CODEOWNERS](https://github.com/opencontainers/wg-reference-types/blob/main/CODEOWNERS) document. 23 | 24 | - Maintainers shall be responsible for overseeing documentation of community decisions, consensus, and resolution of conflicts. 25 | - Maintainers shall provide timely feedback to requests for review and promptly merge approved Pull Requests. 26 | - Maintainers shall operate in good faith and trust in the community and in each other. 27 | - Maintainers shall keep the documentation, issues, and discussion topics as up-to-date as possible. 28 | - In the event a Maintainer cannot perform their duties or have been inactive for a period of time, an interim or permanent replacement shall be nominated from the community. 29 | - Consensus on unblocking inactivity or deadlock must be reached in a community meeting and recorded in the meeting minutes. 30 | - Any member from the community may volunteer to be a maintainer as long as they pledge to follow the OCI code of conduct and perform these duties. 31 | 32 | ## Conflict Resolution 33 | 34 | - In the event of a conflict, group members are encouraged to fall back on the [documented personas](https://github.com/opencontainers/wg-reference-types/blob/main/docs/PERSONAS.md) in order to express their concerns. 35 | - Conflicts that cannot be resolved within the group shall be referred to the OCI Technical Oversight Board (TOB) as per [section 5.xv](https://github.com/opencontainers/tob/blob/main/CHARTER.md#5-technical-developer-community) of the TOB Charter. 36 | - Resolution of the conflict shall be documented on this GitHub respository's issues which can be referred to in a pull request. 37 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # OCI Working Group: Reference Types 2 | 3 | ## Status 4 | 5 | This WG has met the mission statement below and has now been archived. 6 | 7 | ## Mission Statement 8 | 9 | Propose how to describe and query relationships between objects stored in an OCI registry. 10 | 11 | ## Background 12 | 13 | Here is the [link](https://github.com/opencontainers/tob/blob/main/proposals/wg-reference-types.md) 14 | to the original proposal to create this working group. 15 | 16 | ## Governance 17 | 18 | Link to [governance](./GOVERNANCE.md) document. 19 | 20 | ## Meetings 21 | 22 | * WG Meeting: [Tuesdays at 11:00am PT (Pacific Time)](https://zoom.us/j/92128676364) (weekly). [Convert to your timezone](https://dateful.com/convert/pt-pacific-time?t=11am). 23 | * [Meeting notes and Agenda](https://hackmd.io/bGIxKAxPROi8KlwZMQioXQ?edit). 24 | * [Past Meetings](https://github.com/opencontainers/wg-reference-types/tree/main/minutes). 25 | * [Initial Google Doc](https://docs.google.com/document/d/1SVOWQTowigXzbYdorzfa7tMmrcm91yK12LvSONqziJY/edit) 26 | 27 | ## Completed 28 | 29 | ### Upstream Changes 30 | 31 | The following PRs were merged upstream based on 32 | [Proposal E](./docs/proposals/PROPOSAL_E.md). 33 | 34 | * https://github.com/opencontainers/distribution-spec/pull/335 35 | * https://github.com/opencontainers/image-spec/pull/934 36 | 37 | ### Proposals 38 | 39 | The following proposal ("E") is now frozen and has been proposed and merged upstream: 40 | 41 | | ID | Link | Description | 42 | | -- | -------------------------------------- | ------------ | 43 | | E | [View](./docs/proposals/PROPOSAL_E.md) | Cherry pick | 44 | 45 | ### Inactive Proposals 46 | 47 | After much discussion, the following proposals are no longer being evaluated by the WG: 48 | 49 | | ID | Link | Description | 50 | | -- | -------------------------------------- | ------------------------------------------------------------------------- | 51 | | A | [View](./docs/proposals/PROPOSAL_A.md) | Defines a new artifact manifest and corresponding referrers extension API | 52 | | B | [View](./docs/proposals/PROPOSAL_B.md) | Add "reference" field to existing schemas | 53 | | C | [View](./docs/proposals/PROPOSAL_C.md) | Create Node manifest | 54 | | D | [View](./docs/proposals/PROPOSAL_D.md) | No Changes | 55 | | F | [View](./docs/proposals/PROPOSAL_F.md) | OCI Index references it all | 56 | 57 | ### Documents 58 | 59 | The following documents are actively being updated by the WG: 60 | 61 | | Document | Description | 62 | | --------------------------------------- | ---------------------------------------------------------------- | 63 | | [Personas](./docs/PERSONAS.md) | A friendly frame of reference to characterize our design goals | 64 | | [Requirements](./docs/REQUIREMENTS.md) | A list of requirements identified by the WG | 65 | | [Upgrading](./docs/UPGRADING.md) | A description of upgrade scenarios at various stages of adoption | 66 | | [Proposal Template](./docs/TEMPLATE.md) | A template for submitting a new reference types proposal | 67 | | [Evaluation Rubric](./docs/RUBRIC.md) | A comparison matrix of proposals to use cases | 68 | 69 | ## Organizers 70 | 71 | * Lachlan Evenson (@lachie83) 72 | * Justin Cormack (@justincormack) 73 | * Michael Brown (@michaelb990) 74 | * Derek McGowan (@dmcgowan) 75 | * Jon Johnson (@jonjohnsonjr) 76 | 77 | ## Contact 78 | 79 | * Slack: [#wg-reference-types](https://opencontainers.slack.com/messages/wg-api-expression) 80 | * [GitHub Discussions](https://github.com/opencontainers/wg-reference-types/discussions) 81 | -------------------------------------------------------------------------------- /docs/PERSONAS.md: -------------------------------------------------------------------------------- 1 | # Personas 2 | 3 | In order to abstract away from specific use cases and 4 | implementation details, we will use terms from the story 5 | of *Glen and Larry’s Ice Cream Company*. 6 | 7 | Each persona describes those involved in the 8 | ice cream supply chain, and has a relevant parallel 9 | relating to OCI and the surrounding software ecosystem. 10 | 11 | In this document, we aim to characterize which persona(s) 12 | this working group is designing around. 13 | 14 | ## Which persona are we designing around? 15 | 16 | From the list of below, we are primarily designing to improve 17 | the function of 18 | **(3) The Refrigerated Truck Driver**. 19 | 20 | This working group is equivalent to the strategy 21 | team within the logitisics arm of *Glen and Larry's*. 22 | 23 | How do we improve our capabilities and efficiency as ice cream 24 | travels between the factory conveyor belt to the shelves of the bodega? 25 | 26 | What new technology can we introduce to enhance this process? 27 | How can we do so in a way that will be embraced by both factories 28 | and bodegas with minimal effort? 29 | 30 | How do we ensure business continues to operate smoothly if 31 | not everyone adopts our new process on day 1? 32 | 33 | ## List of personas 34 | 35 | ### 1. The Dairy Farmer 🐮 36 | 37 | The people who provide the raw ingredients used to make 38 | the ice cream 39 | 40 | Real-world parallel: 41 | 42 | - Open source project maintainers 43 | 44 | ### 2. The Ice Cream Factory Worker 🏭 45 | 46 | The people who produce the ice cream and are responsible 47 | for its contents 48 | 49 | Real-world parallel: 50 | 51 | - Development teams building custom software components 52 | 53 | ### 3. The Refrigerated Truck Driver 🚚 54 | 55 | The people responsible for safely delivering ice cream from 56 | the factory to the purchaser 57 | 58 | Real-world parallel: 59 | 60 | - Hosted OCI registry vendors 61 | 62 | ### 4. The Bodega Owner 🏪 63 | 64 | The people who receive the ice cream from the truck driver 65 | and place it on their shelves 66 | 67 | Real-world parallel: 68 | 69 | - Production environments 70 | - Kubernetes admission controllers 71 | 72 | ### 5. The Ice Cream Lover 😍 73 | 74 | The people who actually purchase and consume the ice cream 75 | 76 | Real-world parallel: 77 | 78 | - End-users of the software product 79 | 80 | ### 6. The Health Inspector 🕵️‍♀️ 81 | 82 | The people who make sure that the ice cream is safe to eat 83 | at various stages in the process 84 | 85 | Real-world parallel: 86 | 87 | - Security teams 88 | - Auditors 89 | -------------------------------------------------------------------------------- /docs/REQUIREMENTS.md: -------------------------------------------------------------------------------- 1 | # Requirements 2 | 3 | This document contains a list of requirements identified 4 | to be considered in all proposals originating from this WG. 5 | 6 | The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119) (Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997). 7 | 8 | ## Member-submitted user stories (Distilled) 9 | 10 | ### Top level definitions 11 | 12 | - An OCI artifact is defined as any artifact that is to be stored in an OCI registry. 13 | - A container image is a specialized OCI artifact as defined by the OCI [image](https://github.com/opencontainers/image-spec) and [runtime](https://github.com/opencontainers/runtime-spec) specifications. 14 | 15 | ### User stories 16 | 17 | The following are categorized user stories 18 | 19 | #### Filtering 20 | 21 | 1. As a user, I want to query a registry for a stored artifact by its digest or tag. 22 | 1. As a user, I want to query the registry for all stored artifacts that reference a given artifact by its digest or tag. 23 | 1. As a user, I want to query a registry for all stored artifacts of a particular type that reference a given artifact by its digest or tag. 24 | 1. As a user, I want to query a registry for all stored artifacts based on annotations that reference a given artifact by its digest or tag. 25 | 1. As a user, I want to fetch the most up-to-date artifact, collection of artifacts, or application. 26 | 1. As an artifact producer, I want to reduce the number of tags that reference an artifact. 27 | 28 | #### Backwards Compatibility 29 | 30 | 1. As a user, I want to be sure that existing container runtimes are not affected by any other type of registry artifact. 31 | 1. As a user, I want to move container images to and from registries that do not support reference types. 32 | 1. As an artifact producer, I want to tag artifacts that I can pull by said tag, even if they contain references to other artifacts. 33 | 1. As an artifact producer, I want be sure that pushing an artifact to a repository will not affect a copy of the same artifact previously created and referenced by a manifest list existing in another repository on the same registry. 34 | 1. As a tool writer, I want to identify whether a registry supports reference types or not. 35 | 1. As a tool writer, I would like the option to perform a server side blob mount when copying a large artifact between repositories. 36 | 1. As a tool writer, I want to be able to include reference types within the Image Layout filesystem format. 37 | 38 | #### Content Management 39 | 40 | 1. As a user, I want to store one or more artifacts in a registry with a reference to another related artifact. 41 | 1. As a user, when I delete an artifact, I want the option to delete one or more artifacts referencing it. 42 | 1. As a user, I want to push an artifact that references another artifact that doesn't exist on the registry yet. 43 | 1. As a user, I want to move an artifact and one or more artifacts referencing it from one registry to another. 44 | 1. As a registry operator, I want to help users understand how they can manage the lifecycle of their artifacts. 45 | 1. As a registry operator, I want to allow users to "lock" the tags to their artifacts. 46 | 1. As an artifact producer, I want to update an existing artifact with a newer artifact. 47 | 1. As an artifact producer, I want to push multiple artifacts concurrently (possibly from separate systems) without encountering race conditions or other errors. 48 | 1. As an artifact author, I want to document other artifacts in one or more registries that my artifact requires and/or provides. 49 | 1. As a user, I want assurances that the object I found really did come from the claimed supplier. 50 | 1. As an artifact author, I want to add assurances that the artifact originated from me. 51 | 1. As a registry operator, I want to provide users with retention policies for their artifacts. 52 | 1. As a user, I want to apply timestamp or numerical ranges on my artifacts so I can apply retention policies on them. 53 | 54 | ## Member-submitted user stories (Raw) 55 | 56 | The following user stories have been submitted by members of 57 | the WG, and MAY be converted to official requirements. 58 | 59 | Stated more clearly, just because something is listed below does 60 | not necessarily mean this WG has reached consensus to support 61 | the use case. 62 | 63 | Titles of subsections below are the name of the member who 64 | originally submitted them. 65 | 66 | *General note: a lot of these say "container image" to ground them 67 | in a non-controversial real world scenario; in general a lot of 68 | these apply to Artifacts too* 69 | 70 | ### Lachlan 71 | 72 | - As a user, I want to store a signature/SBOM/etc in a registry along with a reference to the container image (by digest?) it is for 73 | - As a user, I want to query the registry the signatures for a container image by name and tag 74 | - As a user, I want to query the registry for all stored objects that reference a container image by name and tag 75 | - As a user, I want to query the registry for stored objects that reference a container image filtering by type (eg. Signature, SBOM, etc) or by annotation (I want to see all signatures from this identity) 76 | - As a user, I want to store a signature for an SBOM in a registry along with a reference to SBOM it is for 77 | - As a user, I want to store a signature for an SBOM in a registry along with a reference to SBOM it is for 78 | - As a user, I want to query the registry for the most recent stored objects that reference a container image 79 | - As a user, I want all stored objects that reference a container image to be deleted when a container image is deleted 80 | - As a user, I want to be able to store a SBOM or signature in a registry without the container image it’s for 81 | - As a user, I want to be able to copy a container image and all it’s references to another registry 82 | 83 | ### Steve 84 | 85 | - As a user, I want to copy a container image, and a subset of its references to another registry 86 | - As a user, I want to view the top-level container images in a registry through tags, but only see the references as a selected detail 87 | - As a registry operator, I want to help users understand how they can manage the lifecycle of their container images and their references 88 | - As a registry operator, I want to provide tag locking features that don’t preclude users from adding signatures or SBOMs to a tagged artifact 89 | - As an artifact author, I want to use multiple blobs/layers for reference types 90 | - As an artifact author, I want to push annotations (without blob data) as additional metadata, as reference types 91 | - As a security admin, I want to assure non-container artifacts, pushed to a registry doesn't add security risks to container runtime services that may pull the reference type 92 | - As a container image author, I want to support promotion of container images, and their references, across registries that may not yet support references 93 | - As a security scanner project/product, I want to know the type of each artifact so I know how to scan it for vulnerabilities, or if I should scan it. (example, scanners evaluate signatures, but don’t "scan" them) 94 | 95 | ### Nisha 96 | 97 | - As a user, I want to identify the most updated artifact in a registry 98 | - As a user, I would like to be able to map monotonically increasing product versions to container images so I have an idea of deployment progression 99 | - As a developer/devopser, I would like to bisect builds based on container images I have deployed 100 | 101 | ### Josh 102 | 103 | - As a user, I want to store images in one registry, and signatures/SBOMs/attestations in a separate registry 104 | 105 | ### Brandon 106 | 107 | - As an artifact producer, I want to be able to create multiple artifacts referring to the same manifest, and upload them separately 108 | - As an artifact producer, I would like to push multiple artifacts concurrently (possibly from separate systems) without encountering race conditions or other errors 109 | - As an artifact producer, I would like to be able to push an artifact to a registry, associated with another manifest, and not need to tag that artifact (reducing tag clutter) 110 | - As an artifact producer, I want to push an artifact to a registry with a tag so it can be pulled directly, in addition to having references to other manifests in the registry 111 | - As an artifact producer, I would like an efficient way to update an existing artifact with a newer version (replacing an expiring signature) 112 | - As an artifact producer, pushing an artifact to one repository should not impact the associated artifact list on a copy of the manifest previously created in another repository on the same registry 113 | - As a tool writer, I would like to be able to efficiently query artifacts of different types attached to a given digest 114 | - As a tool writer, I would like to be able to query for a specific artifact based on artifact type and other user defined annotations on the artifact 115 | - As a tool writer, I would like to be able to identify when a registry does not support the new APIs 116 | - As a tool writer, I want to be able to include reference types within the Image Layout filesystem format and have a way to lookup those reference types without reading the blob for every manifest 117 | - As a tool writer, I would like to perform a server side blob mount when copying a large artifact between repositories 118 | - As a user, I would like to walk the CAS tree in reverse. This would allow a query of all manifests pointing to a blob digest, and all manifest lists pointing to a manifest digest 119 | - As a registry operator, I want attempts to push artifacts to an older registry to have a minimal impact (e.g. artifacts are not missed by GC causing bloating of storage, and a tagged artifact does not break tag listings) 120 | - As a user, I would like graceful degradation if the registry does not support the new ref types. This would either be some kind of limited fall back support or a clear error message from tooling 121 | - As a user, I want to be sure existing runtimes are not affected by any of the new reference types added to images 122 | -------------------------------------------------------------------------------- /docs/RUBRIC.md: -------------------------------------------------------------------------------- 1 | # Proposal Evaluation Rubric 2 | 3 | This Rubric is based on the [user stories](https://github.com/opencontainers/wg-reference-types/blob/main/docs/REQUIREMENTS.md#user-stories) assembled by community members. 4 | 5 | *WARNING* As discussed during the community meeting dated [March 1, 2022](https://docs.google.com/document/d/1SVOWQTowigXzbYdorzfa7tMmrcm91yK12LvSONqziJY/edit#heading=h.qv9hc0gujvjj), this rubric is not meant to score the "best" proposal, but to evaluate what specific changes can be proposed to the OCI specifications. 6 | 7 | The Rubric will be updated based on consensus reached in the community meetings. 8 | 9 | Key: 10 | - F: Filtering 11 | - B: Backwards Compatibility 12 | - C: Content Management 13 | 14 | |User Stories|Proposal A|Proposal B|Proposal C|Proposal D|Proposal E|Proposal F| 15 | 16 | |--- |--- |--- |--- |--- |--- |--- | 17 | |**F.1**| | | | | | | 18 | |**F.2**| | | | | | | 19 | |**F.3**| | | | | | | 20 | |**F.5**| | | | | | | 21 | |**F.6**| | | | | | | 22 | |**B.1**| | | | | | | 23 | |**B.2**| | | | | | | 24 | |**B.3**| | | | | | | 25 | |**B.4**| | | | | | | 26 | |**B.5**| | | | | | | 27 | |**B.6**| | | | | | | 28 | |**C.1**| | | | | | | 29 | |**C.2**| | | | | | | 30 | |**C.3**| | | | | | | 31 | |**C.4**| | | | | | | 32 | |**C.5**| | | | | | | 33 | |**C.6**| | | | | | | 34 | |**C.7**| | | | | | | 35 | |**C.8**| | | | | | | 36 | |**C.9**| | | | | | | 37 | |**C.10**| | | | | | | 38 | |**C.11**| | | | | | | 39 | |**C.12**| | | | | | | 40 | |**C.13**| | | | | | | 41 | -------------------------------------------------------------------------------- /docs/TEMPLATE.md: -------------------------------------------------------------------------------- 1 | # Proposal \ 2 | 3 | Short description here that will fit neatly in the README table 4 | 5 | ## Description 6 | 7 | Longer description here in 100 words or less. Cras imperdiet nisl odio, sed fermentum urna consequat eu. Integer sed condimentum turpis. Vestibulum at ultrices nunc. Suspendisse semper lectus ut dolor maximus ornare. 8 | 9 | Etiam eu dolor tellus. Suspendisse sed eros vulputate, cursus urna eget, interdum nunc. Morbi sagittis ante sed eros hendrerit placerat. Aliquam sagittis blandit velit eget ullamcorper. Vivamus hendrerit egestas dui, non fringilla risus. 10 | 11 | Vestibulum blandit nec ex in fringilla. Nam lacus diam, interdum id quam sed, sollicitudin tincidunt quam. Integer eget magna erat. Sed vel efficitur quam, id viverra lacus. Curabitur sapien nisi, placerat quis dapibus ut, malesuada. 12 | 13 | ## Links 14 | 15 | | Description | Link | 16 | | ------------------------------------------- | --------------------------- | 17 | | GitHub issue where this was first proposed | [View](https://example.com) | 18 | | Sample code of a working proof-of-concept | [View](https://example.com) | 19 | | Blog post which proves the point | [View](https://example.com) | 20 | 21 | ## Modifications 22 | 23 | ### JSON Schema 24 | 25 | In this section, explain any modifications which may be needed in the existing schema of 26 | JSON manifests, indexes, etc. 27 | 28 | If no modifications are required, describe how you propose to use the existing schema 29 | to achieve the goals of this working group. 30 | 31 | Include code blocks of JSON with comments to illustrate your proposal: 32 | 33 | ```jsonc 34 | { 35 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 36 | ... 37 | "icecream": "r.example.com/flavors/chocolate:0.1.0" // <-- Remote ref here 38 | } 39 | ``` 40 | 41 | The field `icecream` above is used to link a container image to an ice cream cone. 42 | 43 | ### Registry HTTP API 44 | 45 | In this section, explain any modifications which may be needed in HTTP API used to 46 | interact with registries. 47 | 48 | If no modifications are required, describe how you propose to use the existing API 49 | to achieve the goals of this working group. 50 | 51 | Include code blocks of sample HTTP requests to illustrate your proposal: 52 | 53 | ```text 54 | GET /v2//manifests//icecream 55 | ``` 56 | 57 | Response: 58 | 59 | ```jsonc 60 | { 61 | "flavors": { 62 | "chocolate": { 63 | "providers": [ 64 | "r.example.com/flavors/chocolate:0.1.0" 65 | ] 66 | } 67 | } 68 | } 69 | ``` 70 | 71 | ## Requirements 72 | 73 | In this section, copy the distilled user stories from [REQUIREMENTS.md](REQUIREMENTS.md) and include a description of how each is handled by this proposal. 74 | 75 | ### Filtering 76 | 77 | 1. As a user, I want to query a registry for a stored artifact by its digest or tag. 78 | - Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. 79 | 1. As a user, I want to query the registry for all stored artifacts that reference a given artifact by its digest or tag. 80 | - Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. 81 | ... 82 | -------------------------------------------------------------------------------- /docs/UPGRADING.md: -------------------------------------------------------------------------------- 1 | # Upgrading 2 | 3 | This document is a place to outline the upgrade path for 4 | both clients and vendors, considering that not all will adopt 5 | the processes designed by this WG at once (or perhaps ever). 6 | 7 | ## Proposal E 8 | 9 | The following section describes the upgrade path for 10 | [Proposal E](./proposals/PROPOSAL_E.md). 11 | 12 | ### Component defintions 13 | 14 | The following icons and definitions will be used to illustate various scenarios 15 | in the context of this document. 16 | 17 | #### Producer 18 | 19 | A producer of images and/or artifacts (a client that "pushes") 20 | 21 | | Icon | State | Description | 22 | | ----------------- | ------------ | ------------------------------------ | 23 | | 🌱 (leaf) | Current | Build tooling that does not push references | 24 | | 🌿 (tree branch) | Intermediate | Pushes image-spec manifests with "refers" field, includes tags if refers API missing | 25 | | 🌲 (whole tree) | Complete | Pushes references using new manifest | 26 | 27 | #### Registry 28 | 29 | A service that hosts images and/or artifacts 30 | 31 | | Icon | State | Description | 32 | | -------------- | ------------ | -- | 33 | | 🚲 (bicycle) | Current | References supported via tags/"refers" field in existing image-spec manifest | 34 | | ~~🛵 (moped)~~* | ~~Intermediate~~ | ~~N/A~~ | 35 | | 🏍 (motocycle) | Complete | Supports new API and manifest | 36 | 37 | *\* It has been determined that there is not a valid "Intermediate" registry state.* 38 | 39 | #### Consumer 40 | 41 | A consumer of images and/or artifacts (a client that "pulls") 42 | 43 | | Icon | State | Description | 44 | | ------------- | ------------ | -- | 45 | | 🐀 (rat) | Current | Existing runtime that is unaware of refers | 46 | | 🐿 (squirrel) | Intermediate | Discovers image-spec manifest references via refers API, falls back to tags if refers API is missing | 47 | | 🦫 (beaver) | Complete | Discovers referrers via new API and manifest | 48 | 49 | ### Scenarios 50 | 51 | There are a total of 18 component combinations listed below. 52 | Note: supported scenarios have descriptions in **bold**. 53 | 54 | | | Producer | Registry | Consumer | Description | 55 | | - | ----------|----------|----------|-------------| 56 | | 1 | 🌱 | 🚲 | 🐀 | **Present state, no refers** | 57 | | 2 | 🌱 | 🚲 | 🐿 | **Consumer looking for refers that don't exist** | 58 | | 3 | 🌱 | 🚲 | 🦫 | **Consumer looking for refers that don't exist** | 59 | | 4 | 🌱 | 🏍 | 🐀 | **Present state, no refers** | 60 | | 5 | 🌱 | 🏍 | 🐿 | **Consumer looking for refers that don't exist** | 61 | | 6 | 🌱 | 🏍 | 🦫 | **Consumer looking for refers that don't exist** | 62 | | 7 | 🌿 | 🚲 | 🐀 | **Producer creating refers, consumer isn't using refers and is not impacted** | 63 | | 8 | 🌿 | 🚲 | 🐿 | **Producer / consumer working in compatibility mode with tags** | 64 | | 9 | 🌿 | 🚲 | 🦫 | **Consumer wants artifact-spec, but can fall back to image-spec refers using tags** | 65 | | 10 | 🌿 | 🏍 | 🐀 | **Producer creating refers, consumer isn't using refers and is not impacted** | 66 | | 11 | 🌿 | 🏍 | 🐿 | **Producer / consumer using image-spec manifests and referrers API** | 67 | | 12 | 🌿 | 🏍 | 🦫 | **Producer pushes image-spec manifest, consumer discovers refers via new API and would prefer new manifest** | 68 | | 13 | 🌲 | 🚲 | 🐀 | Producer attempts to push new manifest, registry rejects as new manifest is unknown | 69 | | 14 | 🌲 | 🚲 | 🐿 | Producer attempts to push new manifest, registry rejects as new manifest is unknown | 70 | | 15 | 🌲 | 🚲 | 🦫 | Producer attempts to push new manifest, registry rejects as new manifest is unknown | 71 | | 16 | 🌲 | 🏍 | 🐀 | **Producer creates new manifest, consumer isn't using refers and is not impacted** | 72 | | 17 | 🌲 | 🏍 | 🐿 | Producer pushes new manifest, consumer finds refers via new API but cannot parse new manifest | 73 | | 18 | 🌲 | 🏍 | 🦫 | **Producer and consumer both use new manifest and API** | 74 | 75 | ### Registry Transition 76 | 77 | 1. Registry in current state, referrers pushed as tags. Registries should not block refer field in manifests, but do not need to parse it. 78 | 2. Registry indexes refer field in new manifests, reindexes old manifests with a digest tag. 79 | 3. Registry enables referrers API and artifact manifest, clients stop pushing or querying digest tags. 80 | 81 | ## Extensions API for Distribution 82 | 83 | Beginning in OCI Distribution Spec v1.1.0 (not yet released), the 84 | [Extensions API for Distribution](https://github.com/opencontainers/distribution-spec/tree/main/extensions) 85 | will provide a method for asking a registry (or individual repository) for which extensions are supported: 86 | 87 | ```HTTP 88 | GET /v2/_oci/ext/discover 89 | ``` 90 | 91 | ```HTTP 92 | GET /v2/{name}/_oci/ext/discover 93 | ``` 94 | 95 | ```HTTP 96 | 200 OK 97 | Content-Length: 98 | Content-Type: application/json 99 | 100 | { 101 | "extensions": [ 102 | { 103 | "name": "_", 104 | "description": "", 105 | "url": "..." 106 | } 107 | ] 108 | } 109 | ``` 110 | 111 | This may provide a useful upgrade path as new APIs designed by this WG are 112 | proposed but not yet accepted by other parts of the OCI and wider community. 113 | -------------------------------------------------------------------------------- /docs/proposals/PROPOSAL_A.md: -------------------------------------------------------------------------------- 1 | # Proposal A 2 | 3 | Defines a new artifact manifest and corresponding referrers extension API. 4 | 5 | ## Description 6 | 7 | Provides a new manifest type, with an optional `subject` reference to another manifest (runtime image), an `artifactType` to differentiate types of artifacts (signatures, sboms, security scan results) and renames `layers` to optional `blobs`. 8 | 9 | The modifications include: 10 | 11 | - [New artifact manifest](#description) 12 | - [Descriptor (OPTIONAL) additional property](#descriptor-properties) 13 | - [Distribution - Referrers API](#registry-http-api) 14 | 15 | ## Links 16 | 17 | | Description | Link | 18 | | ------------------------------------------- | --------------------------- | 19 | | GitHub issue where this was first proposed: | [OCI Artifact Manifest - with weak reference support #27](https://github.com/opencontainers/artifacts/pull/27)
[OCI Artifact Manifest, Phase 1-Reference Types #29](https://github.com/opencontainers/artifacts/pull/29) | 20 | | Current ORAS Specifications: | [Manifest](https://github.com/oras-project/artifacts-spec/blob/main/artifact-manifest.md) and [Referrers API](https://github.com/oras-project/artifacts-spec/blob/main/manifest-referrers-api.md) | 21 | | Implementations | Registry: [ORAS Fork of CNCF Distribution (WIP)](https://github.com/oras-project/distribution/tree/ext_oras)
Registry: [ZOT Project (merged)](https://github.com/project-zot/zot/issues/264)
Registry client: [oras-project/oras/tree/artifacts](https://github.com/oras-project/oras/tree/artifacts) | 22 | 23 | ## Modifications 24 | 25 | The Artifact manifest is similar to the [OCI image manifest][oci-image-manifest-spec], but removes constraints defined on the image-manifest such as a required `config` object and required & ordinal `layers`. 26 | It adds a `subject` property supporting a graph of independently linked artifacts. 27 | The addition of a new manifest does not change, nor impact the `image.manifest`. 28 | It provides a means to define a wide range of artifacts, including a chain of related artifacts enabling SBoMs, signatures and metadata that can be related to an `image.manifest`, `image.index` or another `artifact.manifest`. 29 | By defining a new manifest, registries and clients opt-into new capabilities, without breaking existing registry and client behavior or setting expectations for scenarios to function when the client and/or registry may not yet implement new capabilities. 30 | 31 | ### JSON Schema 32 | 33 | An Artifact manifest, representing a detached signature of the `hello-world@sha256:abc123` image: 34 | - The signature is stored as a `blob` 35 | - The signature points to the `hello-world@sha256:abc123` image through the `subject` property 36 | - Sorting of references may be achieved by setting a `created` annotation. 37 | 38 | ```jsonc 39 | { 40 | "mediaType": "application/vnd.oci.artifact.manifest.v1+json", 41 | "artifactType": "signature/example", 42 | "blobs": [ 43 | { 44 | "mediaType": "application/tar", 45 | "digest": "sha256:def456", 46 | "size": 32654 47 | } 48 | ], 49 | "subject": { 50 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 51 | "digest": "sha256:abc123", 52 | "size": 16724 53 | }, 54 | "annotations": { 55 | "org.opencontainers.artifact.created": "" 56 | } 57 | } 58 | ``` 59 | 60 | #### Manifest Properties 61 | 62 | - **`mediaType`** *string* 63 | 64 | This field contains the `mediaType` of this document, differentiating from [image-manifest][oci-image-manifest-spec] and [image-index][oci-image-index]. The `mediaType` for this manifest type MUST be `application/vnd.oci.artifact.manifest.v1+json`, where the version WILL change to reflect newer versions. 65 | 66 | - **`artifactType`** *string* 67 | 68 | The REQUIRED `artifactType` is a unique value, as registered with [iana.org][registering-iana]. 69 | Examples include `signature/example`, `sbom/example`, `ice-cream/example`. 70 | For details on creating a unique `artifactType`, see [OCI Artifact Authors Guidance][oci-artifact-authors] 71 | 72 | - **`blobs`** *array of objects* 73 | 74 | An OPTIONAL collection of 0 or more blobs. The blobs array is analogous to [oci.image.manifest layers][oci-image-manifest-spec-layers], however unlike [image-manifest][oci-image-manifest-spec], the ordering of blobs is specific to the artifact type. Some artifacts may choose an overlay of files, while other artifact types may store independent collections of files. 75 | - Each item in the array MUST be an [artifact descriptor][descriptor], and MUST NOT refer to another `manifest` providing dependency closure. 76 | - The max number of blobs is not defined, but MAY be limited by [distribution-spec][oci-distribution-spec] implementations. 77 | 78 | - **`subject`** *descriptor* 79 | 80 | An OPTIONAL reference to any existing manifest within the repository. When specified, the artifact is said to be dependent upon the referenced `subject`. 81 | - The item MUST be an [artifact descriptor][descriptor] representing a manifest. Descriptors to blobs are not supported. The registry MUST return a `400` response code when `subject` is not found in the same repository, and not a manifest. 82 | 83 | - **`annotations`** *string-string map* 84 | 85 | This OPTIONAL property contains arbitrary metadata for the artifact manifest. 86 | This OPTIONAL property MUST use the [annotation rules][annotations-rules]. 87 | This map MAY contain some or all of the pre-defined keys in the image-spec, and those listed below 88 | 89 | **Pre-Defined Annotation Keys:** 90 | - `org.opencontainers.artifact.created` date and time on which the artifact was created (string, date-time as defined by [RFC 3339][rfc-3339]) 91 | 92 | #### Descriptor Properties 93 | 94 | Registries and clients work with descriptors as the means to establish discovery and links. To support hashing of different types, enabling filtering, the `artifactType` property is added as an OPTIONAL property to the descriptor: 95 | 96 | ```jsonc 97 | { 98 | "digest": "sha256:aaabbb", 99 | "mediaType": "application/vnd.oci.artifact.manifest.v1+json", 100 | "size": 312, 101 | "artifactType": "signature/example" 102 | } 103 | ``` 104 | 105 | - **`artifactType`** *string* 106 | 107 | This OPTIONAL property defines the type or Artifact, differentiating artifacts that use the `application/vnd.oci.artifact.manifest`. 108 | When the descriptor is used for blobs, this property MUST be empty. 109 | 110 | ### Registry HTTP API 111 | 112 | The `referrers` [extension API](https://github.com/opencontainers/distribution-spec/blob/main/extensions/README.md) is provided to discover these artifacts. 113 | An artifact client would parse the returned [artifact descriptors][descriptor], determining which artifact manifest they will pull and process. 114 | 115 | The `referrers` API returns all artifacts that have a `subject` of the given manifest digest. 116 | Reference artifact requests are scoped to a repository, ensuring access rights for the repository can be used as authorization for the referenced artifacts. 117 | 118 | #### API Path 119 | 120 | The `referrers` API is provided on the [distribution-spec][oci-distribution-spec] paths as described below. 121 | The path of the referrers API provides consistent namespace/repository paths, enabling registry operators to implement consistent auth access, using existing tokens for content. 122 | 123 | **template:** 124 | 125 | ```rest 126 | GET /v2/{repository}/_oci/artifacts/referrers?digest={digest} 127 | ``` 128 | 129 | **expanded example:** 130 | 131 | ```rest 132 | GET /v2/hello-world/_oci/artifacts/referrers?digest=sha256:abc123 133 | ``` 134 | 135 | #### Artifact Referrers API results 136 | 137 | - Implementations MUST implement [paging](#paging-results). 138 | - Implementations MUST implement [sorting](#sorting-results) 139 | - Implementations SHOULD implement [`artifactType` filtering](#filtering-results). 140 | 141 | Some artifacts types including signatures, may return multiple signatures of the same `artifactType`. 142 | For cases where multiple artifacts are returned to the client, it may be necessary to pull each artifact's manifest in order to determine whether or not the full artifact is needed. 143 | Maintainers of the standards utilizing references SHOULD define standard sets of annotations that will allow clients to determine whether or not each artifact needs to be downloaded in full. 144 | 145 | While this will cause additional round trips, manifests are typically small in comparison to the full pull time for a manifest and its blobs or layers. 146 | 147 | This paged result MUST return the following elements: 148 | 149 | - `referrers`: A list of [artifact descriptors][descriptor] that reference the 150 | given manifest. The list MUST include these references even if the given 151 | manifest does not exist in the repository. The list MUST be empty 152 | if there are no artifacts referencing the given manifest. 153 | 154 | **example result of artifacts that reference the `hello-world@sha256:abc123` image:** 155 | 156 | ```jsonc 157 | { 158 | "referrers": [ 159 | { 160 | "digest": "sha256:aaabbb", 161 | "mediaType": "application/vnd.oci.artifact.manifest.v1+json", 162 | "artifactType": "signature/example", 163 | "size": 312 164 | }, 165 | ... 166 | ] 167 | } 168 | ``` 169 | 170 | **example result for a manifest that has no artifacts referencing it:** 171 | 172 | ```json 173 | { 174 | "referrers": [] 175 | } 176 | ``` 177 | 178 | #### Paging Results 179 | 180 | The `referrers` API MUST provide for paging, returning a list of [artifact descriptors](./descriptor.md). 181 | Page size can be specified by adding a `n` parameter to the request URL, indicating that the response should be limited to `n` results. 182 | 183 | - If specified, servers MAY return up to `n` items from the entire result set. 184 | - When `n` is not provided, servers MAY return a default number of items, which may be implementation specific. 185 | 186 | A paginated flow begins as: 187 | 188 | **template:** 189 | 190 | ```rest 191 | GET /v2/{repository}/_oci/artifacts/referrers?digest={digest}&n= 192 | ``` 193 | 194 | **expanded example:** 195 | 196 | ```rest 197 | GET /v2/{repository}/_oci/artifacts/referrers?digest=sha256:abc123&n=10 198 | ``` 199 | 200 | The above specifies that a referrers response should be returned limiting the number of results to `n`. 201 | The response to such a request would look as follows: 202 | 203 | ```jsonc 204 | 200 OK 205 | RefType-Api-Version:reftype/1.0 206 | Link: ; rel="next" 207 | { 208 | "referrers": [ 209 | { 210 | "digest": "", 211 | "mediaType": "", 212 | "artifactType": "", 213 | "size": 214 | }, 215 | ... 216 | ] 217 | } 218 | ``` 219 | 220 | The above includes up to `n` items from the result set. If there are more items, the URL for the next collection is 221 | encoded in a [RFC5988][rfc5988] `Link` header, as a "next" relation. Clients SHOULD treat this as an opaque value and not try to 222 | construct it themselves. 223 | 224 | - The presence of the `Link` header communicates to the client that the server has more items. Clients are expected 225 | to follow the link to fetch the next page of items, irrespective of the number of items received in the current 226 | response. 227 | - If the header is not present, clients can assume that all items have been received. 228 | 229 | > NOTE: In the request template above, the brackets around the url are required. 230 | 231 | For example, if the url is: 232 | 233 | ``` 234 | http://example.com/v2/hello-world/_oci/artifacts/referrers?digest=sha256:abc123&n=5&nextToken=abc 235 | ``` 236 | 237 | The value of the header would be: 238 | 239 | ``` 240 | ; rel="next"`. 241 | ``` 242 | 243 | Please see [RFC5988][rfc5988] for details. 244 | 245 | #### Sorting Results 246 | 247 | The `/referrers` API MUST allow for artifacts to be sorted by the date and time in which they were created, which SHOULD be included in the artifact manifest's list of `annotations`. 248 | The artifact's creation time MUST be the value of the `org.oci.artifact.created` annotation. 249 | The results of the `/referrers` API MUST list artifacts that were created more recently first. 250 | Artifacts that do not have the `org.oci.artifact.created` annotation MUST appear after those with creation times specified in the list of results. 251 | There is no specified ordering for artifacts that do not include the creation time in their list of `annotations`. 252 | 253 | #### Filtering Results 254 | 255 | The `referrers` API MAY provide for filtering of `artifactTypes`. 256 | Artifact clients MUST account for implementations that MAY NOT support filtering. 257 | Artifact clients MUST revert to client side filtering to determine which `artifactTypes` they will process. 258 | 259 | Request referenced artifacts by `artifactType` 260 | 261 | **template:** 262 | 263 | ```rest 264 | GET /v2/{repository}/_oci/artifacts/referrers?digest={digest}&n=10&artifactType={artifactType} 265 | ``` 266 | 267 | **expanded example:** 268 | 269 | ```rest 270 | GET /v2/hello-world/_oci/artifacts/referrers?digest=sha256:abc123&n=10&artifactType=signature%2Fexample 271 | ``` 272 | 273 | #### Push Validation 274 | 275 | Following the [distribution-spec push API](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#push), all blobs *and* the `subject` descriptors SHOULD exist when pushed to a distribution instance. 276 | 277 | #### Lifecycle Management 278 | 279 | Registries MAY treat the lifecycle of a reference type object, such as an SBoM or signature, as being tied to its `subject`. In such registries, when the `subject` is deleted or marked for garbage collection, the defined artifact is subject to deletion as well, unless the artifact is tagged. 280 | 281 | [annotations-rules]: https://github.com/opencontainers/image-spec/blob/main/annotations.md#rules 282 | [descriptor]: https://github.com/oras-project/artifacts-spec/blob/main/descriptor.md 283 | [manifest-differences]: https://github.com/oras-project/artifacts-spec#comparing-the-oras-artifact-manifest-and-oci-image-manifest 284 | [oci-artifact-authors]: https://github.com/opencontainers/artifacts/blob/master/artifact-authors.md 285 | [oci-artifacts]: https://github.com/opencontainers/artifacts 286 | [oci-distribution-spec]: https://github.com/opencontainers/distribution-spec 287 | [oci-image-index]: https://github.com/opencontainers/image-spec/blob/master/image-index.md 288 | [oci-image-manifest-spec-layers]: https://github.com/opencontainers/image-spec/blob/master/manifest.md#image-manifest-property-descriptions 289 | [oci-image-manifest-spec]: https://github.com/opencontainers/image-spec/blob/master/manifest.md 290 | [registering-iana]: https://github.com/opencontainers/artifacts/blob/master/artifact-authors.md#registering-unique-types-with-iana 291 | [rfc-3339]: https://tools.ietf.org/html/rfc3339#section-5.6 292 | [rfc5988]: https://datatracker.ietf.org/doc/html/rfc5988 293 | [oras-azure]: https://aka.ms/acr/oras-artifacts 294 | -------------------------------------------------------------------------------- /docs/proposals/PROPOSAL_B.md: -------------------------------------------------------------------------------- 1 | # Proposal B 2 | 3 | Add "reference" field to existing schemas 4 | 5 | ## Description 6 | 7 | The following proposal describes adding a new field to the existing JSON schemas to enable the creation of relationships between objects stored in an OCI registry. 8 | 9 | Additionally it describes a new read-only endpoint on the registry HTTP API to allow listing of all objects which reference a given object. 10 | 11 | ## Links 12 | 13 | | Description | Link | 14 | | ---------------------------------- | --------------------------------------------------------------- | 15 | | Original proposal (image-spec) | [View](https://github.com/opencontainers/image-spec/issues/827) | 16 | | PR to implement (image-spec) | [View](https://github.com/opencontainers/image-spec/pull/828) | 17 | | Fork of distribution with support | [View](https://github.com/dlorenc/distribution/tree/references) | 18 | | Diagram of usage pattern | [View](https://user-images.githubusercontent.com/1007786/121441279-5c61ca00-c93e-11eb-8b18-40b312542044.png) | 19 | 20 | ## Modifications 21 | 22 | ### JSON Schema 23 | 24 | All existing supported JSON schemas (index/manifest/descriptor) will be allowed to include a new field, `reference`, which is itself a [descriptor](https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/descriptor.go#L22) object: 25 | 26 | ```jsonc 27 | { 28 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 29 | "size": 2345, 30 | "digest": "sha256:b2b2b2...", 31 | "reference": { // new field 32 | "mediaType": "application/vnd.oci.image.manifest.v1+json", // any manifest media type 33 | "size": 1234, 34 | "digest": "sha256:a1a1a1..." 35 | } 36 | } 37 | ``` 38 | 39 | ### Registry HTTP API 40 | 41 | A single, read-only endpoint will be added to the registry HTTP API: 42 | 43 | ``` 44 | GET /v2//manifests//references 45 | ``` 46 | 47 | The response will be a valid [index](https://github.com/opencontainers/image-spec/blob/main/specs-go/v1/index.go#L21), containing a `manifests` array, which is the complete list of descriptor objects referencing a given `` (tag or digest) on a given `` (repo). 48 | 49 | For example: 50 | 51 | ``` 52 | GET /v2/products/cones/manifests/neapolitan/references 53 | ``` 54 | 55 | ```jsonc 56 | { 57 | "schemaVersion": 2, 58 | "mediaType": "application/vnd.oci.image.index.v1+json", 59 | "manifests": [ 60 | { 61 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 62 | "size": 2345, 63 | "digest": "sha256:b2b2b2..." 64 | }, 65 | { 66 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 67 | "size": 2345, 68 | "digest": "sha256:c3c3c3..." 69 | }, 70 | { 71 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 72 | "size": 2345, 73 | "digest": "sha256:d4d4d4..." 74 | } 75 | ], 76 | "annotations": [ 77 | // reserved for future use 78 | ] 79 | } 80 | ``` 81 | -------------------------------------------------------------------------------- /docs/proposals/PROPOSAL_C.md: -------------------------------------------------------------------------------- 1 | # Proposal C 2 | 3 | Create a Node manifest. 4 | 5 | ## Description 6 | 7 | The proposal introduces a "Node" manifest used to organize container images with related artifacts or to group container images together into a higher order artifact. It is based on the typical "Node" data structure. 8 | 9 | A detailed description of this proposal can be found [here](https://docs.google.com/document/d/1KYJaCm5Z-BJ7hVOI_lDh4vEvrmyEAMwUp2nJBELstGw/edit). 10 | 11 | ## Links 12 | 13 | | Description | Link | 14 | | ------------------------------------------- | --------------------------- | 15 | | A talk that introduces the idea | [View](https://youtu.be/U_Q5bG-G_Pw) | 16 | | A Detailed description with pictures | [View](https://docs.google.com/document/d/1KYJaCm5Z-BJ7hVOI_lDh4vEvrmyEAMwUp2nJBELstGw/edit) | 17 | 18 | ## Modifications 19 | 20 | ### JSON Schema 21 | 22 | A new manifest called "node" is introduced. 23 | 24 | The JSON Schema for a "node" manifest looks like this: 25 | ```jsonc 26 | { 27 | "schemaVersion": 3, 28 | "mediaType": "application/vnd.oci.node.v1+json", 29 | "description": "This is a generic node object", 30 | "objects": [ 31 | ... list of blob descriptors ... 32 | ], 33 | "reference": { 34 | ... one blob descriptor 35 | OR pointer to an external reference 36 | OR none ... 37 | } 38 | } 39 | ``` 40 | Restrictions on this manifest schema to prevent loops and reduce load on server side processing: 41 | 42 | - "objects" CANNOT contain descriptors to another Node manifest. 43 | - "reference" has a cardinality of 0..1 i.e. it can either contain 0 or 1 descriptor. 44 | 45 | This is an example of using the node manifest to refer multiple ice cream ingredients to a specific ice cream: 46 | 47 | ```jsonc 48 | { 49 | "schemaVersion": 3, 50 | "mediaType": "application/vnd.oci.node.v1+json", 51 | "description": "Chocolate Sprinkles Ice Cream", 52 | "objects": [ 53 | { 54 | "mediaType": "flavor/vnd.glenandlarry.v0.1.0+batch", 55 | "size": 10, 56 | "digest": "sha256:c0c0abea5" 57 | }, 58 | { 59 | "mediaType": "toppings/vnd.sprinklesgalore.v1.0.1+batch", 60 | "size": 12, 61 | "digest": "sha256:512c17e5" 62 | } 63 | ] 64 | "reference": { 65 | "mediaType": "icecream/vnd.glenandlarry.chocolatesprinkles.v2.0.0+package", 66 | "size": 1024, 67 | "digest": "sha256:1cec12ea77" 68 | } 69 | } 70 | ``` 71 | 72 | This is an example of multiple ice creams grouped together to make one ice cream product: 73 | 74 | ```jsonc 75 | { 76 | "schemaVersion": 3, 77 | "mediaType": "application/vnd.oci.node.v1+json", 78 | "description": "Neopolitan Ice Cream", 79 | "objects": [ 80 | { 81 | "mediaType": "icecream/vnd.glenandlarry.chocolate.v0.0.2+batch", 82 | "size": 10, 83 | "digest": "sha256:c0c01a7e" 84 | }, 85 | { 86 | "mediaType": "icecream/vnd.glenandlarry.vanilla.v2.0.1+batch", 87 | "size": 12, 88 | "digest": "sha256:4a77111a" 89 | }, 90 | { 91 | "mediaType": "icecream/vnd.onlyberry.strawberry.v0.0.1+batch", 92 | "size": 12, 93 | "digest": "sha256:5d12abe12121" 94 | } 95 | ] 96 | "reference": { 97 | "mediaType": "icecream/vnd.glenandlarry.neopolitan.v2022+package", 98 | "size": 3096, 99 | "digest": "sha256:bec12a1c12a1" 100 | } 101 | } 102 | ``` 103 | 104 | _NOTE_:The Node manifest looks very similar to the [index](https://github.com/opencontainers/image-spec/blob/main/image-index.md). Further experiments need to be done in order to assert that the index schema can accept OCI descriptors as well as image manifests. 105 | 106 | This is an example of using a Node manifest to describe a single ingredient: 107 | 108 | ```jsonc 109 | { 110 | "schemaVersion": 3, 111 | "mediaType": "application/vnd.oci.node.v1+json", 112 | "description": "Ice Cream Cone", 113 | "objects": [ 114 | { 115 | "mediaType": "cones/vnd.waffleconeinc.v0.1.0+cone", 116 | "size": 10, 117 | "digest": "sha256:114fff13c0" 118 | } 119 | ] 120 | "reference": {} 121 | } 122 | ``` 123 | 124 | ### Registry HTTP API 125 | 126 | No modifications to the existing API are needed. The proposal includes the following new APIs: 127 | 128 | #### References to a tag or digest 129 | 130 | ``` 131 | GET /v3//referrers/ 132 | ``` 133 | 134 | Response: 135 | 136 | ```jsonc 137 | { 138 | "referrers": 139 | [list of descriptors] 140 | } 141 | ``` 142 | 143 | Example: 144 | 145 | ``` 146 | GET /v3/glenandlarry/referrers/sha256:bec12a1c12a1 147 | ``` 148 | 149 | Gives response: 150 | 151 | ```jsonc 152 | { 153 | "referrers": [ 154 | { 155 | "mediaType": "icecream/vnd.glenandlarry.chocolate.v0.0.2+batch", 156 | "size": 10, 157 | "digest": "sha256:c0c01a7e" 158 | }, 159 | { 160 | "mediaType": "icecream/vnd.glenandlarry.vanilla.v2.0.1+batch", 161 | "size": 12, 162 | "digest": "sha256:4a77111a" 163 | }, 164 | { 165 | "mediaType": "icecream/vnd.onlyberry.strawberry.v0.0.1+batch", 166 | "size": 12, 167 | "digest": "sha256:5d12abe12121" 168 | }, 169 | ] 170 | 171 | ``` 172 | 173 | #### Reference of a tag or digest 174 | 175 | ``` 176 | GET /v3//reference/ 177 | ``` 178 | 179 | Response: 180 | 181 | ```jsonc 182 | { 183 | descriptor OR empty 184 | } 185 | ``` 186 | 187 | Example: 188 | 189 | ``` 190 | GET /v3/glenandlarry/reference/sha256:abcdef123450 191 | ``` 192 | 193 | Gives response: 194 | 195 | ```jsonc 196 | { 197 | "mediaType": "icecream/vnd.glenandlarry.chocolatesprinkles.v2.0.0+package", 198 | "size": 1024, 199 | "digest": "sha256:1cec12ea77" 200 | 201 | } 202 | ``` 203 | 204 | #### Objects contained in a node manifest 205 | 206 | ``` 207 | GET /v3//objects/ 208 | ``` 209 | 210 | Response: 211 | 212 | ```jsonc 213 | { 214 | "objects": [ list of descriptors ] 215 | } 216 | ``` 217 | 218 | Example: 219 | 220 | ``` 221 | GET /v3/glenandlarry/objects/sha256:abcdef123450 222 | ``` 223 | 224 | Gives response: 225 | 226 | ```jsonc 227 | { 228 | "objects": [ 229 | { 230 | "mediaType": "flavor/vnd.glenandlarry.v0.1.0+batch", 231 | "size": 10, 232 | "digest": "sha256:c0c0abea5" 233 | }, 234 | { 235 | "mediaType": "toppings/vnd.sprinklesgalore.v1.0.1+batch", 236 | "size": 12, 237 | "digest": "sha256:512c17e5" 238 | } 239 | ] 240 | } 241 | ``` 242 | 243 | #### The Description of a node manifest 244 | 245 | ``` 246 | GET /v3//description/ 247 | ``` 248 | 249 | Response: 250 | 251 | ```jsonc 252 | { 253 | description 254 | } 255 | ``` 256 | 257 | Example: 258 | 259 | ``` 260 | GET /v3/glenandlarry/description/sha256:abcdef123450 261 | ``` 262 | 263 | Gives response: 264 | 265 | ```jsonc 266 | { 267 | "Chocolate Sprinkles Ice Cream" 268 | } 269 | ``` 270 | 271 | ## Requirements 272 | 273 | #### Filtering 274 | 275 | 1. As a user, I want to query a registry for a stored artifact by its digest or tag. 276 | - Yes: use `GET /v3//objects/` to get a list of objects. 277 | 1. As a user, I want to query the registry for all stored artifacts that reference a given artifact by its digest or tag. 278 | - Yes: use `GET /v3//referrers/`. 279 | 1. As a user, I want to query a registry for all stored artifacts of a particular type that reference a given artifact by its digest or tag. 280 | - Partial: use `GET /v3//description/`, then use the client to filter based on `description` content. This is to allow artifact producers to include specific keywords rather than relying on IANA artifact types. 281 | 1. As a user, I want to query a registry for all stored artifacts based on annotations that reference a given artifact by its digest or tag. 282 | - Yes: In this proposal, the existing image manifest layout does not change and can still be filtered by annotations. 283 | 1. As a user, I want to fetch the most up-to-date artifact, collection of artifacts, or application. 284 | - Partial: If Node manifests are used to combine artifacts of a certain type, and a client follows a pattern where the most up-to-date artifact is appended to the beginning of the list, then the most up-to-date artifact is the one at the beginning of the list. However, there isn't any strong protection against not following these rules. Clients will have to rely on some indicator in the description that points to the "latest" artifact. Another way to implement this is to have a Node reference pointing to an older Node reference. Then the first Node manifest represents the most recent artifact. The drawback of this mechanism is long Node chains which registries will have to garbage collect. 285 | 1. As an artifact producer, I want to reduce the number of tags that reference an artifact. 286 | - Yes: Node manifests pointing to a list of artifacts removes the requirement to tag the artifacts themselves if needed. 287 | 288 | #### Backwards Compatibility 289 | 290 | 1. As a user, I want to be sure that existing container runtimes are not affected by any other type of registry artifact. 291 | - Yes: Existing manifests such as container or index manifests are not affected. 292 | 1. As a user, I want to move container images to and from registries that do not support reference types. 293 | - Partial: Registries that do not support node manifests require the client to create tags for each of the embedded artifacts before pushing them. All the information in description and reference will be lost. Registries that support node manifests have no effect on artifacts that require tagging. 294 | 1. As an artifact producer, I want to tag artifacts that I can pull by said tag, even if they contain references to other artifacts. 295 | - Yes: Node manifests will not affect tags on other artifacts. 296 | 1. As an artifact producer, I want be sure that pushing an artifact to a repository will not affect a copy of the same artifact previously created and referenced by a manifest list existing in another repository on the same registry. 297 | - Yes: Node manifests do not modify existing artifacts nor do they create duplicates of the same artifact, as is the case with existing registries. 298 | 1. As a tool writer, I want to identify whether a registry supports reference types or not. 299 | - Yes: use `GET /v3/`. Catalog listing is not prescribed in this proposal. 300 | 1. As a tool writer, I would like the option to perform a server side blob mount when copying a large artifact between repositories. 301 | - Yes: If a large blob is pushed to the registry and then referenced by a Node manifest, a server side mount should be possible. 302 | 1. As a tool writer, I want to be able to include reference types within the Image Layout filesystem format. 303 | - Yes: The existing image layout will be unaffected. 304 | 305 | #### Content Management 306 | 307 | 1. As a user, I want to store one or more artifacts in a registry with a reference to another related artifact. 308 | - Yes: Node manifests can group one or more artifacts with a reference to another manifest. 309 | 1. As a user, when I delete an artifact, I want the option to delete one or more artifacts referencing it. 310 | - Partial: use `GET /v3//referrers/` to get a list of referring artifacts, use the client to delete specific ones, then push a new Node manifest containing the updated object list. To delete the whole manifest, use `DELETE /v3//manifests/`. 311 | 1. As a user, I want to push an artifact that references another artifact that doesn't exist on the registry yet. 312 | - Yes: This is should be possible if registries don't perform a check that the digest exists. 313 | 1. As a user, I want to move an artifact and one or more artifacts referencing it from one registry to another. 314 | - Partial: The client is responsible for selection of the artifacts and pushing to the target registries, including checks if the registry supports node manifests. 315 | 1. As a registry operator, I want to help users understand how they can manage the lifecycle of their artifacts. 316 | - Yes: Node manifests allow for lifecycle policies to be applied to the list of objects. 317 | 1. As a registry operator, I want to allow users to "lock" the tags to their artifacts. 318 | - Yes: Collections of different types of artifacts may be referenced by a long lived tag. 319 | 1. As an artifact producer, I want to update an existing artifact with a newer artifact. 320 | - Partial: use `GET /v3//manifests/` to fetch a node manifest, then update the objects list with a new artifact. 321 | 1. As an artifact producer, I want to push multiple artifacts concurrently (possibly from separate systems) without encountering race conditions or other errors. 322 | - No: If two manifests with the same digest are pushed to the same registry path, a race condition will occur. However, this problem exists in current registries. 323 | 1. As an artifact author, I want to document other artifacts in one or more registries that my artifact requires and/or provides. 324 | - Partial: Use the description to indicate the reference is a "requires" or "provides" relationship. 325 | 1. As a user, I want assurances that the object I found really did come from the claimed supplier. 326 | - Yes: Node manifests can include attestation, signature, and SBOM artifacts, which can be linked using references. 327 | 1. As an artifact author, I want to add assurances that the artifact originated from me. 328 | - Yes: Node manifests can include supplier information with attestations. 329 | 1. As a registry operator, I want to provide users with retention policies for their artifacts. 330 | - Yes: Server side policies on node manifest size or length of the objects list can be enforced. Timestamp data may be embedded in the description. A registry provider would then have to require that every node manifest have timestamp data in the description which it can read. 331 | 1. As a user, I want to apply timestamp or numerical ranges on my artifacts so I can apply retention policies on them. 332 | - Yes: Clients can enforce ranges on objects and description in accordance with update and retention policies. 333 | -------------------------------------------------------------------------------- /docs/proposals/PROPOSAL_D.md: -------------------------------------------------------------------------------- 1 | # Proposal D 2 | 3 | No Changes 4 | 5 | ## Description 6 | 7 | The following proposal describes how existing OCI components can be used to provide features of reference types without introducing new manifest schemas or distribution APIs. 8 | 9 | ## Links 10 | 11 | | Description | Link | 12 | | -------------- | ---------------------------------------------------- | 13 | | OCI Artifacts | [View](https://github.com/opencontainers/artifacts) | 14 | | Image Spec | [View](https://github.com/opencontainers/image-spec) | 15 | 16 | ## Modifications 17 | 18 | ### JSON Schema 19 | 20 | The image-spec json schema is unchanged. 21 | 22 | The following annotations would be reserved: 23 | 24 | - "org.opencontainers.reference": this annotation is defined on an descriptor to an artifact and is set to the digest of another manifest that this artifact references. 25 | - "org.opencontainers.reference.type": this annotation is defined on descriptors and artifact manifests to indicate the type of artifact. 26 | 27 | The artifact is defined using the existing OCI Artifact definition (image-spec to a custom config media type): 28 | 29 | ```jsonc 30 | { 31 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 32 | "schemaVersion": 2, 33 | "config": { 34 | "mediaType": "", 35 | "size": 1234, 36 | "digest": "sha256:a1a1a1..." 37 | }, 38 | "layers": [ 39 | { 40 | "mediaType": "", 41 | "size": 1234, 42 | "digest": "sha256:b2b2b2...", 43 | "annotations": { 44 | "com.example.metadata": "value" 45 | } 46 | } 47 | ], 48 | "annotations": { 49 | // "org.opencontainers.reference" is not included here since one artifact could reference multiple objects 50 | "org.opencontainers.reference.type": "sig" 51 | // additional annotations may be added for filtering queries (to avoid fetching blobs) 52 | } 53 | } 54 | ``` 55 | 56 | Attaching an artifact to another object in the registry may be done with an OCI Index. 57 | This should only be done by the image originator since changes to this index would modify the digest. 58 | For this example, the above artifact manifest is assumed to be `sha256:a0a0a0...`: 59 | 60 | ```jsonc 61 | { 62 | "mediaType": "application/vnd.oci.image.index.v1+json", 63 | "schemaVersion": 2, 64 | "manifests": [ 65 | { 66 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 67 | "digest": "sha256:010101...", 68 | "size": 1234, 69 | "platform": { 70 | "architecture": "amd64", 71 | "os": "linux" 72 | } 73 | }, 74 | { 75 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 76 | "digest": "sha256:020202...", 77 | "size": 1234, 78 | "platform": { 79 | "architecture": "arm64", 80 | "os": "linux" 81 | } 82 | }, 83 | { 84 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 85 | "digest": "sha256:a0a0a0...", 86 | "size": 1234, 87 | "platform": { 88 | "os": "unknown" // platform that shouldn't be used by image runtimes 89 | }, 90 | "annotations": { 91 | "org.opencontainers.reference": "sha256:010101...", // this is a reference to another descriptor 92 | "org.opencontainers.reference.type": "sig" // type is recommended for client filtering 93 | // additional annotations may be added for filtering queries 94 | } 95 | }, 96 | { 97 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 98 | "digest": "sha256:b0b0b0...", 99 | "size": 1234, 100 | "platform": { 101 | "os": "unknown" 102 | }, 103 | "data": "", // artifact data may be inlined 104 | "annotations": { 105 | "org.opencontainers.reference": "sha256:020202...", 106 | "org.opencontainers.reference.type": "sbom" 107 | } 108 | } 109 | ] 110 | } 111 | ``` 112 | 113 | Later examples assume the digest of the index above is `sha256:000000...`. 114 | 115 | Runtimes select the first matching manifest when they do not understand the artifact annotations. 116 | This is specified in the [OCI image-spec index definition][image-spec-index]: 117 | 118 | > If multiple manifests match a client or runtime's requirements, the first matching entry SHOULD be used. 119 | 120 | ### Registry HTTP API 121 | 122 | The distribution-spec is unmodified. 123 | Querying for a reference involves pulling either existing tags pointing to an index that includes the artifact and image, or pulling new tags that use the digest of the referenced image in the tag value. 124 | 125 | References may be pushed to the following tags. 126 | 127 | 1. `:`: 128 | - Pushing directly to the target `` is useful when artifacts are added by the image originator. 129 | - Altering an existing index after it is released is not recommended since it will change the digest. 130 | 1. `:-..`: 131 | - E.g. `registry.example.org/project-d:sha256-0000000000000000000000000000000000000000000000000000000000000000.0404040404040404.sbom` 132 | - ``: the digest algorithm 133 | - ``: the referenced digest (limit of 64 characters) 134 | - ``: hash of this artifact (limit of 16 characters) 135 | - ``: type of artifact for filtering 136 | - Adding a short hash of the artifact allows multiple artifacts of the same type with little risk of collision or race conditions. 137 | - This may point directly to an artifact instead of the index. 138 | - Image originators should include these tags for every referenced image inside their index, pointing to the same digest as the original index. 139 | E.g. `sha256-010101...a0a0a0.sig` and `sha256-020202...b0b0b0.sbom` would be created and both point to `sha256:000000...`. 140 | - Periodic garbage collection may be performed by clients pushing new references, deleting stale references that have been replaced with newer versions, and tags that no longer point to an accessible manifest. 141 | 142 | ## Requirements 143 | 144 | ### Filtering 145 | 146 | 1. As a user, I want to query a registry for a stored artifact by its digest or tag. 147 | - Yes: Artifacts can be pushed and pulled by tag. 148 | 1. As a user, I want to query the registry for all stored artifacts that reference a given artifact by its digest or tag. 149 | - Yes: The tag list is checked for all digest entries matching the digest of the referenced manifest. 150 | 1. As a user, I want to query a registry for all stored artifacts of a particular type that reference a given artifact by its digest or tag. 151 | - Yes: The tag list is checked for all digest entries matching the digest of the referenced manifest and the desired type for the artifact. 152 | 1. As a user, I want to query a registry for all stored artifacts based on annotations that reference a given artifact by its digest or tag. 153 | - Partial: Each manifest matching the digest of the referenced manifest and type of the desired artifact must be fetched and filtered by the client. 154 | 1. As a user, I want to fetch the most up-to-date artifact, collection of artifacts, or application. 155 | - Partial: Each manifest matching the digest of the referenced manifest and type of the desired artifact must be fetched and filtered by the client. 156 | 1. As an artifact producer, I want to reduce the number of tags that reference an artifact. 157 | - No: This proposal relies on creating tags to track the references. 158 | 159 | ### Backwards Compatibility 160 | 161 | 1. As a user, I want to be sure that existing container runtimes are not affected by any other type of registry artifact. 162 | - Yes: Testing is needed to verify that an index with entries without a platform or with an unknown platform will not break processing of other entries. 163 | 1. As a user, I want to move container images to and from registries that do not support reference types. 164 | - Yes: This proposal does not require changes to the registry. 165 | 1. As an artifact producer, I want to tag artifacts that I can pull by said tag, even if they contain references to other artifacts. 166 | - Yes: Artifacts can be pulled by tag. 167 | 1. As an artifact producer, I want be sure that pushing an artifact to a repository will not affect a copy of the same artifact previously created and referenced by a manifest list existing in another repository on the same registry. 168 | - Yes: Access to artifacts are queried and pulled from their repository using the existing access controls. 169 | 1. As a tool writer, I want to identify whether a registry supports reference types or not. 170 | - Yes: This proposal doesn't require changes to the registry. 171 | 1. As a tool writer, I would like the option to perform a server side blob mount when copying a large artifact between repositories. 172 | - Yes: Artifacts can be copied with existing APIs. 173 | 1. As a tool writer, I want to be able to include reference types within the Image Layout filesystem format. 174 | - Yes: Artifacts may be added to the Image Layout in addition to the referenced manifests. 175 | Descriptors are added to the `index.json` with the `org.opencontainers.image.ref.name` annotation for each digest tag. 176 | 177 | ### Content Management 178 | 179 | 1. As a user, I want to store one or more artifacts in a registry with a reference to another related artifact. 180 | - Yes: References are created using the unique tag syntax. 181 | 1. As a user, when I delete an artifact, I want the option to delete one or more artifacts referencing it. 182 | - Partial: Clients that delete a manifest should also delete tags with a digest referencing that manifest. 183 | A client-side GC could also be created to prune digest tags for digests that are no longer available in that repository. 184 | Client-side GC should not be performed when the user wants to push artifacts before the referenced image, or when creating references to images that are not stored in this repository. 185 | 1. As a user, I want to push an artifact that references another artifact that doesn't exist on the registry yet. 186 | - Yes: Digest tags can be created that point to manifests that do not exist yet. 187 | Client-side GC should not be performed in these environments. 188 | 1. As a user, I want to move an artifact and one or more artifacts referencing it from one registry to another. 189 | - Yes: Artifacts may be copied between registries. 190 | 1. As a registry operator, I want to help users understand how they can manage the lifecycle of their artifacts. 191 | - Partial: Lifecycle management depends on client-side processing to remove tags to artifacts that should be deleted. 192 | 1. As a registry operator, I want to allow users to "lock" the tags to their artifacts. 193 | - Yes: Tag locking can be used with the unique tags to extend existing manifests with new artifact references. 194 | There is no need to mutate existing tags, and the originator can package their index in advance to push once with the images and all reference artifacts together. 195 | 1. As an artifact producer, I want to update an existing artifact with a newer artifact. 196 | - Yes: New artifacts are associated by pushing the artifact and the unique tag referencing the target manifest. 197 | 1. As an artifact producer, I want to push multiple artifacts concurrently (possibly from separate systems) without encountering race conditions or other errors. 198 | - Yes: Each artifact may be pushed separately with a unique artifact manifest and tag that references the target manifest. 199 | 1. As an artifact author, I want to document other artifacts in one or more registries that my artifact requires and/or provides. 200 | - Yes: Unique tags could reference the digest of a manifest in a different registry. 201 | 1. As a user, I want assurances that the object I found really did come from the claimed supplier. 202 | - Yes: Artifacts can be signed, and the signature can be associated with the artifact using the same tag schema used to reference any other manifest. 203 | 1. As an artifact author, I want to add assurances that the artifact originated from me. 204 | - Yes: Artifacts can be signed, and the signature can be associated with the artifact using the same tag schema used to reference any other manifest. 205 | 1. As a registry operator, I want to provide users with retention policies for their artifacts. 206 | - Yes: Artifacts are retained for as long as a tag to that artifact exists. 207 | 1. As a user, I want to apply timestamp or numerical ranges on my artifacts so I can apply retention policies on them. 208 | - Partial: Client-side processing is required to pull and check annotations on each artifact manifest. 209 | 210 | [image-spec-index]: https://github.com/opencontainers/image-spec/blob/main/image-index.md 211 | -------------------------------------------------------------------------------- /docs/proposals/PROPOSAL_E.md: -------------------------------------------------------------------------------- 1 | # Proposal E 2 | 3 | Cherry Pick 4 | 5 | ## Description 6 | 7 | This proposal combines ideas from proposals A, B, and D to create a solution that provides an ability to use it on existing registries, while giving a value add as registries upgrade in the future. 8 | 9 | It consists of the following changes: 10 | 11 | - It adds a new media type for future use cases. 12 | - It defines a "refers" field on both the new media type and existing image manifests. 13 | - It defines an artifactType field to enable users to differentiate between types of artifacts and filter referrer results based on type. 14 | - It defines both an API and a digest tag syntax for querying referrers. 15 | 16 | The result is the following upgrade path: 17 | 18 | - Registries without new API or media type support can use the image manifest plus digest tags to create artifacts that refer to other manifests. 19 | - As registries are upgraded, the new API can be used for more efficient queries and less tag clutter. 20 | The extended Image manifest would still be used for portability to older registries. 21 | - When enough registries support the new media types, a transition can happen to those media types for artifacts. 22 | 23 | ## Links 24 | 25 | | Description | Link | 26 | | ---------------- | --------------------------- | 27 | | Proposal A | [View](./PROPOSAL_A.md) | 28 | | Proposal B | [View](./PROPOSAL_B.md) | 29 | | Proposal D | [View](./PROPOSAL_D.md) | 30 | 31 | ## Modifications 32 | 33 | ### JSON Schema 34 | 35 | #### Annotations 36 | 37 | These annotations would be added for artifacts (both the new artifact-spec and existing image-spec): 38 | 39 | - `org.opencontainers.artifact.description`: human readable description for the artifact 40 | - `org.opencontainers.artifact.created`: creation time for a manifest 41 | 42 | Additional annotations should be considered for filtering various artifact types, e.g. signature public key hash, attestation type, and sbom schema. 43 | 44 | These annotations should be considered from the current config schema: 45 | 46 | - `org.opencontainers.platform.architecture`: CPU architecture for binaries 47 | - `org.opencontainers.platform.os`: operating system for binaries 48 | - `org.opencontainers.platform.os.version`: operating system version for binaries 49 | - `org.opencontainers.platform.variant`: variant of the CPU architecture for binaries 50 | 51 | Existing `org.opencontainers.image.*` annotations should be reviewed to consider more generic names (e.g. replacing `image` with `manifest` or `artifact`). 52 | 53 | #### Artifact Spec 54 | 55 | Create a new artifact media type to support future use cases where a separate config blob, and an ordered list of blobs, may not match an artifact's use case: 56 | 57 | ```jsonc 58 | { 59 | "mediaType": "application/vnd.oci.artifact.manifest.v1+json", 60 | "artifactType": "application/vnd.example.icecream.v1", // used in place of config mediaType 61 | "blobs": [ 62 | // optional list, ordering is not enforced by the spec 63 | // but may be required for specific artifact types 64 | ], 65 | "refers": { // optional 66 | // include refers here 67 | }, 68 | "annotations": { // optional 69 | // annotations for this artifact here 70 | } 71 | } 72 | ``` 73 | 74 | #### Image Spec 75 | 76 | For supporting existing registries, the Image Manifest is extended with a refers field (existing registries should ignore this per OCI's extensibility requirement): 77 | 78 | ```jsonc 79 | { 80 | "schemaVersion": 2, 81 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 82 | "config": { 83 | "mediaType": "application/vnd.example.icecream.v1", // already used as "artifact type" today by many implementations 84 | "size": 1234, 85 | "digest" "sha256:cafecafecafe..." 86 | }, 87 | "layers": [ ... ], 88 | "refers": { // new field 89 | "mediaType": "application/vnd.oci.image.manifest.v1+json", // any manifest media type 90 | "size": 1234, 91 | "digest": "sha256:a1a1a1...", 92 | "annotations": [] 93 | }, 94 | "annotations": { 95 | // annotations for this artifact here 96 | } 97 | } 98 | ``` 99 | 100 | ### Distribution Spec 101 | 102 | #### Referrers API 103 | 104 | Add the following `referrers` API (`` is the digest in the `refers` schema field): 105 | 106 | Current working group testing API: 107 | 108 | ```text 109 | GET /v2//_oci/artifacts/referrers?digest= 110 | ``` 111 | 112 | Proposed API for distribution-spec: 113 | 114 | ```text 115 | GET /v2//referrers/ 116 | ``` 117 | 118 | The response is an Index of descriptors: 119 | 120 | ```jsonc 121 | { 122 | "schemaVersion": 2, 123 | "mediaType": "application/vnd.oci.image.index.v1+json", 124 | "manifests": [ 125 | { 126 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 127 | "artifactType": "application/vnd.example.icecream.v1", // pulled up from manifest 128 | "size": 1234, 129 | "digest": "sha256:a1a1a1...", 130 | "annotations": [ 131 | // annotations pulled up from manifest 132 | "org.opencontainers.artifact.created": "2022-01-01T14:42:55Z", 133 | "org.example.icecream.flavor": "chocolate" 134 | ] 135 | }, 136 | { 137 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 138 | "artifactType": "application/vnd.example.icecream.v1", 139 | "size": 1234, 140 | "digest": "sha256:a2a2a2...", 141 | "annotations": [ 142 | "org.opencontainers.artifact.created": "2022-01-01T15:24:30Z", 143 | "org.example.icecream.flavor": "vanilla" 144 | ] 145 | } 146 | ], 147 | "annotations": { 148 | // reserved for future use 149 | } 150 | } 151 | ``` 152 | 153 | The `annotation` and the `artifactType` fields are pulled up from the referrer manifests. 154 | The `artifactType` is pulled up from the `config` descriptor's `mediaType` field with image-spec manifests. 155 | 156 | If a registry does not implement the `referrers` API, it MUST return a 404. 157 | If a query results in no referrers found, an empty manifest list MUST be returned. 158 | 159 | ##### Ordering and Pagination 160 | 161 | - The registry MUST order the results in a way that allows pagination. 162 | - The `Link` HTTP header is included in the response when additional results are available and is set to the URL for the next page of results. 163 | Given the size of descriptors and maximum size of a manifest, paging is expected to be rare, and it is only supported in the API. 164 | - In the digest tag fallback, there is no paging support and there is no defined order of the manifests in the index. 165 | 166 | ##### Filtering 167 | A limited ability to filter results based on `artifactType` will enable the referrers API to scale as the number of artifact use cases grows. 168 | - The registry SHOULD allow for filtering based on `artifactType`. 169 | - If the registry performs filtering, the response MUST include an annotation (`org.opencontainers.references.filtersApplied`) denoting that an `artifactType` filter was applied. 170 | - Clients MAY request results be filtered by adding the `artifactType` query parameter to requests to the referrers API. 171 | - The value for `artifactType` MUST be the IANA media type of the artifact to be returned. 172 | - Clients SHOULD send only one `artifactType` query parameter, and registries SHOULD only interpret one when filtering, if a client sends multiple values. 173 | 174 | Example request with filtering: 175 | ```text 176 | GET /v2//referrers/?artifactType=application/vnd.example.icecream.v1 177 | ``` 178 | 179 | Response: 180 | ```jsonc 181 | { 182 | "schemaVersion": 2, 183 | "mediaType": "application/vnd.oci.image.index.v1+json", 184 | "manifests": [ 185 | { 186 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 187 | "artifactType": "application/vnd.example.icecream.v1", // pulled up from manifest 188 | "size": 1234, 189 | "digest": "sha256:a1a1a1...", 190 | "annotations": [ 191 | // annotations pulled up from manifest 192 | "org.opencontainers.artifact.created": "2022-01-01T14:42:55Z", 193 | "org.example.icecream.flavor": "chocolate" 194 | ] 195 | }, 196 | { 197 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 198 | "artifactType": "application/vnd.example.icecream.v1", 199 | "size": 1234, 200 | "digest": "sha256:a2a2a2...", 201 | "annotations": [ 202 | "org.opencontainers.artifact.created": "2022-01-01T15:24:30Z", 203 | "org.example.icecream.flavor": "vanilla" 204 | ] 205 | } 206 | ], 207 | "annotations": { 208 | "org.opencontainers.references.filtersApplied": "artifactType" 209 | } 210 | } 211 | ``` 212 | 213 | ##### Registry Upgrade Expectations 214 | 215 | When upgrading existing registries, the following manifests MUST be scanned for a `refers` field: 216 | 217 | 1. Any existing `application/vnd.oci.image.manifest.v1+json` manifest referenced by a [digest tag](#digest-tags) 218 | 2. Any newly uploaded `application/vnd.oci.image.manifest.v1+json` and `application/vnd.oci.artifact.manifest.v1+json` manifests 219 | 220 | Clients SHALL NOT expect manifests uploaded before the [referrers API](#referrers-api) is available on that registry, without using a [digest tag](#digest-tags), will be included in future API responses. 221 | 222 | ##### Garbage Collection 223 | 224 | For registries that implement garbage collection based on tagged manifests, an untagged manifest with a `refers` field pointing to an existing manifest should not be removed. 225 | When a manifest is deleted by a garbage collection policy or by an API request, all untagged artifacts that referred to that manifest may be cleaned by garbage collection. 226 | 227 | #### Digest Tags 228 | 229 | For registries that do not support the `referrers` API, a tag MUST be pushed containing an index of all manifests that refer to the specified manifest, matching the API response above. 230 | The tag uses the following schema: 231 | 232 | ```text 233 | - 234 | ``` 235 | 236 | - E.g. `registry.example.org/project:sha256-0000000000000000000000000000000000000000000000000000000000000000` 237 | - ``: the digest algorithm 238 | - ``: the digest from the `refers` field (limit of 64 characters) 239 | - Periodic garbage collection may be performed by clients pushing new referrers, deleting stale referrers that have been replaced with newer versions, and tags that no longer point to an accessible manifest. 240 | - Clients can verify the registry does not support the `referrers` API by querying the API and checking for a 404. 241 | - Clients should pull the existing tag and extend it with additional entries, minimizing the time between the pull and push to reduce the chance of overwriting changes from other clients. 242 | - Clients should use a conditional push for registries that support ETag conditions to avoid overwriting a tag that has been modified by another client since the previous tag manifest was pulled. 243 | 244 | #### Client Expectations 245 | 246 | ##### Creating Artifacts 247 | 248 | - For portability, clients should generate artifacts using image-spec until all registries where the artifact is pushed to have been upgraded. 249 | - The descriptor of the manifest this artifact refers to should be set in the `refers` field of the manifest. 250 | - Other metadata should be included in the manifest annotations. 251 | - When pushing, the registry should be checked for the referrers API support. 252 | - If the referrers API is not available, the artifact should be pushed with a tag using the digest schema. Tags with the digest schema should not be pushed if the referrers API is available. 253 | 254 | ##### Pulling Artifacts 255 | 256 | To pull artifacts that reference an existing manifest: 257 | 258 | - Clients requests artifacts associated with a manifest first query the referrers API using the digest of the requested manifest. 259 | - If the request fails, clients must fall back to listing tags in the repository and pull manifests for each tag with the matching `` and `` prefix. 260 | - Clients then pull any artifact matching their criteria from the API response or the list generated from the tag query. 261 | 262 | ##### Copying Images 263 | 264 | - Tooling that copies images between registries may recursively query for referrers and copy them. 265 | - Copying an artifact that refers to an image uses the same pull and push steps described above and should support both existing registries and registries with the `referrers` API on both the pull and push. 266 | 267 | ##### Deleting Manifests 268 | 269 | For managing existing registries without the `referrers` API: 270 | 271 | - Client tooling that deletes manifests should also delete digest tags that reference that manifest. 272 | - Client tooling may periodically check for dangling digest tags that refer to missing manifest, and prune those tags. 273 | 274 | ## Requirements 275 | 276 | ### Filtering 277 | 278 | 1. As a user, I want to query a registry for a stored artifact by its digest or tag. 279 | - Yes, artifacts may be pushed and pulled by tag. 280 | 1. As a user, I want to query the registry for all stored artifacts that reference a given artifact by its digest or tag. 281 | - Yes, queries to the API and digest tag work with a digest. 282 | 1. As a user, I want to query a registry for all stored artifacts of a particular type that reference a given artifact by its digest or tag. 283 | - Yes, the digest tag response and the API returns a descriptor list containing annotations that can be filtered by the client. 284 | In addition, the API supports filtering by `artifactType`. 285 | 1. As a user, I want to query a registry for all stored artifacts based on annotations that reference a given artifact by its digest or tag. 286 | - Partial, the returned index contains a descriptor list with annotations that can be filtered by the client. 287 | 1. As a user, I want to fetch the most up-to-date artifact, collection of artifacts, or application. 288 | - Partial, the returned index contains a descriptor list with annotations that can be filtered by the client. 289 | 1. As an artifact producer, I want to reduce the number of tags that reference an artifact. 290 | - Yes, registries that add the API can associate artifacts with manifests without pushing a digest tag. 291 | Existing registries only need a single digest tag per manifest with a referrer. 292 | 293 | ### Backwards Compatibility 294 | 295 | 1. As a user, I want to be sure that existing container runtimes are not affected by any other type of registry artifact. 296 | - Yes, pulling existing images is not impacted by these changes. 297 | 1. As a user, I want to move container images to and from registries that do not support reference types. 298 | - Yes, if Image manifests are used, artifacts can be pushed both to and from OCI compatible registries without changing the digest of the artifact. 299 | A digest tag is used on registries without the new API. 300 | 1. As an artifact producer, I want to tag artifacts that I can pull by said tag, even if they contain references to other artifacts. 301 | - Yes, artifacts may be pushed and pulled by tag. 302 | 1. As an artifact producer, I want be sure that pushing an artifact to a repository will not affect a copy of the same artifact previously created and referenced by a manifest list existing in another repository on the same registry. 303 | - Yes, artifacts with referrers are pushed separately from the manifests they refer to. 304 | 1. As a tool writer, I want to identify whether a registry supports reference types or not. 305 | - Yes, this can be provided by either the OCI extensions discovery interface, or querying the referrers API and checking for an error. 306 | When a query to the referrers API fails, the client should push the digest tag. 307 | 1. As a tool writer, I would like the option to perform a server side blob mount when copying a large artifact between repositories. 308 | - Yes, blob APIs are not impacted by this proposal. 309 | 1. As a tool writer, I want to be able to include reference types within the Image Layout filesystem format. 310 | - Yes, digest tags may be used within the Image Layout. 311 | 312 | ### Content Management 313 | 314 | 1. As a user, I want to store one or more artifacts in a registry with a reference to another related artifact. 315 | - Yes, referrers are created by the `refers` field and, for registries without the `referrers` API, a digest tag. 316 | 1. As a user, when I delete an artifact, I want the option to delete one or more artifacts referencing it. 317 | - Yes, referrers could be queried first and explicitly deleted. 318 | The digest tag can be explicitly deleted. 319 | Garbage collection should delete any untagged artifact if the `refers` field points to a non-existent manifest. 320 | 1. As a user, I want to push an artifact that references another artifact that doesn't exist on the registry yet. 321 | - Partial, digest tags do not require the target manifest to exist on that registry, but would require clients to query for that tag even if the registry supports the `referrers` API. 322 | Alternatively, a registry with the `referrers` API would need to disable validation of the `refers` field and garbage collection of untagged artifacts, which is valid under OCI, but not expected to be a default configuration for most registries. 323 | The `referrers` API would also need to support querying against a digest that doesn't exist. 324 | 1. As a user, I want to move an artifact and one or more artifacts referencing it from one registry to another. 325 | - Yes, after copying the artifact, the referrers should be recursively queried and copied. 326 | 1. As a registry operator, I want to help users understand how they can manage the lifecycle of their artifacts. 327 | - Yes, registry operators can configure their retention policies to support the `refers` field. 328 | Registries without the `referrers` API would continue to use tag based retention policies. 329 | 1. As a registry operator, I want to allow users to "lock" the tags to their artifacts. 330 | - Partial, registries that enforce tag locking can still have artifacts pushed that refer to that locked artifact. 331 | The digest tag can only be pushed once with a single index value. 332 | 1. As an artifact producer, I want to update an existing artifact with a newer artifact. 333 | - Yes, artifacts may be pushed with unique creation annotations, and older artifacts can be explicitly deleted by the client. 334 | 1. As an artifact producer, I want to push multiple artifacts concurrently (possibly from separate systems) without encountering race conditions or other errors. 335 | - No, registries without the `referrers` API will encounter race conditions updating the digest tag. 336 | 1. As an artifact author, I want to document other artifacts in one or more registries that my artifact requires and/or provides. 337 | - Partial, cross repository or registry referrers are not supported with the `referrers` API. 338 | Digest tags may be used to point to digests that do not exist in the current repository. 339 | Additional annotations could be defined to direct the client to search for content in another repository or registry. 340 | The behavior of descriptors that include a `urls` field is unmodified by this proposal which potentially could define a `refers` to an external resource, but this is likely to create more issues than it would solve. 341 | 1. As a user, I want assurances that the object I found really did come from the claimed supplier. 342 | - Yes, artifacts may be signed, and those signatures may be pushed as a referrer to the artifact. 343 | 1. As an artifact author, I want to add assurances that the artifact originated from me. 344 | - Yes, artifacts may be signed, and those signatures may be pushed as a referrer to the artifact. 345 | 1. As a registry operator, I want to provide users with retention policies for their artifacts. 346 | - Yes, registry operators can configure their retention policies to support the `refers` field. 347 | Registries without the `referrers` API would continue to use tag based retention policies. 348 | 1. As a user, I want to apply timestamp or numerical ranges on my artifacts so I can apply retention policies on them. 349 | - Partial, an artifact may have an annotation added with a timestamp, version, or similar value. 350 | These annotations could be queried and a retention policy could be created either by the client or a registry server. 351 | However, this proposal doesn't introduce a specific capability, and leaves retention policies undefined since they are not currently in scope within OCI. 352 | -------------------------------------------------------------------------------- /docs/proposals/PROPOSAL_F.md: -------------------------------------------------------------------------------- 1 | # Proposal F 2 | 3 | OCI Index references it all 4 | 5 | ## Description 6 | 7 | This proposal cherry picks ideas from [Proposal C](https://github.com/opencontainers/wg-reference-types/blob/main/docs/proposals/PROPOSAL_C.md) and [Proposal D](https://github.com/opencontainers/wg-reference-types/blob/main/docs/proposals/PROPOSAL_D.md). 8 | A **nested** [OCI Index](https://github.com/opencontainers/image-spec/blob/main/image-index.md) (an OCI Index referencing another OCI index, allowed by the Image Specification) is used as a top-level object to reference all the artifacts attached to an image. 9 | No change to the reference is expected, but a **well-known annotations** section is added. 10 | 11 | ## Links 12 | 13 | | Description | Link | 14 | | -------------- | ---------------------------------------------------- | 15 | | OCI Artifacts | [View](https://github.com/opencontainers/artifacts) | 16 | | Image Spec | [View](https://github.com/opencontainers/image-spec) | 17 | 18 | ## Modifications 19 | 20 | ### JSON Schema 21 | 22 | The image-spec json schema is left unchanged. 23 | 24 | The OCI Index object references OCI image manifests and OCI artifacts attached to them, using OCI descriptors. 25 | OCI Artifacts descriptors **SHOULD** contain **reference** annotations, to expose the reference type and the image referenced. 26 | OCI Manifest descriptors **SHOULD** contain **well-known** annotations, to expose metadata attached to the image. 27 | 28 | #### Pre-defined annotations 29 | 30 | Reference annotations are added to the [Annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md) section. 31 | * `org.opencontainers.reference.digest`: digest referencing an image. The digest **SHOULD** be referenced as OCI Descriptor in the root OCI index **OR** in the nested OCI index to avoid a weak reference. 32 | * `org.opencontainers.reference.type`: type of the artifact referenced by the descriptor. 33 | * `org.opencontainers.reference.description`: Human-readable description of the reference 34 | 35 | Example of a reference OCI descriptor, pointing to a SBOM referencing an alpine image on a specific platform: 36 | ```json 37 | { 38 | "mediaType": "application/vnd.oci.image.manifest.v1+json", 39 | "digest": "sha256:5b0044a1244...", 40 | "size": 1024, 41 | "annotations": { 42 | "org.opencontainers.reference.type": "sbom", 43 | "org.opencontainers.reference.digest": "sha256:c3c58223e2af75154c4a7852d6924b4cc51a00c821553bbd9b3319481131b2e0", 44 | "org.opencontainers.reference.description": "Software Bill of Materials of alpine:3.17 linux/arm64 image" 45 | } 46 | } 47 | ``` 48 | 49 | #### Well-known annotations 50 | A **well-known** annotations section is added to the [Annotations](https://github.com/opencontainers/image-spec/blob/main/annotations.md) section. 51 | Those annotations **SHOULD** be added to the referenced image descriptor. 52 | An encountered annotation that is unknown to the implementation **MUST** be ignored. 53 | The annotations **MAY** store small data. 54 | The list will evolve depending adoption. 55 | 56 | Example of well-known annotations, adding cosign signatures to an image: 57 | ```json 58 | { 59 | "mediaType": "application/vnd.docker.distribution.manifest.v2+json", 60 | "digest": "sha256:c3c58223e2af75154c4a7852d6924b4cc51a00c821553bbd9b3319481131b2e0", 61 | "size": 528, 62 | "platform": { 63 | "architecture": "arm64", 64 | "os": "linux" 65 | }, 66 | "annotations": { 67 | "org.favorite.icecream": "rocky-road" 68 | } 69 | } 70 | ``` 71 | 72 | ### Scenarii 73 | 74 | The current proposal doesn't change the workflow for [the Refrigerated Truck Driver 🚚](https://github.com/opencontainers/wg-reference-types/blob/main/docs/PERSONAS.md#3-the-refrigerated-truck-driver-), [the Bodega Owner 🏪](https://github.com/opencontainers/wg-reference-types/blob/main/docs/PERSONAS.md#4-the-bodega-owner-) and the [The Ice Cream Lover 😍](https://github.com/opencontainers/wg-reference-types/blob/main/docs/PERSONAS.md#5-the-ice-cream-lover-) personas. 75 | Two scenarii are identified for the [Ice Cream Factory Worker 🏭](https://github.com/opencontainers/wg-reference-types/blob/main/docs/PERSONAS.md#2-the-ice-cream-factory-worker-) and [Health Inspector 🕵️‍♀️](https://github.com/opencontainers/wg-reference-types/blob/main/docs/PERSONAS.md#2-the-ice-cream-factory-worker-) personas. 76 | 77 | 1/ The 🏭 wants to enhance an existing image without changing its digest, already consumed by 😍, so 🕵️ can validate it. 78 | 2/ The 🏭 pushes an image with all the pieces needed by 🕵 without changing 😍 workflow. 79 | 80 | #### Enhance existing image 81 | 82 | An image is already pushed and used. To add artifacts and annotations to it without re-pushin and changing the known digest, a new OCI index is pushed on a new tag, referencing the original image. 83 | The tag **SHOULD** have the following format: 84 | `:-`: 85 | - E.g. `registry.example.org/project-d:sha256-0000000000000000000000000000000000000000000000000000000000000000` 86 | - ``: the digest algorithm 87 | - ``: the referenced digest (limit of 64 characters) 88 | 89 | If the referenced image is an OCI Index, the manifests **SHOULD** be inserted first, for backward compatibility with runtimes. 90 | Runtimes select the first matching manifest when they do not understand the artifact annotations. 91 | This is specified in the [OCI image-spec index definition](image-spec-index): 92 | 93 | > If multiple manifests match a client or runtime's requirements, the first matching entry SHOULD be used. 94 | 95 | Example: 96 | ```jsonc 97 | // Original image, pushed to registry.example.org/project-d:v1 98 | { 99 | "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json", 100 | "schemaVersion": 2, 101 | "manifests": [ 102 | { 103 | "mediaType": "application/vnd.docker.distribution.manifest.v2+json", 104 | "digest": "sha256:c3c58223e2af75154c4a7852d6924b4cc51a00c821553bbd9b3319481131b2e0", 105 | "size": 528, 106 | "platform": { 107 | "architecture": "arm64", 108 | "os": "linux" 109 | } 110 | }, 111 | { 112 | "mediaType": "application/vnd.docker.distribution.manifest.v2+json", 113 | "digest": "sha256:4ff3ca91275773af45cb4b0834e12b7eb47d1c18f770a0b151381cd227f4c253", 114 | "size": 528, 115 | "platform": { 116 | "architecture": "amd64", 117 | "os": "linux" 118 | } 119 | } 120 | ] 121 | } 122 | // Reference OCI Index, pushed to registry.example.org/project-d:sha256-0000000000000000000000000000000000000000000000000000000000000000.0404040404040404 123 | { 124 | "mediaType": "application/vnd.oci.image.index.v1+json", 125 | "schemaVersion": 2, 126 | "manifests": [ 127 | // Original OCI index referenced with signatures on the whole index, can be used by runtimes supporting nested indexes 128 | { 129 | "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json", 130 | "digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000", 131 | "size": 1024, 132 | "annotations": { 133 | "org.favorite.icecream": "mint-chocolate" 134 | } 135 | }, 136 | // Original manifests, for old runtimes, as fallback 137 | { 138 | "mediaType": "application/vnd.docker.distribution.manifest.v2+json", 139 | "digest": "sha256:c3c58223e2af75154c4a7852d6924b4cc51a00c821553bbd9b3319481131b2e0", 140 | "size": 528, 141 | "platform": { 142 | "architecture": "arm64", 143 | "os": "linux" 144 | }, 145 | // signatures added to the linux/arm64 146 | "annotations": { 147 | "org.favorite.icecream": "banana" 148 | } 149 | }, 150 | { 151 | "mediaType": "application/vnd.docker.distribution.manifest.v2+json", 152 | "digest": "sha256:4ff3ca91275773af45cb4b0834e12b7eb47d1c18f770a0b151381cd227f4c253", 153 | "size": 528, 154 | "platform": { 155 | "architecture": "amd64", 156 | "os": "linux" 157 | }, 158 | // signatures added to the linux/amd64 159 | "annotations": { 160 | "dev.cosignproject.cosign/signature.e59879c": "...", 161 | "dev.sigstore.cosign/bundle.6436749": "...", 162 | "dev.sigstore.cosign/certificate.776a3f1": "...", 163 | "dev.sigstore.cosign/chain.8adf60e": "...", 164 | "dev.cosignproject.cosign/signature.de25bf6": "...", 165 | "dev.sigstore.cosign/bundle.37d34ff": "...", 166 | "dev.sigstore.cosign/certificate.e8adf60": "...", 167 | "dev.sigstore.cosign/chain.b1c64a3": "...", 168 | "org.opencontainers.signatures.index":"dev.cosignproject.cosign/signature.e59879c,dev.cosignproject.cosign/signature.de25bf6,dev.sigstore.cosign/bundle.37d34ff,dev.sigstore.cosign/certificate.e8adf60,dev.sigstore.cosign/chain.b1c64a3,dev.sigstore.cosign/bundle.6436749,dev.sigstore.cosign/certificate.776a3f1,dev.sigstore.cosign/chain.8adf60e" 169 | } 170 | }, 171 | // artifacts referencing the image manifests 172 | { 173 | "mediaType": "application/vnd.docker.distribution.manifest.v2+json", 174 | "digest": "sha256:5b0044a1244...", // arm64 SBOM 175 | "size": 1024, 176 | "annotations": { 177 | "org.opencontainers.reference.type": "sbom", 178 | "org.opencontainers.reference.digest": "sha256:c3c58223e2af75154c4a7852d6924b4cc51a00c821553bbd9b3319481131b2e0", 179 | "org.opencontainers.reference.description": "Software Bill of Materials of alpine:3.17 linux/arm64 image" 180 | } 181 | }, 182 | { 183 | "mediaType": "application/vnd.docker.distribution.manifest.v2+json", 184 | "digest": "sha256:5b0044a44d...", // amd64 SBOM 185 | "size": 1024, 186 | "annotations": { 187 | "org.opencontainers.reference.type": "sbom", 188 | "org.opencontainers.reference.digest": "sha256:4ff3ca91275773af45cb4b0834e12b7eb47d1c18f770a0b151381cd227f4c253", 189 | "org.opencontainers.reference.description": "Software Bill of Materials of alpine:3.17 linux/amd64 image" 190 | } 191 | } 192 | ] 193 | } 194 | ``` 195 | 196 | #### Enhanced image 197 | 198 | An enhanced image can be pushed directly, with all metadata annotations and references. 199 | There is no need to nest index in this scenario. 200 | 201 | ```jsonc 202 | { 203 | "mediaType": "application/vnd.oci.image.index.v1+json", 204 | "schemaVersion": 2, 205 | "manifests": [ 206 | // Image manifests with signature annotations 207 | { 208 | "mediaType": "application/vnd.docker.distribution.manifest.v2+json", 209 | "digest": "sha256:c3c58223e2af75154c4a7852d6924b4cc51a00c821553bbd9b3319481131b2e0", 210 | "size": 528, 211 | "platform": { 212 | "architecture": "arm64", 213 | "os": "linux" 214 | }, 215 | // signatures added to the linux/arm64 216 | "annotations": { 217 | "dev.cosignproject.cosign/signature.e59879c": "...", 218 | "dev.sigstore.cosign/bundle.6436749": "...", 219 | "dev.sigstore.cosign/certificate.776a3f1": "...", 220 | "dev.sigstore.cosign/chain.8adf60e": "...", 221 | "dev.cosignproject.cosign/signature.de25bf6": "...", 222 | "dev.sigstore.cosign/bundle.37d34ff": "...", 223 | "dev.sigstore.cosign/certificate.e8adf60": "...", 224 | "dev.sigstore.cosign/chain.b1c64a3": "...", 225 | "org.opencontainers.signatures.index":"dev.cosignproject.cosign/signature.e59879c,dev.cosignproject.cosign/signature.de25bf6,dev.sigstore.cosign/bundle.37d34ff,dev.sigstore.cosign/certificate.e8adf60,dev.sigstore.cosign/chain.b1c64a3,dev.sigstore.cosign/bundle.6436749,dev.sigstore.cosign/certificate.776a3f1,dev.sigstore.cosign/chain.8adf60e" 226 | } 227 | }, 228 | { 229 | "mediaType": "application/vnd.docker.distribution.manifest.v2+json", 230 | "digest": "sha256:4ff3ca91275773af45cb4b0834e12b7eb47d1c18f770a0b151381cd227f4c253", 231 | "size": 528, 232 | "platform": { 233 | "architecture": "amd64", 234 | "os": "linux" 235 | }, 236 | // signatures added to the linux/amd64 237 | "annotations": { 238 | "dev.cosignproject.cosign/signature.e59879c": "...", 239 | "dev.sigstore.cosign/bundle.6436749": "...", 240 | "dev.sigstore.cosign/certificate.776a3f1": "...", 241 | "dev.sigstore.cosign/chain.8adf60e": "...", 242 | "dev.cosignproject.cosign/signature.de25bf6": "...", 243 | "dev.sigstore.cosign/bundle.37d34ff": "...", 244 | "dev.sigstore.cosign/certificate.e8adf60": "...", 245 | "dev.sigstore.cosign/chain.b1c64a3": "...", 246 | "org.opencontainers.signatures.index":"dev.cosignproject.cosign/signature.e59879c,dev.cosignproject.cosign/signature.de25bf6,dev.sigstore.cosign/bundle.37d34ff,dev.sigstore.cosign/certificate.e8adf60,dev.sigstore.cosign/chain.b1c64a3,dev.sigstore.cosign/bundle.6436749,dev.sigstore.cosign/certificate.776a3f1,dev.sigstore.cosign/chain.8adf60e" 247 | } 248 | }, 249 | // artifacts referencing the image manifests 250 | { 251 | "mediaType": "application/vnd.docker.distribution.manifest.v2+json", 252 | "digest": "sha256:5b0044a1244...", // arm64 SBOM 253 | "size": 1024, 254 | "annotations": { 255 | "org.opencontainers.reference.type": "sbom", 256 | "org.opencontainers.reference.digest": "sha256:c3c58223e2af75154c4a7852d6924b4cc51a00c821553bbd9b3319481131b2e0", 257 | "org.opencontainers.reference.description": "Software Bill of Materials of alpine:3.17 linux/arm64 image" 258 | } 259 | }, 260 | { 261 | "mediaType": "application/vnd.docker.distribution.manifest.v2+json", 262 | "digest": "sha256:5b0044a44d...", // amd64 SBOM 263 | "size": 1024, 264 | "annotations": { 265 | "org.opencontainers.reference.type": "sbom", 266 | "org.opencontainers.reference.digest": "sha256:4ff3ca91275773af45cb4b0834e12b7eb47d1c18f770a0b151381cd227f4c253", 267 | "org.opencontainers.reference.description": "Software Bill of Materials of alpine:3.17 linux/amd64 image" 268 | } 269 | } 270 | ] 271 | } 272 | ``` 273 | 274 | ### Registry HTTP API 275 | 276 | > The distribution-spec **SHOULD** solve the race condition occurring when [multiple parties modify an OCI Index in parallel](https://github.com/opencontainers/distribution-spec/pull/251). 277 | Querying for a reference involves pulling either existing tags pointing to an index that includes the artifact and image, or pulling new tags that use the digest of the referenced image in the tag value. 278 | 279 | > Registries are expected to handle nested OCI Index correctly. 280 | 281 | ### Runtime 282 | 283 | > A runtime (clients) **SHOULD** handle a nested OCI index correctly. 284 | 285 | ## Requirements 286 | 287 | ### Filtering 288 | 289 | 1. As a user, I want to query a registry for a stored artifact by its digest or tag. 290 | - Yes: Artifacts can be pushed and pulled by tag. 291 | 1. As a user, I want to query the registry for all stored artifacts that reference a given artifact by its digest or tag. 292 | - Partial: The index stores all the artifacts referencing the given tag or digest. 293 | It is not possible to query artifacts referencing a digest pointing to an image manifest without having a reference to the parent index. 294 | 1. As a user, I want to query a registry for all stored artifacts of a particular type that reference a given artifact by its digest or tag. 295 | - Partial: The index stores all the artifacts referencing the given tag or digest, the client can filter per type. 296 | It is not possible to query artifacts referencing a digest pointing to an image manifest without having a reference to the parent index. 297 | 1. As a user, I want to query a registry for all stored artifacts based on annotations that reference a given artifact by its digest or tag. 298 | - Partial: The index stores all the artifacts referencing the given tag or digest. 299 | The client must pull manifests for each artifact to filter by annotation. 300 | It is not possible to query artifacts referencing a digest pointing to an image manifest without having a reference to the parent index. 301 | 1. As a user, I want to fetch the most up-to-date artifact, collection of artifacts, or application. 302 | - Yes: The tagged index returned by the registry stores all the artifacts referencing the given tag. 303 | 1. As an artifact producer, I want to reduce the number of tags that reference an artifact. 304 | - Partial: The image originator may push a single tag. 305 | Extending that without changing the digest requires an additional tag using a digest schema. 306 | 307 | ### Backwards Compatibility 308 | 309 | 1. As a user, I want to be sure that existing container runtimes are not affected by any other type of registry artifact. 310 | - TBD: Testing is needed to verify that an index with entries without a platform or with an unknown platform will not break processing of other entries. 311 | 1. As a user, I want to move container images to and from registries that do not support reference types. 312 | - Partial: Some registries do not support a nested OCI Index. 313 | 1. As an artifact producer, I want to tag artifacts that I can pull by said tag, even if they contain references to other artifacts. 314 | - Yes: Artifacts can be pulled by tag. 315 | 1. As an artifact producer, I want be sure that pushing an artifact to a repository will not affect a copy of the same artifact previously created and referenced by a manifest list existing in another repository on the same registry. 316 | - Yes: Access to artifacts are queried and pulled from their repository using the existing access controls. 317 | 1. As a tool writer, I want to identify whether a registry supports reference types or not. 318 | - Yes: This proposal doesn't require changes to the registry. 319 | 1. As a tool writer, I would like the option to perform a server side blob mount when copying a large artifact between repositories. 320 | - Yes: Artifacts can be copied with existing APIs. 321 | 1. As a tool writer, I want to be able to include reference types within the Image Layout filesystem format. 322 | - Yes: Artifacts may be added to the Image Layout in addition to the referenced manifests. 323 | 324 | ### Content Management 325 | 326 | 1. As a user, I want to store one or more artifacts in a registry with a reference to another related artifact. 327 | - Yes: References may be created using the unique tag syntax. 328 | 1. As a user, when I delete an artifact, I want the option to delete one or more artifacts referencing it. 329 | - Partial: Clients that delete a manifest should also delete tags with a digest referencing that manifest. 330 | A client-side GC could also be created to prune digest tags for digests that are no longer available in that repository. 331 | Client-side GC should not be performed when the user wants to push artifacts before the referenced image, or when creating references to images that are not stored in this repository. 332 | 1. As a user, I want to push an artifact that references another artifact that doesn't exist on the registry yet. 333 | - Yes: Digest tags can be created that point to manifests that do not exist yet. 334 | Client-side GC should not be performed in these environments. 335 | 1. As a user, I want to move an artifact and one or more artifacts referencing it from one registry to another. 336 | - Yes: Artifacts may be copied between registries. 337 | 1. As a registry operator, I want to help users understand how they can manage the lifecycle of their artifacts. 338 | - Partial: Lifecycle management depends on client-side processing to remove tags to artifacts that should be deleted. 339 | 1. As a registry operator, I want to allow users to "lock" the tags to their artifacts. 340 | - Partial: Once the original tag has been pushed, a single digest schema tag can be pushed with any added artifacts. 341 | It is not possible to push additional digest schema tags to add additional referrers to an index without changing an existing tag. 342 | 1. As an artifact producer, I want to update an existing artifact with a newer artifact. 343 | - Yes: New artifacts are associated by pushing the artifact and the unique tag referencing the target manifest. 344 | 1. As an artifact producer, I want to push multiple artifacts concurrently (possibly from separate systems) without encountering race conditions or other errors. 345 | - No: If two manifests with the same tag are pushed, one push will be overwritten by the other. This is similar to the issue experienced creating multi-platform manifests today. 346 | 1. As an artifact author, I want to document other artifacts in one or more registries that my artifact requires and/or provides. 347 | - Yes: Unique tags could reference the digest of a manifest in a different registry. 348 | 1. As a user, I want assurances that the object I found really did come from the claimed supplier. 349 | - Yes: Artifacts can be signed, and the signature can be associated with the artifact using the same tag schema used to reference any other manifest. 350 | 1. As an artifact author, I want to add assurances that the artifact originated from me. 351 | - Yes: Artifacts can be signed, and the signature can be associated with the artifact using the same tag schema used to reference any other manifest. 352 | 1. As a registry operator, I want to provide users with retention policies for their artifacts. 353 | - Yes: Artifacts are retained for as long as a tag to that artifact exists. 354 | 1. As a user, I want to apply timestamp or numerical ranges on my artifacts so I can apply retention policies on them. 355 | - Partial: Client-side processing is required to pull and check annotations on each artifact manifest. 356 | -------------------------------------------------------------------------------- /minutes/2022-03-08.md: -------------------------------------------------------------------------------- 1 | ## Date 2 | March 8th 2022 3 | 4 | ## Attendees 5 | - Josh Dolitsky 6 | - Brandon Mitchell 7 | - Nisha 8 | - Marina Moore 9 | - Tianon 10 | - Jason Hall 11 | - Samuel Karp 12 | - Lachlan Evenson 13 | - Ramkumar Chinchani (Cisco) 14 | - Michael Brown 15 | - Steve Lasker 16 | - Sajay Antony 17 | - _attendees list_ 18 | 19 | ## Notetaker 20 | - Nisha 🥇 21 | - _backup notetaker_ 🥈 22 | 23 | ## Agenda 24 | - Examine [Proposal D](https://github.com/opencontainers/wg-reference-types/blob/main/docs/proposals/PROPOSAL_D.md) (Josh) 25 | - [Rubric](https://github.com/opencontainers/wg-reference-types/blob/main/docs/RUBRIC.md), based on user stories 26 | 27 | ## Notes 28 | - Brandon shows proposal D 29 | - We can attach other manifests to the index manifest 30 | - Use annotations to add extra descriptions `vnd.oci.artifact.type` to get the artifact types. 31 | - Clients pick the first manifest. Assume the first manifest is an image. 32 | - Smaller artifacts can just be embedded in an annotation as base64 encoded value. 33 | - APIs are unchanged. It doesn't work as good with index unless you reference the index by digest. 34 | - To query the annotation you can use ``:.`` 35 | - Another way to query is to use `:..` 36 | - Questions 37 | - ETAGS - when two people push different digests to the same tag, this should solve it. 38 | - Jason: how do we sign an index? 39 | - Probably going to be some runtimes that don't like this 40 | - Nisha: Do we need to reserve some of these annotations for consistency across clients? 41 | - Josh: "\ as a tag MUST be at most 128 characters in length" - how does this affect the usage of \? 42 | - This is a "short hash" in accordance to spec. 43 | - Josh: does this index then grow indefinitely? 44 | - We have a 4MB limit on the index size. So how can we link? 45 | - If someone wants to push multiple artifacts then push all the artifacts by tags and we can sign the digest. The client has to verify that the hash in the tag matches the hash of the manifest. 46 | - Josh: as far as querying, can this only be done client side? (since no registry changes) 47 | - Yes, we can't do filtering on the server side. 48 | - 49 | - Sajay: what about reserving an annotation for linking to another manifest? 50 | - Maybe we should repurpose the true annotation to be that pointer (Brandon) 51 | - Garbage collection - can be implemented on the client side is not ideal but better than nothing. 52 | - Generally, this is a recommended way of addressing all the user stories with the existing OCI spec. 53 | - Steve: if the originator of an image and an SBOM, if the image gets promoted, the annotation will have information about the SBOM that may still exist in the original registry. 54 | - Gist: one could provide all these use cases but the client will do all the work. 55 | 56 | ### Proposal Evaluation Rubric 57 | 58 | See [user stories](https://github.com/opencontainers/wg-reference-types/blob/main/docs/REQUIREMENTS.md#user-stories) 59 | 60 | ✅ 61 | ❌ 62 | 63 | 64 | Key: 65 | - F: Filtering 66 | - B: Backwards Compatibility 67 | - C: Content Management 68 | 69 | |User Stories|Proposal D| 70 | |--- |--- | 71 | |**F.1**|Yes - query based on tags | 72 | |**F.2**|Yes but not efficient at scale | 73 | |**F.3**|Yes - by type string | 74 | |**F.4**|Yes - inefficient | 75 | |**F.5**|Yes but not efficient and dependent on artifact type | 76 | -------------------------------------------------------------------------------- /minutes/2022-03-15.md: -------------------------------------------------------------------------------- 1 | ## Date 2 | March 15, 2022 3 | 4 | ## Attendees 5 | - Lachlan Evenson 6 | - Josh Dolitsky 7 | - Brandon Mitchell 8 | - Jesse Butler 9 | - Jason Hall 10 | - Nisha Kumar 11 | - Sajay Antony 12 | - Tianon Gravi 13 | - Steve Lasker 14 | - Batuhan Apaydin 15 | 16 | ## Notetaker 17 | - Lachlan Evenson 🥇 18 | - _backup notetaker_ 🥈 19 | 20 | Agenda 21 | - Rubric and updates on proposal D (Brandon) 22 | - 23 | - 24 | - Proposal C (Nisha?) 25 | - 26 | - Reference Looping (Brandon) 27 | - _enter agenda before meeting_ 28 | 29 | Notes 30 | - Should we update the template to include discussion and feedback (Brandon). 31 | - Should we add the rubric and feedback to the template? (Brandon) 32 | - The intent of the template was to not need to much review and am concerned (Josh) 33 | - If people are challenging a yes/no to the rubric - where should we have that discussion (Nisha) 34 | - I would like to the proposal to be the one stop shop (Brandon) 35 | - I thought of the proposal docs to be a snapshot and not to be continuously updated (Josh) 36 | - I don't think bloating the proposal document is the right 37 | - DECISION to punt the feedback decision until later and track the comments on the proposal addition to the rubric PR 38 | - Proposal C discussion 39 | - Introduces a new node manifest 40 | - node manifest looks very similar to index however it adds a description and a manifest blob 41 | - Questions 42 | - When we're looking at objects field, are they manifest or blobs or both and how are they accessed and interact? (Brandon) 43 | - If object can point to a blob or other objects it gets confusing for the client to understand which API to send the request to 44 | - If you're writing a client that's trying to construct the tree, I don't know how to do it. 45 | - If I push a v2 image manifest, do I need to push a v3 at the same time or is it created and I could. Can I point to v2 manifests from v3 APIs? (Jason) 46 | - Confusion about the addition of the objects? Can you help explain when they are used (Josh) 47 | - Can you walk through the series of pushing to understand the process. What is the entrypoint? (Josh) The reference field is still causing confusing 48 | - Is this similar to what we tried to do in oras artifacts? Ref: https://github.com/oras-project/artifacts-spec/pull/75 (Steve) 49 | - How do you recommend we would filter for objects of a specific type? (Sajay) 50 | - Artifact type has been specifically left out because there were use cases where IANA types were not favored 51 | - What are you thoughts on backwards compatibility? (Brandon) 52 | - If I copy this from a registry that supports v3 to a registry that supports v2? (Brandon) 53 | - Brandon discusses garbage collection in looping scenarios - how do we deal with GC where loops can be created with reference? Does it matter that we can create loops? (Brandon) 54 | -------------------------------------------------------------------------------- /minutes/2022-03-22.md: -------------------------------------------------------------------------------- 1 | ## Date 2 | 3 | March 22, 2022 4 | 5 | ## Attendees 6 | 7 | - Josh Dolitsky 8 | - Brandon Mitchell 9 | - Lachlan Evenson 10 | - Marina Moore 11 | - Sajay Antony 12 | - Steve Lasker 13 | - Derek McGowan 14 | - Tianon Gravi 15 | - Jesse Butler 16 | - vbatts 17 | - Ramkumar Chinchani 18 | 19 | ## Notetaker 20 | 21 | - Brandon Mitchell 🥇 22 | - _backup notetaker_ 🥈 23 | 24 | Agenda 25 | 26 | - Review [Proposal B](https://github.com/opencontainers/wg-reference-types/blob/main/docs/proposals/PROPOSAL_B.md) (Josh) 27 | - Updates for [Proposal D](https://github.com/opencontainers/wg-reference-types/pull/23) (Brandon) 28 | - [Image Layout Requirement](https://github.com/opencontainers/wg-reference-types/pull/26) (Brandon) 29 | - Reference Looping follow up (Brandon) 30 | 31 | Notes 32 | 33 | - Proposal B 34 | - Adding a reference field to various media types called `reference` that is itself a `descriptor` 35 | - Reference on manifest makes sense as we're tracking links from artifacts (signatures) to artifacts (images). Putting reference on descriptor means blobs can reference blobs which makes lifecycle near impossible to manage as anything can reference anything. We haven't identified a scenario for blobs to reference blobs. 36 | - Adds a query API that returns an Index with an array of descriptors 37 | - Should we limit reference to only Image media types to avoid looping? (Brandon) 38 | - Is there a need for reference to be a list? (Brandon) 39 | - Steve suggested this as an individual property because it would result in more server side processing to manage lifecycle of artifacts. 40 | - Does the API risk collisions if a user requests `/v2/manifests/manifests/references` (Brandon) 41 | - Option may be for `/v2//references/` 42 | - May want to reformat API response to support pagination (Brandon) 43 | - Media type will need to be manifest type (application/vnd.oci.image), and we'll need a separate artifactType property (Steve) 44 | - Any schema change to an Image manifest may have versioning questions for OCI (Steve) 45 | - Discussing extensibility clause of OCI that allows the change to the Image manifest for existing registries. 46 | - Suggestion that versioning may solve some of these issues. 47 | - There are different versions for both registries and media types (Sajay) 48 | - May be able to depend on the registry/distribution version to determine support for new APIs without querying API. 49 | - Ability to use this with backwards compatible solutions, push/pull digest tags when API doesn't work (Brandon) 50 | - Filtering also isn't included as part of this proposal, may be added into the final WG proposal (Sajay/Josh) 51 | - Index payload can be paginated, as each response is an index. How do you know which item in the response is a signature or sbom. And how do you know which signature is which if you have multiple signatures? (Steve) 52 | - Verbosity question from Proposal A 53 | - Trying to answer questions that we'll have, debating inline vs documentation on each field 54 | - Trying to find balance between too much detail vs leaving questions for later 55 | - Last call for changes to Proposal D and Image Layout Requirement 56 | - Reference Looping: from the OCI, they've asked that we don't create loops 57 | - Next week will discuss Proposal A 58 | -------------------------------------------------------------------------------- /minutes/2022-03-29.md: -------------------------------------------------------------------------------- 1 | ## Date 2 | 3 | March 29, 2022 4 | 5 | ## Attendees 6 | 7 | - Brandon Mitchell 8 | - Jason Hall 9 | - Marina Moore 10 | - Tianon 11 | - Steve Lasker 12 | - Nisha Kumar 13 | - Sajay Antony 14 | - Ramkumar Chinchani 15 | - Josh Dolitsky 16 | 17 | ## Notetaker 18 | 19 | - Brandon Mitchell 🥇 20 | - Nisha Kumar 🥈 21 | 22 | Agenda 23 | 24 | - ~~Review [Proposal A](https://github.com/opencontainers/wg-reference-types/blob/main/docs/proposals/PROPOSAL_A.md) (Sajay) - Can we punt this as Lachie is out (He will ask in Slack)~~ - Punted to April 5 as per 25 | - Proposal C Rubric is up for review: 26 | - Sort out how we will update rubrics per proposal (Brandon) 27 | 28 | Notes 29 | 30 | - Sort out how proposals solves requirements 31 | - Consensus: Add "how" to the bottom of the proposal 32 | - Steve: What about client-server sharing? 33 | - Good to clarify whether the client or the server does the work 34 | - Jason: yes, worth calling out how much work is required to do the filtering, etc. 35 | - Brandon: for scan results or attestations, there would be hundreds of these. 36 | - Jason: don't think any of the proposals dictate how the round tripping happens. 37 | - Ideally, registry servers should perform filtering to minimize rate-limit issues faced by some registries. 38 | - Steve: rate limiting is a soltuion to too many requests being made. Any new APIs should be designed around minmimizing the round trips, to avoid the need to implement throttles. A good design will minimize requests. Then, if developers abuse the APIs, throttles enforce good consumer designs 39 | - Reviewing Rubric for C 40 | - C could have been an OCI Index, but used another media type to avoid breaking existing runtimes. 41 | - List of descriptors may be manifests, could also be blobs, and that risks issues seen with buildx 42 | - Extending manifests could be a chain, but introduces performance problems and GC issues 43 | - Potential issues with chaining indexes, including race conditions, and registry needing to validate depth of chain 44 | - Filtering was done based on the description field, and the description content is currently undefined 45 | -------------------------------------------------------------------------------- /minutes/2022-04-05.md: -------------------------------------------------------------------------------- 1 | ## Date 2 | April 5, 2022 3 | 4 | ## Attendees 5 | - Lachlan Evenson 6 | - Brandon Mitchell 7 | - Josh Dolitsky 8 | - Jason Hall 9 | - Ramkumar Chinchani 10 | - Sajay Antony 11 | - Steve Lasker 12 | - Marina Moore 13 | 14 | ## Notetaker 15 | - Jason 🥇 16 | - Brandon Mitchell 🥈 17 | 18 | Agenda 19 | - Review [Proposal A](https://github.com/opencontainers/wg-reference-types/blob/main/docs/proposals/PROPOSAL_A.md) (Sajay) 20 | - Suggestion for Proposal E (Brandon) 21 | 22 | Notes 23 | - Updates for Proposal A 24 | - not evolving the Image spec, starting fresh with a new Artifact manifest 25 | - `blobs` are not required to be ordered/layered. It's up to each artifactType to specify 26 | - `subject` points to another entry (could be `"reference"`) 27 | - Reference tends to reflect the downward reference - manifest --> blobs. `subject` is an upward reference. `subject` is also a generalized term for a pointer in signatures and claims 28 | - one `subject` or N `subjects`? 29 | - e.g., one signatue signing multiple images 30 | - start with one 31 | - subjects pointing to blobs may allow for looping 32 | - `subject` points to a single manifest assuring lifecycle managment is possible 33 | - `blobs` was going to be ``"descriptors"` ([PR#75](https://github.com/oras-project/artifacts-spec/pull/75), but was reverted) -- disallowed to prevent loops 34 | - `artifactType` in the descriptor --> moving to an annotation? 35 | - may make it easier to index for filtering at query-time 36 | - `_oci/artifacts/referrers` matches [OCI extensions spec](https://github.com/opencontainers/distribution-spec/blob/main/extensions/README.md) 37 | - Can we move the artifactType to annotations? (Brandon) 38 | - Nisha: can blobs be interpreted as ordinal? 39 | - order can't change, or else digest would change 40 | - could be interpreted as ordered if you want to 41 | - Nisha: can artifact manifests point to other artifact manifests? 42 | - Yes. `subject` can point to any manifest type (index, docker, oci, artifact) 43 | - Loops are prevented because `subject` can only point to manifests, not blobs 44 | - `blobs` descriptors are only blobs (never manifests) 45 | - Nisha: this looks like a v3 change, major version bump 46 | - `/v2/` is part of the OCI extensions spec 47 | - `/v2/` already works, supports auth, etc. 48 | - `/v3/` makes registry hosting more difficult 49 | - Nisha: why do descriptors also include `artifactType`? 50 | - to avoid round tripping when querying? (yes) 51 | - lifting all annotations has concerns, could result in larger size, may make sense to use data field to inject full manifest in reply, bloating the response, and possibly sending exploitable `data` in a reference 52 | - Nisha: having params in the API might not be a good idea? 53 | - e.g., `.../sha256:.../referrers` 54 | - OCI extensions spec recommends query params 55 | - Jason: "subject MUST exist" in some scenarios 56 | - We should document the use case. (Sajay) 57 | - open to relaxing that requirement to support offline signing 58 | - artifact without a subject existing could be removed by GC, a tag could help with this 59 | - race condition of pushing image and then pushing signature could be an issue for some users that require only signed images 60 | - Steve: you can push a manifest as a digest, push the signature, than push a tag update assuring the new tag reference is signed 61 | - Josh: can container images refer to things? 62 | - or only "artifacts" like this (Sajay: no) 63 | - be able to tell what images a Helm chart refers to 64 | - Sajay: solving a specific problem; the goal is not to change the image spec 65 | - a Helm chart can refer to N images, you could query for images' `/referrers` to find the Helm chart. 66 | - an artifact can't point across repos, the images would have to be in the same repo, which is not relevant to helm charts 67 | - Josh: artifactType should be registered with IANA, should that be a fully qualified media type? 68 | - Yes, registration prevents multiple implementations fighting over a string 69 | - Other proposals allow this to be more free form string 70 | - Brandon: `created` annotation? 71 | - is this because we don't have `config` field anymore? 72 | - Recommend looking for other needed annotations from the config object and make one PR for all of them. 73 | - Nisha: could we put subsequent scans in additional (ordered) blobs? 74 | - Steve: each scan is a new artifact, assuring each can be promoted individually, or a filtered subset (eg: first and last scan), avoiding any contention for updated manifests 75 | - Proposal E suggestion 76 | - combination of AB+D 77 | - new media type, add referrers field, add /referrers API to query, and support digest tags 78 | - useful to users today, with addl' benefits later when registries support the new media type + APIs 79 | - Users start with an existing OCI artifact today (image with appropriate config media type), include a reference field 80 | - Query using digest tags on existing registries and later upgrade to the API against that field 81 | - Once all registries are upgraded, they can switch over to the new media type to drop the config blob 82 | - Brandon will write it up and review at a future meeting 83 | -------------------------------------------------------------------------------- /minutes/2022-04-12.md: -------------------------------------------------------------------------------- 1 | ## Date 2 | April 12, 2022 3 | 4 | ## Attendees 5 | - Lachlan Evenson 6 | - Brandon Mitchell 7 | - Nisha Kumar 8 | - Josh Dolitsky 9 | - Jason Hall 10 | - Steve Lasker 11 | - Ramkumar Chinchani 12 | - Michael Brown 13 | - Tianon 14 | 15 | ## Notetaker 16 | - Nisha 🥇 17 | - _backup notetaker_ 🥈 18 | 19 | ## Agenda 20 | - [Proposal E](https://github.com/opencontainers/wg-reference-types/pull/38) (Brandon) 21 | - _enter agenda before meeting_ 22 | 23 | ## Notes 24 | 25 | - Proposal E 26 | - Combine pieces of A, B, and D 27 | - Another mediaType 28 | - Add reference type to artifact manifest and image manifest 29 | - Define annotations for filtering artifacts 30 | - Add syntax for tag names 31 | - Idea is that this allows for an upgrade path - it should just work 32 | - New APIs allow for efficient querying, but old registries can still support it. 33 | - Maybe a new name for `org.containers.image*` but not necessary. 34 | - Reference type is any _manifest_ type. 35 | - Lachie: do we need to do anything special for the annotations i.e. are they required? 36 | - This can be optional. Reference and digest tag is required. 37 | - Artifact suppliers must put those in if they want to be seen. But other artifact suppliers may want to put their own annotations. 38 | - TODO: add `os.version` to `platform` annotations too 39 | - Jason: client doesn't need to pull up annotations - up to the registry 40 | - Blobs are optional, and can be unordererd or ordered depending on client 41 | - Registries may show the 404 error if the API doesn't exist 42 | - May be a case where artifact producers will create too many blobs, but it's up to the registries for pagination 43 | - Jason: we should only support querying by digest, not tag, and make clients resolve tag->digest as a separate operation 44 | - Lachie: how does the client understand if references are suppported by the registries 45 | - Brandon: registry should say 404 for the API. 46 | - Steve: manifest registries need to know what type of manifest 47 | - Brandon: it's still an issue for clients to choose whether to use an image manifest with the reference or use an artifact manifest 48 | - Steve: Downgrade path to older registries 49 | - A downgrade would be extra work, but would support round tripping of data between up/down registries (since we won't have artifact manifest) 50 | - Sajay : NOTE: Consider ACLs here querying for a ref-type should not require push permissions 51 | - Sajay: do we want to address the upgrade/downgrade path 52 | - Brandon: you should only move to the new APIs if all dependencies have moved. 53 | - Pagination and sorting is supported 54 | - Generally filtering is done via annotations 55 | - Nisha: is type same as mediaType? 56 | - Brandon: keeping these short names, since the tag can only be so long 57 | - Nisha: 58 | - Steve: client should be able to check the tag names before pushing 59 | - Lachie: digest tags are probably the biggest problem - tag listing in the old registry will be painful enough to implement the new manifest type in their registries, then clients will not have to do this. 60 | - Josh: primary differences for not using the API in proposal A 61 | - Brandon: 62 | - Clients filter on the digest tag, then check the manifest to see if they match 63 | - Biggest difference is making the filtering based on annotation 64 | - Josh: but why change the API names? 65 | - Josh: will this list also include the new mediaTypes? 66 | - Brandon: downloading the index isn't much different from downloading a list of manifests 67 | - Sajay: Regarding tagging scheme - Do we need consider hash collisions when moving content? 68 | - Brandon: The hash is of the artifact not the digest i.e. the manifest. This hash should not change when moving from registry to registry. 69 | - Sajay: Might be hard to get this correct - so may be a good idea to define how that hash is created. 70 | - Nisha: why change API names (joshs question) 71 | - Brandon: it just wasnt _oci extension 72 | - Brandon: field is "reference" vs. "refferer" 73 | - Lachie: next steps? 74 | - Brandon: we should just push it 75 | - Think about submitting proposal E 76 | 77 | Proposal F preview: 78 | - Query parameters 79 | - Steve: Proposal B includes artifact type where we can query 80 | - Josh: is this not implementable? Or out of scope? 81 | - Steve: querying the whole registry for this information would be hugely valuable [Blog post: Common Registry Search ... APIs](https://stevelasker.blog/2019/08/25/oci-artifacts-and-a-view-of-the-future/) 82 | - Brandon: 1. query syntax can be easier 2. Knowing how auth works, doing this across repos is challenging. 83 | - Josh: this is probably that needs a new working group. 84 | - Steve: it's assumed if you are pulling from multiple repos you have access to all the repos. 85 | - Next steps: Josh to submit an issue for this proposal 86 | -------------------------------------------------------------------------------- /minutes/2022-04-19.md: -------------------------------------------------------------------------------- 1 | ## Date 2 | April 19, 2022 3 | 4 | ## Attendees 5 | - Brandon Mitchell 6 | - Michael Brown 7 | - Derek McGowan 8 | 9 | ## Notetaker 10 | - Brandon Mitchell 🥇 11 | 12 | Agenda 13 | - Discussion on Proposal E 14 | 15 | Notes 16 | - Should we be modifying the image-spec 17 | - Should the image-spec changes require a version bump 18 | - Concern that a version bump would break backwards compatibility with existing tooling 19 | - Discussing pros and cons of filtering for registry operators 20 | - Filters only remove entries from the response, so if the registry doesn't filter, it would return more data to the client that could be removed client side 21 | - Concern of indexing all annotations on the registry 22 | - Could a registry pull up only a handful of annotations it cares about into an DB index 23 | - There will be some use cases where users want an unindexed annotation (e.g. looking for a specific signer's signatures), either don't filter on those and return everything to the client, or on the fly filtering 24 | - Concern of how an S3 backed registry could perform the filtering and sorting 25 | - Discussing whether a data field in the descriptor in the response makes more sense than the annotations 26 | - Annotations could be a majority of the manifest, or the manifest with a reference type could have a data field of its own 27 | - Do we have enough to submit PR's to OCI for image-spec with a `reference` field and document the digest descriptors (distribution-spec?) now, giving us time to test an implementation of the references API in distribution/distribution before submitting that PR? 28 | -------------------------------------------------------------------------------- /minutes/2022-04-26.md: -------------------------------------------------------------------------------- 1 | ## Date 2 | April 26, 2022 3 | 4 | ## Attendees 5 | - Sajay Antony 6 | - Brandon Mitchell 7 | - Steve Lasker 8 | - Josh Dolitsky 9 | - Tianon 10 | - _attendees list_ 11 | 12 | ## Notetaker 13 | - Sajay Antony 🥇 14 | - Brandon Mitchell 🥈 15 | 16 | Agenda 17 | - Proposal E Updates (Steve) 18 | - _enter agenda before meeting_ 19 | 20 | Notes 21 | - How can we update the proposal E ? - Steve 22 | - Raise issue or send a PR over the merged PR - Brandon 23 | - Want to ensure that registry operators concerns are made. 24 | - E doesn't seem too far and should we discuss if E the one we should take forward. 25 | - Should this be community or TOB? - Nisha 26 | - Consider taking this the respective maintainers - Michael 27 | - Some changes require consideration across boundaries and getting everyone on the same page is hard - Jason 28 | - Need some quorum of distribution and image-spec folks - Jason 29 | - Might need the TOB to get artifact-spec repo - Brandon 30 | - Distribution spec should already have an idea that this group is working on this. - Josh 31 | - Should we drop pagination/filtering for first round - Josh 32 | - Consider moving with existing registry support and then move forward with distribution changes - Brandon 33 | - Incremental is great, bug suggest we should avoid "Frankensteining" the specs, making sure that the incremental steps accrue to a solution that makes sense in the end - Steve 34 | - Can we propose something useful but might be cumbersome - Nisha 35 | - Some of the work is influencing the wider community but takes time, tern pinning took 5 years - Nisha 36 | - Cut a release and make progress - Jason 37 | - We can pipeline multiple changes without waiting for a release 38 | - Where the properties exist is not the biggest challenge - Steve 39 | - Should we make progress with implementaiton - ZOT - Josh 40 | - What is the customer expectation when the registry gets an unknown fields. 41 | - It is a big effort, but we do have implementations and progress with ORAS Artifacts that we've learned what works and what need more info. Suggest additional reference implementations, building on the [referrers work in distribution](https://github.com/oras-project/distribution/tree/feature_oras_referrers). This is [an output of the WG Ref Type Charter](https://github.com/opencontainers/tob/issues/96) - Steve 42 | - Concerns with E: 43 | - Versioning 44 | - Bumping versions breaks existing clients and registries 45 | - Leaving existing version with new field to process requires registries reprocess existing manifests 46 | - Bridge between states? 47 | - Details of changes to distribution spec if any - Nisha 48 | - Can we shape the specification in such a way that we send clients down the recommended path of using the new manifest and new API and point them to the backwards compat story if the above API is not supported. - Sajay 49 | - Didn't get time to discuss the extension api specification - this was brought up in the last OCI call with Mike Brown and recommeded as a way to incubate the new reference API as well. 50 | - Is extension API needed for new API's defined by OCI? Is this best left as a space for registry operators to extend the registry without accidentally conflicting with new API's that OCI or other registry operators may add? (Brandon) 51 | - Proposal C 52 | - Leaning heavily on extensibility of image-spec 53 | - Handling unknown properties 54 | - Using extensibility API 55 | - Consider reversing priority of image-spec vs artifact-spec in proposal E 56 | -------------------------------------------------------------------------------- /minutes/2022-05-03.md: -------------------------------------------------------------------------------- 1 | ## Date 2 | May 3, 2022 3 | 4 | ## Attendees 5 | - Jason Hall 6 | - Lachlan Evenson 7 | - Nisha 8 | - Tianon 9 | - Patrick Flynn 10 | - Josh Dolitsky 11 | - Michael Brown 12 | - Marina Moore 13 | - Dan Lorenc 14 | - Sajay Antony 15 | - _attendees list_ 16 | 17 | ## Notetaker 18 | - Nisha 🥇 19 | - _backup notetaker_ 🥈 20 | 21 | Agenda 22 | - Discuss [proposal E](https://github.com/opencontainers/wg-reference-types/blob/main/docs/proposals/PROPOSAL_E.md) 23 | - modifying existing image spec. [Sajay] 24 | - new manifest updates [Lachie] 25 | - wrap and next steps to OCI TOB [Lachie] 26 | - Partial demo of proposal E w/ crane and zot [Josh] 27 | - See https://github.com/oci-playground 28 | - _enter agenda before meeting_ 29 | 30 | Notes 31 | - Proposal E 32 | - Continuation of last week's convo: what is the expectation of modifying the existing spec to add a reference field. 33 | - There is some work on the operator's side: image spec does not say that new mediaTypes need to be parsed. 34 | - Jason: reg: what should the registry operators do. A registry should ignore it. Registry operators should signal that anything pushed before x date will not be indexed, you will have to repush it. 35 | - Jason: spec says "ignore field" but doesn't say what it should do if that field becomes meaningful (similar to data field discussion). Suggest adding to the spec to watch out for changes to the fields even though it can be ignored for now. This class of problem is probably common to all the specs. 36 | - Sajay: if reference field may or may not be honored. Should we just go with the new manifest and let registry operators deal with the change - communicate to registry operators and prepare for changes? 37 | - Jason: This is hard to motivate rather than implement. 38 | - Sajay: afraid to touch the image spec because it may break something that will cause backlash. 39 | - Jason: yes, definitely must have something that supports this 40 | - Jason: will take the action to bring up these two concerns to image spec maintainers, if there is group consensus. 41 | - Michael: legitimate concerns about accepting input you don't understand with regards to security. Confuse a manifest list for a manifest. When accepting data with references that mean things, then there should be some response from the registry. 42 | - Jason: the spec is general about what it supports. 43 | - Jason will take the action to clarify verbiage about specific and general concerns. 44 | - Proposal E vs Proposal A 45 | - Why not take the manifest from [Proposal A](https://github.com/opencontainers/wg-reference-types/blob/main/docs/proposals/PROPOSAL_A.md)? 46 | - ArtifactType, Subject, Referrers 47 | - Jason: personally doesn't have a preference to names. Would it make sense to add to E why the names changed? May also be cognizant of the image spec maintainers' feelings about the words. 48 | - (Late follow up from Brandon): Names weren't changed from Proposal A, they were just taken from Proposal B, this was a cherry pick from multiple proposals 49 | - Lachie: looks like proposal E is not as strong as the other proposals. Eg: Proposal A has examples and well thought out explanations about filtering. Maybe the action item is adding the example from proposal A. 50 | - Sajay: Agree, but Mike Brown did say to use the extensions API. No strong opinion about names. Gets complicated with filtering. Probably need some clarity with that. The filtering with extensions would help to land the filtering without touching the manifest endpoints. 51 | - Michael: agree dealing with the filtering part in increments. 52 | - Josh: Proposal E has strengths but the filtering is getting in the way. Maybe focus on the upgrade path and break the proposals 53 | - Nisha: seems to be consensus that Proposal E is good, but should be broken down into sub-proposals and staged (not Lachie's interpretation) 54 | - Lachie's interpretation: strip back Prop E to minimal viable proposal, for TOB to understand, strip out filtering, better examples, (Josh: describe upgrade path, Sajay: use extensions a la Prop A?) 55 | - E-prime: how do we coalesce toward the concrete proposal 56 | - Josh: unless we're creating a new spec, we can bypass TOB 57 | - we might be creating a new spec 58 | - Lachie: we could drop distribution-spec changes if we do an extension :thinking_face: 59 | - Nisha: Prop E is good, we have to figure out what to propose first; start with E's new artifact, then filtering and image-spec backcompat changes 60 | - 1. Drop filtering 2. Registry endpoints out to extensions 3. Submit artifact manifest and image reference field upgrade path. Need explanation for all the proposals. 61 | - Michael: adding an endpoint is important though 62 | - Demo 63 | - Josh to follow up on questions that came up while implementing the demo. Eg the links annotiation which is a comma separated list. 64 | -------------------------------------------------------------------------------- /minutes/2022-05-10.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | May 10, 2022 4 | 5 | **Recording**: 6 | 7 | ## Attendees 8 | 9 | - Josh Dolitsky 10 | - Jason Hall 11 | - Sajay Antony 12 | - Lachie Evenson 13 | - Michael Brown 14 | - Jesse Butler 15 | - Brandon Mitchell (joined late) 16 | - Ramkumar Chinchani 17 | - _attendees list_ 18 | 19 | ## Notetaker 20 | 21 | - Jason Hall 🥇 22 | - _backup notetaker_ 🥈 23 | 24 | Agenda 25 | 26 | - 27 | - prototyping in OCI extension, upgrade it to a "real" path later 28 | - OCI extension discovery is an OCI extension 29 | - let's only make the API move once 30 | - (Nisha) How do we demonstrate the popularity of an extension? 31 | - PoC as an extension to distribution at 32 | - Get input on the following - @sajay 33 | - Discuss if we need artifactType in the new manifest and how does this impact the image spec changes since the updates decided to drop filtering all together? 34 | - Basically is there a middle ground for minimum viable experience? 35 | - Is this acknowledging that other filters will never happen, or will there be two tiers/paths for filters? (Brandon) 36 | - Get concensus on if we should return referrers or leave it upto cloud providers to decide the impact of introducing `refer` field into the image-spec? Inputs from Jon might be really valuable here. Or maybe bring it upto the OCI call. 37 | - Is there a need for implementers to vouch for spec changes? (Nisha) 38 | - _enter agenda before meeting_ 39 | - Follow up: should ArtifactType be a field or an annotation? 40 | 41 | Notes 42 | -------------------------------------------------------------------------------- /minutes/2022-05-17.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | May 17, 2022 4 | 5 | **Recording**: 6 | 7 | ## Attendees 8 | 9 | - Brandon Mitchell 10 | - _attendees list_ 11 | 12 | ## Notetaker 13 | 14 | - No one, it was chaos 🥇 15 | 16 | Agenda 17 | 18 | - Live code proposal E (Josh) 19 | - If time permits - Demo distribution with extension support for the new manifest. [sajay] 20 | 21 | Notes 22 | 23 | - What we accomplished today: 24 | - regclient: on a fresh run of registry:2, we successfully pushed manifest with fallback 25 | - regclient: list on fresh run of registry:2 (via fallback tag list) 26 | - regclient: pushed manifest with new referrer field to oci-playground/distribution 27 | - oci-playground/distribution: supports referrers API (via _oci extension) 28 | - oci-playground/distribution: not yet supporting of image spec changes 29 | - see 30 | - see 31 | - regclient: missing new artifact type 32 | - pull in new artifact type 33 | - see 34 | -------------------------------------------------------------------------------- /minutes/2022-05-24.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | May 24, 2022 4 | 5 | **Recording**: 6 | 7 | ## Attendees 8 | 9 | - Brandon Mitchell 10 | - Nisha Kumar 11 | - Tonis Tiigi 12 | - Chris Crone 13 | - Jason 14 | - Sajay Antony 15 | - Josh Dolitsky 16 | - Tianon Gravi 17 | - Matt Bendix 18 | - Patrick Flynn 19 | - Lachlan Evenson 20 | - Ramkumar Chinchani 21 | - Michael Brown 22 | - _attendees list_ 23 | 24 | ## Notetaker 25 | 26 | - Nisha 🥇 27 | - Chris 🥈 28 | 29 | Agenda 30 | 31 | - Demo regclient + distribution fork implementing proposal E (Brandon) 32 | - Go through feedback on Proposal D, E and anything else 33 | - Are OCI Layout changes needed? [Zot comment](https://github.com/project-zot/zot/compare/main...oci-playground:main#diff-dff2f68dc3ec0ac35cebe09e239b9dea414f84553a6efc4f24d787c46ecc35e6R678) (Brandon) 34 | - Should query response be an OCI Index or new media type? [Justin's comment](https://github.com/opencontainers/wg-reference-types/pull/38#discussion_r864660341) (Brandon) 35 | - [Field/API naming bike shedding (reference, refers, referrers)?](https://github.com/opencontainers/wg-reference-types/issues/41) (Brandon) 36 | - [Proposal E upgrade scenarios](https://github.com/opencontainers/wg-reference-types/pull/49) (Josh) 37 | - If we have time, can try to validate some 38 | - See 39 | - _enter agenda before meeting_ 40 | 41 | Notes 42 | 43 | - Demo 44 | - & 45 | - Nisha: How many changes did you have to make on top of distribution/distribution to make this happen? 46 | - Registry side: 47 | - regctl side wasn't too bad. Most of the work was on adding media type 48 | - The hard part is that content on the registry side will have to be reindexed 49 | - Feedback on proposals 50 | - 51 | - Anything requiring changes to structs and API will have impact on existing implementations 52 | - Changing how registries are restructured is problematic for large registries 53 | - Reg: using index - should digest change when digests are added? 54 | - Brandon: then it's hard to figure out what you are signing 55 | - Chris: you could sign a single digest (rather a digest + size) or any struct (list of digests) 56 | - Tonis: the docker use case is more aligned to proposal D i.e. no changes (?). Logically, an image should only have one signature. 57 | - Jason: conformance tests for nested indexes. How would you discover an image in a deeply nested index? 58 | - Brandon: if you are an image originator this makes sense, but downstream, workflows that depend on the digest being static will be affected. 59 | - Tonis: but there could be different components - if container bits change, workflows can detect it. 60 | - Jason: the same system can query for attestations and signatures. 61 | - Tonis: you can't understand what attestations were part of the container. 62 | - Nisha: this is addressed in one of the use cases, we want to know what was the latest thing appended to an image. We don't want a list of attestations, just the latest one. Proposal C was supposed to handle this. We left this because it had problems with GC. 63 | - Tonis: You don't always want all the signatures, sometimes you want a subset. 64 | - Nisha: specific use case is chain of custody. In this case, you want to maintain the chain of signatures for the artifact so that you can track where it came from. 65 | - Jason: this is a valid use case. Can be tracked by adding metadata to document handovers between parties. 66 | - Tonis: in the index model (Proposal D-ish), when you hand it over, you append the object with a new signature. The digest changes with the signature addition. 67 | - Brandon: Folks still need write access to your repositories. Suppose you want to link digests to a different repos. 68 | - Brandon suggests Tonis submit their proposals and how it addresses use cases 69 | - TBD things are OK in the proposal 70 | - Jason: what if there is a vuln against digest abc, we want to get that information linked. If we link in the index then we will have to parse the index. If the digest doesn't change it's easy to match. 71 | - Chris: you have to crawl the registry anyway. 72 | - Chris- Proposal C: it does look like an index but versioning breaks backwards compat. 73 | - Chris: propose start with Proposal D (no changes) but work on v3. Jason: fallback mechanism becomes "the mechanism". This is the nice things in Proposal E. Brandon: registries would want to upgrade. 74 | - Chris: registries will probably rate limit and give you a crappy experience rather than move to the new API. 75 | - Action Item: Chris and Tonis to submit a proposal 76 | - Are OCI layout changes needed? 77 | - Referres API? 78 | - Query or an OCI index? 79 | - The name of the "reference" 🌹 80 | - Upgrading 81 | - PR 82 | - Docker community concerns 83 | - Chris: what are the data structures that get stored in registries. Should they be attached to the root object or detached. 84 | - Tonis: Not sure it fits the requirements for backwards compatible use cases. Performance is an issue. Needs to be snappy with UX. 85 | - Jason: This is feedback that we should consider performance. 86 | - Jason: docker pull shouldn't have to verify all the signatures by default. Various UX ways to handle this. 87 | - Brandon: Have done some thinking about this on the notary side about how to define policies for this. 88 | - Jason: We should support the distroless use case well even though it is a bit exceptional. 89 | - Brandon: backwards compatibility is a big concern, particularly for runtimes that don't know anything about references and need to run images. 90 | -------------------------------------------------------------------------------- /minutes/2022-05-31.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | May 31, 2022 4 | 5 | **Recording**: 6 | 7 | ## Attendees 8 | 9 | - Brandon Mitchell 10 | - Josh Dolitsky 11 | - Silvin Lubecki 12 | - Chris Crone 13 | - Tianon 14 | - Tonis Tiigi 15 | - Sajay Antony 16 | - Patrick Flynn 17 | - Nisha Kumar 18 | - Jason Hall 19 | - _attendees list_ 20 | 21 | ## Notetaker 22 | 23 | - Brandon 🥇 24 | - Nisha 🥈 25 | 26 | Agenda 27 | 28 | - Chris: Proposal F 29 | 30 | Notes 31 | 32 | - Proposal F: 33 | - Chris: Docker will write up a Proposal F based on the discussion [here](https://github.com/opencontainers/wg-reference-types/issues/50) 34 | - How to make mutating an index atomic 35 | - 36 | - ETag concern from before was S3 backend was eventually consistent 37 | - This is no longer a concern with the AWS implementation of S3 38 | - 39 | - Josh: size of attached artifacts 40 | - Manifest are size limited 41 | - Artifact can be pushed as a blob 42 | - Manifest should be small, think that signing falls in this bucket 43 | - Manifest can also grow when there are lots of small things (many attestations attached to an image) 44 | - We can't necessarily control how people will add new ref types to an image, may not just be a signature and sbom 45 | - Some new types may group lots of content into a single manifest instead of lots of ref types to an image 46 | - Sajay: what does this group do if we propose no change to image/distribution specs 47 | - OCI artifact definition is already a "no change" description 48 | - We can still standardize how this is done without proposing new types or API endpoints 49 | - Sajay: we will have limits on the number of objects that can be attached based on the size of manifests 50 | - Nisha: concerns with F including missing filtering support, creating tags, difficult to track history 51 | - Jason: don't treat signatures as special, but all small things should have a different option to inline 52 | - Chris: don't specify each use case, let tool builders define how they use the OCI specs 53 | - Brandon: interoperability concerns, want to be sure tooling can be designed to copy any ref type between registries 54 | - Nisha: creating micro-SBOMs and linking them together, how would this be done with F 55 | - The linked structure would create a tree 56 | - Tree should be represented by an OCI index (with the option of nesting indexes) 57 | - Concern with frequently changing content where existing data remains and gets extended with new information 58 | - Brandon: GitBom may handle tree design in a way that fits into annotation syntax 59 | - Josh: how to pick between E or F? 60 | - Concerned that registries won't update quick, resulting in bad UX for proposal E 61 | - Josh: do we need to see some new proposal G based on Justin's bigger goals 62 | - Need to find a solution that handles our immediate goals 63 | - Can also look towards bigger goals later 64 | - Brandon: A concern from Justin was E resulted in a data model that didn't fit his longer term vision 65 | - Nisha: we don't have a place to iterate on bigger visions for OCI 66 | - Working group shouldn't expand too far out of WG goals, leave that to main OCI group and TOB 67 | - Jason: Various ways to innovate 68 | 1. Can do something in a vacuum and later propose to OCI 69 | 2. Work within constraints of OCI (like cosign) 70 | 3. Dictating from above often fails (or won't get approved by OCI) 71 | -------------------------------------------------------------------------------- /minutes/2022-06-07.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | June 7, 2022 4 | 5 | **Recording**: 6 | 7 | ## Attendees 8 | 9 | - Jason Hall 10 | - Nisha Kumar 11 | - Sajay Antony 12 | - Tonis Tiigi 13 | - Michael Brown 14 | - Silvin Lubecki 15 | - Chris Crone 16 | - Tianon 17 | - Lachlan Evenson 18 | - Josh Dolitsky 19 | - Brandon Mitchell 20 | 21 | ## Notetaker 22 | 23 | - Nisha 🥇 24 | - Brandon 🥈 25 | 26 | Agenda 27 | 28 | - Enumerate concerns and thoughts on [Proposal F](https://github.com/opencontainers/wg-reference-types/blob/main/docs/proposals/PROPOSAL_F.md) (Josh) 29 | - Document them in issue [#53](https://github.com/opencontainers/wg-reference-types/issues/53) 30 | 31 | Notes 32 | 33 | - Silvin: Proposal F 34 | - Add annotations to describe references 35 | - Add "well known" annotations for "small" data 36 | - Append data to original image by uploading a new OCI index manifest adding a "digest tag". 37 | - Jason: we want to get rid of the digest tag. But is this the best we can come up with? 38 | - Silvin: this would be only one that would include everyone. 39 | - Tonis: latest tag will point to the latest image and latest index 40 | - Jason: when downstream consumer ingested alpine:latest then they will add a signature but this changes the digest of the original image. How can I find that this image is the same as the original image? 41 | - Tonis: in this case you would use the digest tag 42 | - Brandon: that would mean we would have to parse each of the index manifest. 43 | - Brandon: what if the arm64 image exists in other indices? 44 | - Chris: is that in scope? 45 | - Chris: you would push to a different repo with all the attached artifacts 46 | - Brandon: now we have to query a special index along with the top level index 47 | - Tonis: you can only know the list of signatures which means the image has been rebuilt the image that many times 48 | - Nested indices 49 | - Tonis: Pull manifest list, check each manifest if it has the right platform. Descriptors are then sorted. Things that don't have a platform are lower priority. If a index is found it will pull the manifest down and go through the same process. 50 | - Jason: this algorithm needs to be well defined. Platformless manifests need to be handled. 51 | - Michael: issues with tag race conditions and customers not wanting tags to be overwritten, the tag based approach may not work with existing registries. Tag needs to be immutable and built filters on tags. Scaling this for big registries require additional changes. How do we want to address this? 52 | - Chris: should have hard limits on index size 53 | - Josh: thoughts around the reference type field? There is a mediaType which we can rely on. 54 | - Silvin: not sure if defining mediaTypes was in scope. Maybe use config? 55 | - Josh: is the primary goal of adding "small data" to support clients? 56 | - Silvin: it's to reduce roundtripping of manifests - just pull one manifest and get the signature 57 | - Tonis: unknown platform - using a keyword "unknown" 58 | - Brandon: feels like another hack 59 | - Sajay: ordering seems to be important 60 | - Brandon: defined in OCI today, but not tested enough 61 | - Nisha: Do nested indexes need to be covered in other proposals too? 62 | - Jason: we should do this in general from OCI outside of the working group 63 | - Josh: Scalability if vulnerability scan is added each day to an image 64 | - Jason: May result in lots of entries in one list, or a deeply nested index if tags cannot be mutated. 65 | - Brandon: some runtimes limit length of individual annotations to 4KB, not limited by OCI yet, but maybe should be 66 | - Nisha: is this creating more tags than other proposals? 67 | - Want to avoid running tag list API 68 | - This solution doesn't have unique hash, so tags can be pulled directly 69 | - Brandon: Race conditions when updating existing image 70 | - Jason: push OCI to support ETags 71 | - How should clients respond if ETags are not supported by the registry? 72 | - How can clients detect ETag support on push? 73 | - Sajay: could all SBOMs be added to a single index? 74 | -------------------------------------------------------------------------------- /minutes/2022-06-14.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | June 14, 2022 4 | 5 | ## Attendees 6 | 7 | - Josh Dolitsky 8 | - Tianon 9 | - Brandon Mitchell 10 | 11 | ## Notetaker 12 | 13 | - _notetaker_ 🥇 14 | - _backup notetaker_ 🥈 15 | 16 | Agenda 17 | 18 | - _enter agenda before meeting_ 19 | 20 | Notes 21 | 22 | - ETag discussion 23 | - 24 | -------------------------------------------------------------------------------- /minutes/2022-06-26.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | June 28, 2022 4 | 5 | ## Attendees 6 | 7 | - Lachlan Evenson 8 | - Tianon 9 | - Nisha Kumar 10 | - Alexander Mazuruk 11 | - Sajay Antony 12 | - Michael Brown 13 | - Jesse Butler 14 | - Brandon Mitchell 15 | 16 | ## Notetaker 17 | 18 | - Nisha 🥇 19 | - Lachlan Evenson 🥈 20 | 21 | Agenda 22 | 23 | - Next steps for deciding on a proposal (Brandon) 24 | 25 | Notes 26 | 27 | - Looks like we've settled on prop E and F. (Brandon) 28 | - Are we looking at a cherry pick of a cherry pick (Nisha) 29 | - I think they represent two different paths they can go down (Josh) 30 | - Should we call a vote with how to proceed? 31 | - From Jon: We need to query the new fields and references via an API 32 | - Jesse: Must drive quorum here - "consensus doesn't mean unanimous" use Roberts rules(?) 33 | - Brandon: will file an issue to collect poll results and we will leave it up for a week. 34 | - [Issue 56](https://github.com/opencontainers/wg-reference-types/issues/56) has been opened 35 | - Jason: propose that once we vote we present a united front. 36 | - Brandon: maybe we should go over E to flush out any issues 37 | - Any time you have to run the tag list instead of give me the tag - that's a downside to prop e - Brandon 38 | - Can we be clear about the upgrade path is for prop e? - Nisha 39 | - I would divide the prop into all the new additions then the fallback method (Nisha) 40 | - Do we convert Proposal E into a spec or how are we going to communicate this? 41 | - Josh: would like the entirety of Proposal E be agreed upon 42 | - Michael: concerned about load bearing annotations. We should make them into fields. 43 | - Brandon: what about signing keys? 44 | - General concern: do we want to support server side filtering or do we want to embed annotations to do client side filtering? 45 | - Quorum vote administrivia 46 | - Context on upgrade path from Brandon - Nisha will submit PR for formatting 47 | - Added questions to for follow up 48 | -------------------------------------------------------------------------------- /minutes/2022-07-05.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | July 5, 2022 4 | 5 | ## Attendees 6 | 7 | - Brandon Mitchell 8 | - Tianon 9 | - _attendees list_ 10 | 11 | ## Notetaker 12 | 13 | - _notetaker_ 🥇 14 | - _backup notetaker_ 🥈 15 | 16 | Agenda 17 | 18 | - [Picking a direction](https://github.com/opencontainers/wg-reference-types/issues/56) 19 | - See 20 | - [Updates to E](https://github.com/opencontainers/wg-reference-types/issues/42) 21 | 22 | Notes 23 | -------------------------------------------------------------------------------- /minutes/2022-07-12.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | July 12, 2022 4 | 5 | ## Attendees 6 | 7 | - Brandon Mitchel 8 | - Ankit Agarwal 9 | - Marina Moore 10 | - Jason Hall 11 | - Michael Brown (AWS) 12 | - Tianon Gravi 13 | - Josh Dolitsky 14 | - Brandon Mitchell 15 | - Jesse Butler 16 | - Ramkumar Chinchani (Cisco) 17 | - _attendees list_ 18 | 19 | ## Notetaker 20 | 21 | - _notetaker_ 🥇 22 | - _backup notetaker_ 🥈 23 | 24 | Agenda 25 | 26 | - [Clarifications to E](https://github.com/opencontainers/wg-reference-types/pull/60) (Brandon) 27 | - [Consider making a dedicated artifactType field](https://github.com/opencontainers/wg-reference-types/pull/59) (Brandon) 28 | - [Consider a single digest tag](https://github.com/opencontainers/wg-reference-types/pull/61) (Brandon) 29 | - [How do we propose these changes land across OCI repos? 30 | ](https://github.com/opencontainers/wg-reference-types/issues/62#issuecomment-1178911565) (Josh) 31 | - we can start to stage some of this in oci-playground 32 | - 33 | - 34 | - _enter agenda before meeting_ 35 | 36 | Notes 37 | -------------------------------------------------------------------------------- /minutes/2022-07-19.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | July 19, 2022 4 | 5 | ## Attendees 6 | 7 | - Brandon Mitchell 8 | - Sajay Antony 9 | - Tianon 10 | - Michael Brown 11 | - Ramkumar Chinchani 12 | - Jason Hall 13 | - _attendees list_ 14 | 15 | ## Notetaker 16 | 17 | - Brandon Mitchell 🥇 18 | - _backup notetaker_ 🥈 19 | 20 | Agenda 21 | 22 | - Outstanding votes (Josh) 23 | - 24 | - 25 | - New PRs from Jamstah (Josh) 26 | - 27 | - 28 | - 29 | - Preparing changesets against image-spec/dist-spec (Josh) 30 | - 31 | - 32 | 33 | - new vote for partitioned digest tags: 34 | 35 | Notes 36 | 37 | - Issue 64 - artifactType 38 | - Concern that depending on the config descriptor media type will not work with Docker Hub (Brandon) 39 | - Consider specific use cases for Docker Hub (Michael) 40 | - Ask Docker Hub if they would consider changing their filtering on the Config media type 41 | - Brandon will update the PR based on comments and take out of draft state 42 | - Issue 65 - predictable digest tags 43 | - Majority is in favor of predictable tags 44 | - We need to pick whether it is a tag per artifact type or one tag for all artifacts 45 | - One tag per type requires a query to recursively get all artifacts, but removes the search space for tools working with specific types of artifacts 46 | - Opening a follow on vote in [Issue 72](https://github.com/opencontainers/wg-reference-types/issues/72) 47 | - There's still an option to roll back these changes before suggesting to OCI 48 | - Reviewing PRs from Jamstah 49 | - Some may go away with the decision on 65 50 | - Change sets to image-spec/dist-spec 51 | - distribution-spec has a sample PR by Josh 52 | - Nisha will start with the image-spec changes 53 | - To handle a migration with Go, it may require renames that would be handled with an alias. That may need a second repository rather than a rename. (Brandon) 54 | -------------------------------------------------------------------------------- /minutes/2022-07-26.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | July 26, 2022 4 | 5 | ## Attendees 6 | 7 | - Josh Dlistsky 8 | - Sajay Antony 9 | - Brandon Mitchell 10 | - Jason 11 | - Michael Brown (AWS) 12 | - Yi Chen 13 | - Tianon Gravi 14 | - Mounic 15 | - Chris Short 16 | - _attendees list_ 17 | 18 | ## Notetaker 19 | 20 | - _notetaker_ 🥇 21 | - _backup notetaker_ 🥈 22 | 23 | Agenda 24 | 25 | - Resolve some open votes (Josh) 26 | - 27 | - 28 | - 29 | - Preparing distribution-spec PR (Josh) 30 | - View diff [here](https://github.com/opencontainers/distribution-spec/compare/main...oci-playground:distribution-spec:pr) 31 | - [Suggested changes](https://github.com/oci-playground/distribution-spec/issues/1) (Brandon) 32 | - Preparing image-spec PR (Nisha) 33 | - View diff [here](https://github.com/opencontainers/image-spec/compare/main...oci-playground:image-spec:pr) 34 | - [Suggested changes](https://github.com/oci-playground/image-spec/issues/3) (Brandon) 35 | - PR to link to the changesets above: (Josh) 36 | - Discuss artifactType filtering: (Michael) 37 | - [Clarifications on E](https://github.com/opencontainers/wg-reference-types/pull/60) (Brandon) 38 | 39 | Notes 40 | -------------------------------------------------------------------------------- /minutes/2022-08-02.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | Aug 2, 2022 4 | 5 | ## Attendees 6 | 7 | - Brandon Mitchell 8 | - Sajay Antony 9 | - Yi Chen 10 | - Lachlan Evenson 11 | - Nisha Kumar 12 | - Michael Brown 13 | - _attendees list_ 14 | 15 | ## Notetaker 16 | 17 | - Brandon Mitchell 🥇 18 | - _backup notetaker_ 🥈 19 | 20 | Agenda 21 | 22 | - Should ordering of the manifest/descriptor fields be considered? (Nisha) 23 | - Should a list of artifact types be included? (Nisha) 24 | - More examples of image/artifact manifests? (Nisha) 25 | - Live code the upstream PRs (Josh) 26 | - [Michael] 27 | 28 | Notes 29 | 30 | - artifactType filtering: 31 | - Deciding if it makes sense to add this since clients will have filtering. 32 | - The negative is servers may need to cache multiple responses, one per media type 33 | - Michael will get a Vote opened up for this, to be closed by end of week. 34 | - How to handle a "refers" pushed before referred manifest exists? 35 | - Group seems to like responding to API even before manifest exists 36 | - Jason will add a PR for this 37 | - Avoid using 404 for cases other than "API not available" to avoid interfering with the "tag fallback" - Brandon 38 | - Involve the OCI Maintainers in the decision of the API route since the manifest that is referenced in the URI path and technically the manifest may not exists. 39 | - Is ordering important: 40 | - Within the descriptor itself (mediaType, digest, size) 41 | - How does this impact reproducibility? 42 | - This hasn't been handled by JSON previously. 43 | - Would be good to bring up reproducibility to image-spec maintainers, too big of a lift for this WG. (Sajay) 44 | - Should a list of artifact types be included? 45 | - We've gotten rid of the short artifact types from the spec 46 | - The IANA media types are pushed off to IANA 47 | - Adding more examples? 48 | - Pushing to have a more generic example instead of different example per type for SBOM/Sig/etc. 49 | - Live Coding PRs 50 | - Where should the tag schema fall back be defined? 51 | - Group is leaning towards distribution-spec 52 | - Started a PR for defining the push process with the tag schema in [oci-playground/distribution-spec](https://github.com/oci-playground/distribution-spec/pull/5/files) 53 | -------------------------------------------------------------------------------- /minutes/2022-08-09.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | Aug 9, 2022 4 | 5 | ## Attendees 6 | 7 | - _attendees list_ 8 | 9 | ## Notetaker 10 | 11 | - _notetaker_ 🥇 12 | - _backup notetaker_ 🥈 13 | 14 | Agenda 15 | 16 | - Submit the final output of this working group as 2 PRs 🎉 (Josh) 17 | - Discuss where to add `artifactType` to support the referrer API to have this field in the outputs. 18 | @sajay 19 | - image-spec: [Create pull request](https://github.com/opencontainers/image-spec/compare/main...oci-playground:image-spec:pr) 20 | - [PR opened](https://github.com/opencontainers/image-spec/pull/934) 21 | - distribution-spec: [Create pull request](https://github.com/opencontainers/distribution-spec/compare/main...oci-playground:distribution-spec:pr) 22 | - [PR opened](https://github.com/opencontainers/distribution-spec/pull/335) 23 | 24 | Notes 25 | -------------------------------------------------------------------------------- /minutes/2022-08-16.md: -------------------------------------------------------------------------------- 1 | # Date 2 | 3 | August 16, 2022 4 | 5 | ## Attendees 6 | 7 | - Brandon Mitchell 8 | - Sajay Antony 9 | - Lachlan Evenson 10 | - Michael Brown (IBM) 11 | - Josh Dlistsky 12 | - Jason 13 | - Tianon Gravi 14 | - Ramkumar Chinchani 15 | 16 | ## Notetaker 17 | 18 | - _notetaker_ 🥇 19 | - _backup notetaker_ 🥈 20 | 21 | Agenda 22 | 23 | - _enter agenda before meeting_ 24 | - Reviewing PR feedback 25 | - [PR 16](https://github.com/oci-playground/image-spec/pull/16) 26 | 27 | Notes 28 | --------------------------------------------------------------------------------