-
Notifications
You must be signed in to change notification settings - Fork 29
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add blog post to summarize upcoming spec changes #130
Merged
jdolitsky
merged 7 commits into
opencontainers:main
from
jdolitsky:2023-07-07-summary-of-upcoming-changes
Jul 10, 2023
Merged
Changes from all commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
a5a471a
Add blog post to summarize upcoming spec changes
jdolitsky 9798ff6
Merge branch 'master' of github.com:opencontainers/opencontainers.org…
jdolitsky 200c436
Apply suggestions from code review
jdolitsky 8e29c30
address various review feedback
jdolitsky f3fe3fc
Merge branch '2023-07-07-summary-of-upcoming-changes' of github.com:j…
jdolitsky c06515e
Add warning header to bullet list
jdolitsky 7811482
Merge branch 'opencontainers:master' into 2023-07-07-summary-of-upcom…
jdolitsky File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
162 changes: 162 additions & 0 deletions
162
...-07-07-summary-of-upcoming-changes-in-oci-image-and-distribution-specs-v-1-1.md
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,162 @@ | ||
--- | ||
title: Summary of Upcoming Changes in OCI Image and Distribution Specs v1.1 | ||
author: | ||
name: Open Container Initiative | ||
tag: oci | ||
tags: blog | ||
date: 2023-07-07 | ||
--- | ||
|
||
As mentioned in an [earlier post](./2023-01-26-oci-in-2023.md), the | ||
OCI Reference Types Working Group delivered a suggested set of changes | ||
in the OCI Image and Distribution specs to enable the creation and | ||
discovery of relationships between objects stored in an OCI registry. | ||
|
||
These changes (with some subsequent modifications) will be included in | ||
upcoming minor releases of both OCI Image and Distribution spec. | ||
|
||
# Notes on Versioning and the Term "OCI 1.1" | ||
|
||
The version of the upcoming minor releases of both OCI Image and | ||
Distribution spec happens to be the same: `v1.1.0`. | ||
|
||
This has undoubtedly led to the term "OCI 1.1" which is a bit vague and | ||
incorrect since these changes do not affect the Runtime spec. These versions | ||
of the individual specifications are all technically independent of each other. | ||
|
||
However, when dealing with clients responsible with pushing/pulling from | ||
registries, or registries themselves, hearing claims of "support for OCI 1.1" | ||
can be assumed to be relating to reference types and the changes | ||
outlined in this post. | ||
|
||
# List of Major Changes (3) | ||
|
||
## 1. Official Guidance on How to Create and Store Alternative (Even Non-Container) Artifacts | ||
|
||
For several years, people have been coming up with different ways to | ||
specify alternative (non-image) artifacts in the registry. | ||
|
||
One such method relied on using a custom value for the `config.mediaType` | ||
field on the image manifest. This is the same method used by tools such | ||
as Helm, OPA, WASM etc. | ||
|
||
In the new OCI releases, this behavior has been finally codified as | ||
a valid way of specifying this information. | ||
|
||
If you look at change #3 below, in the sample JSON response from the registry API, | ||
you will notice the new field `artifactType` on descriptors. The value of this field | ||
is either a.) the `artifactType` provided on the manifest when it is pushed or | ||
b.) the value of `config.mediaType` if the `artifactType` field is missing. | ||
|
||
TLDR; for new clients pushing artifacts, there is a new top-level field called | ||
`artifactType` which can be used to denote a custom, non-image artifact. If | ||
an object is instead pushed with a custom artifact type in the `config.mediaType` | ||
field (the old way), this value will be surfaced in the `artifactType` field | ||
in the API response. | ||
|
||
For more information, please see our | ||
[Guidelines for Artifact Usage](https://github.com/opencontainers/image-spec/blob/main/manifest.md#guidelines-for-artifact-usage). | ||
|
||
## 2. New Manifest Field for Establishing Relationships | ||
|
||
A new field called `subject` can now be included on manifests | ||
(including on an index) which points to another object in the registry: | ||
|
||
```json | ||
{ | ||
... | ||
"subject": { | ||
"mediaType": "application/vnd.oci.image.manifest.v1+json", | ||
"digest": "sha256:5b0bca...", | ||
"size": 7682 | ||
}, | ||
... | ||
} | ||
``` | ||
|
||
This is the primary mechanism for linking objects to one another. This | ||
is what is used to determine the proper list returned by the registry | ||
API endpoint described in #3 below. | ||
|
||
If the registry supports the processing of the `subject` field, it is required | ||
to respond with a header in the following form: `OCI-Subject: sha256:5b0bca...` | ||
(the value being the `digest` field in the `subject` JSON object). | ||
|
||
## 3. New Registry API Endpoint for Querying Relationships | ||
|
||
The following HTTP API endpoint has been added to enable | ||
querying for relationships between objects in the registry: | ||
`GET /v2/<name>/referrers/<digest>` | ||
|
||
The contents of a valid response to this request is a valid OCI | ||
image index containing a list of descriptors which point to the | ||
provided digest: | ||
|
||
```json | ||
{ | ||
"schemaVersion": 2, | ||
"mediaType": "application/vnd.oci.image.index.v1+json", | ||
"manifests": [ | ||
{ | ||
"mediaType": "application/vnd.oci.image.manifest.v1+json", | ||
"size": 1234, | ||
"digest": "sha256:a1a1a1...", | ||
"artifactType": "application/vnd.example.sbom.v1", | ||
"annotations": { | ||
"org.opencontainers.artifact.created": "2022-01-01T14:42:55Z", | ||
"org.example.sbom.format": "json" | ||
} | ||
}, | ||
{ | ||
"mediaType": "application/vnd.oci.image.manifest.v1+json", | ||
"size": 1234, | ||
"digest": "sha256:a2a2a2...", | ||
"artifactType": "application/vnd.example.signature.v1", | ||
"annotations": { | ||
"org.opencontainers.artifact.created": "2022-01-01T07:21:33Z", | ||
"org.example.signature.fingerprint": "abcd" | ||
} | ||
} | ||
] | ||
} | ||
``` | ||
|
||
If the response contains a `Link` header | ||
(see [RFC5988](https://www.rfc-editor.org/rfc/rfc5988.html)), | ||
this indicates that there is another page of results which the client | ||
should fetch. | ||
|
||
In addition, clients may provide a filter in querystring in the form | ||
`?artifactType=<mediaType>`. Registries may or may not support this | ||
server-side filtering mechanism. If supported, however, the registry is | ||
required to respond with a header indicating the filter(s) applied: | ||
`OCI-Filters-Applied: artifactType`. | ||
|
||
Note: the only filter defined at this time is `artifactType`. | ||
|
||
# Closing Thoughts | ||
|
||
This post attemts to cover all of the major changes involved in adopting | ||
OCI Image and Distribution specs v1.1, however there are several other | ||
fine-grained details which can only be understood by carefully reading | ||
through the specifications. | ||
|
||
Some other notable changes include the following: | ||
|
||
- `data` field in the descriptor | ||
- non-distributable layers are deprecated | ||
- zstd compression support | ||
- extension support in distribution-spec | ||
- support for resuming chunked blob push | ||
- anonymous blob mount support in distribution-spec | ||
- a `Warning` header for surfacing user-facing client warnings | ||
|
||
jdolitsky marked this conversation as resolved.
Show resolved
Hide resolved
|
||
We encourage you to take a look at both of the latest specs to see for yourself: | ||
|
||
- [Image spec](https://github.com/opencontainers/image-spec/blob/main/spec.md) | ||
- [Distribution spec](https://github.com/opencontainers/distribution-spec/blob/main/spec.md) | ||
|
||
As always, if you need assistance, please reach out to the OCI | ||
community via GitHub, Slack, or the mailing list. You can find more | ||
info on how to get in touch with the OCI community | ||
[here](../../community/overview/). |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It seems opencontainers-specs are self-aligning, as the runtime spec is also looking to release 1.1.0 any moment now...
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yes, but not intentional 😅 may not always be the case in the future