CINXE.COM

<!doctype html><html lang=en><head><meta charset=utf-8><meta name=viewport content="width=device-width,initial-scale=1"><title>OCI Image and Distribution Specs v1.1 Releases - Open Container Initiative</title><meta name=author content="map[name:Open Container Initiative tag:oci]"><link href="https://fonts.googleapis.com/css2?family=Lekton:ital,wght@0,400;0,700;1,400&family=Open+Sans:ital,wght@0,400;0,700;1,400;1,700&display=swap" rel=stylesheet><link rel=stylesheet href=/css/styles.min.2c854f9d0e2d21c43b3e71f444e1a7a2599607724f81a7653949a019f1f22878.css integrity="sha256-LIVPnQ4tIcQ7PnH0ROGnolmWB3JPgadlOUmgGfHyKHg="><meta name=generator content="Hugo 0.115.1"></head><body class="flex flex-col min-h-screen bg-lightgray"><header class="sticky top-0 w-full header-shadow"><div class="flex justify-left bg-darkgray"><div class="flex p-1"><a href=https://www.linuxfoundation.org/projects target=_blank><img src=/img/logos/logo_lf_projects.svg class=h-4></a></div></div><nav class="flex flex-wrap items-center justify-between bg-white xs:flex-col sm:flex-col md:flex-col lg:flex-row"><div class="flex-none p-1 md:items-center sm:w-auto md:w-auto"><a href=https://opencontainers.org/ class="flex items-center"><img src=/img/logos/OCI-logo.svg class=h-10></a></div><nav class="flex flex-wrap items-center justify-between pr-5 sm:w-auto md:w-auto"><input id=nav-toggle type=checkbox class=hidden> <label id=show-button for=nav-toggle class="flex items-center block text-gray-500 sm:hidden hover:text-blue-500"><svg class="w-4 h-4 fill-current" viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg"><title>Menu Open</title><path d="M0 3h20v2H0V3zm0 6h20v2H0V9zm0 6h20v2H0V0z"/></svg></label><label id=hide-button for=nav-toggle class="flex items-center hidden p-2 text-gray-700 hover:text-blue-500"><svg class="w-4 h-4 fill-current" viewBox="0 0 20 20" xmlns="http://www.w3.org/2000/svg"><title>Menu Close</title><polygon points="11 9 22 9 22 11 11 11 11 22 9 22 9 11 -2 11 -2 9 9 9 9 -2 11 -2" transform="rotate(45 10 10)"/></svg></label><ul id=nav-menu class="items-center justify-end flex-grow hidden w-full mt-2 md:flex-row sm:flex-row sm:flex sm:w-auto sm:block list-reset sm:mt-0"><li class="parent-menu-item sm:self-start"><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=#>About <ion-icon name=chevron-down-sharp class=align-middle></ion-icon></a><div class="p-2 child-menu"><ul><li><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=/about/overview>About the OCI</a></li><li><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=https://github.com/opencontainers/tob/blob/master/CHARTER.md target=_blank>Governance <ion-icon name=trending-up-sharp title="external link"></ion-icon></a></li><li><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=https://github.com/opencontainers/.github/blob/master/CODE_OF_CONDUCT.md target=_blank>Code of conduct <ion-icon name=trending-up-sharp title="external link"></ion-icon></a></li><li><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=/about/tob>Leadership</a></li><li><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=/about/security-disclosure>Security disclosure</a></li></ul></div></li><li class="parent-menu-item sm:self-start"><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=#>Community <ion-icon name=chevron-down-sharp class=align-middle></ion-icon></a><div class="p-2 child-menu"><ul><li><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=/community/overview>Overview</a></li><li><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=/community/certified>Certification program</a></li></ul></div></li><li class="parent-menu-item sm:self-start"><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=/join>Join</a></li><li class="parent-menu-item sm:self-start"><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=/posts/blog>Blog</a></li><li class="parent-menu-item sm:self-start"><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=#>News <ion-icon name=chevron-down-sharp class=align-middle></ion-icon></a><div class="p-2 child-menu"><ul><li><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=/posts/announcements/>Announcements</a></li><li><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=/posts/news/>In the news</a></li></ul></div></li><li class="parent-menu-item sm:self-start"><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=/faq>FAQ</a></li><li class="parent-menu-item sm:self-start"><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=/release-notices>Release notices</a></li><li class="parent-menu-item sm:self-start"><a class="inline-block text-gray-500 sm:px-2 hover:text-lightpurple lekton navbar-item" href=/contact>Contact us</a></li><li class="parent-menu-item sm:self-start"><a href=https://twitter.com/OCI_ORG class=p-2 target=_blank title="follow us on Twitter"><ion-icon name=logo-twitter class=pt-1></ion-icon></a></li></ul></nav></nav></header><main class="container mx-auto"><article class="mt-5 mb-5 lg:mt-20 lg:mb-10"><div class="px-3 pt-10 pb-5 lg:px-10 single-header"><h1 class="text-3xl font-bold">OCI Image and Distribution Specs v1.1 Releases</h1><p class="pb-5 meta">Wednesday, March 13, 2024 by Open Container Initiative</p><div id=sharing><a href="http://www.facebook.com/sharer.php?u=https%3a%2f%2fopencontainers.org%2fposts%2fblog%2f2024-03-13-image-and-distribution-1-1%2f" class=pl-1 aria-label="share on Facebook"><ion-icon name=logo-facebook></ion-icon></a> <a href="http://twitter.com/share?url=https%3a%2f%2fopencontainers.org%2fposts%2fblog%2f2024-03-13-image-and-distribution-1-1%2f&text=OCI%20Image%20and%20Distribution%20Specs%20v1.1%20Releases&via=" class=pl-1 aria-label="share on Twitter"><ion-icon name=logo-twitter></ion-icon></a> <a href="http://www.linkedin.com/shareArticle?mini=true&url=https%3a%2f%2fopencontainers.org%2fposts%2fblog%2f2024-03-13-image-and-distribution-1-1%2f&title=OCI%20Image%20and%20Distribution%20Specs%20v1.1%20Releases" onclick='return window.open("http://www.linkedin.com/shareArticle?mini=true&url="+encodeURIComponent(document.URL)+"&title="+encodeURIComponent(document.title)),!1' class=pl-1 aria-label="share on LinkedIn"><ion-icon name=logo-linkedin></ion-icon></a></div></div><div class="px-3 py-3 bg-white lg:px-32 lg:py-24 content"><p>The OCI Image Specification and Distribution Specification each had a 1.1.0 release on February 15, 2024. These are the first minor releases since the 1.0.0 releases in July 2017 and May 2021 respectively, and include a number of notable changes.</p><h1 id=artifacts>Artifacts <a class=headline-hash href=#artifacts><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h1><p>The biggest highlight of these releases is support for associating metadata artifacts with existing OCI images. New <code>subject</code> and <code>artifactType</code> fields have been added to the image specification and retrieval of these associated artifacts can be done via a new referrers API in the distribution specification. However, this is far from the only thing that was changed. And many of these changes may affect existing OCI conformant projects.</p><h2 id=guidance-for-artifacts>Guidance for Artifacts <a class=headline-hash href=#guidance-for-artifacts><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h2><p>OCI has been used to package objects other than container images for some time, including projects like Helm, OPA, and Wasm. The guidance for how projects should implement artifacts has now been <a href=https://github.com/opencontainers/image-spec/blob/v1.1.0/artifacts-guidance.md>codified into the image specification</a>.</p><p>The recommendation to use a <code>config.mediaType</code> value different from the recognized container image values remains. That guidance is now extended to include a new <code>artifactType</code> field that enables use cases without a dedicated <code>config.mediaType</code>. In the scenarios were an artifact does not have content for the config or any layers, an <a href=https://github.com/opencontainers/image-spec/blob/v1.1.0/manifest.md#guidance-for-an-empty-descriptor>empty JSON descriptor is recommended</a> as a placeholder to satisfy the requirement that these fields exist, while serving as an indication to consuming tools that there is no useful content in that descriptor.</p><h2 id=describing-associations>Describing Associations <a class=headline-hash href=#describing-associations><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h2><p>A <code>subject</code> field has been added to the image specification manifests to define an association to another manifest. This is used by the <a href=#referrers-api>Referrers API</a> described below. It allows tools to associate signatures, attestations, and other metadata with images with a common specification.</p><p>Putting together the advice for packaging artifacts with the <code>subject</code> field to associate the artifact with an image, results in a manifest that may look like:</p><pre tabindex=0><code class=language-jsonc data-lang=jsonc>{ "schemaVersion": 2, "mediaType": "application/vnd.oci.image.manifest.v1+json", "artifactType": "application/example", "config": { "mediaType": "application/vnd.oci.empty.v1+json", "digest": "sha256:44136fa355b3678a1146a...", "size": 2 }, "layers": [ { "mediaType": "application/example", "digest": "sha256:e3b0c44298fc1c149af...", "size": 0 } ], "subject": { "mediaType": "application/vnd.oci.image.manifest.v1+json", "digest": "sha256:21edd7d11800e94bae9f4...", "size": 1769 }, "annotations": { "org.opencontainers.image.created": "2024-03-02T15:16:17Z", "org.opencontainers.image.description": "Example artifact for image sha256:21ed..." } } </code></pre><h2 id=referrers-api>Referrers API <a class=headline-hash href=#referrers-api><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h2><p>In the distribution-spec, the counterpart to the <code>subject</code> field is the the new <a href=https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers>referrers API</a>: <code>GET /v2/<name>/referrers/<digest></code>. This API returns an OCI Index listing the manifests where the <code>subject</code> digest matches the requested <code><digest></code> value. Each of the descriptors in the response also include the <code>artifactType</code> and <code>annotation</code> values from the referenced manifest. Including those values allows tooling to select their desired artifact from the OCI Index the same way runtimes use the platform to select an image to run from a multi-platform Index.</p><p>The referrers response to <code>GET /v2/<name>/referrers/sha256:21edd7d11800e94bae9f4...</code> may look like:</p><pre tabindex=0><code class=language-jsonc data-lang=jsonc>{ "schemaVersion": 2, "mediaType": "application/vnd.oci.image.index.v1+json", "manifests": [ { "mediaType": "application/vnd.oci.image.manifest.v1+json", "digest": "sha256:9e6569b15e5ed981334003eb8...", "size": 724, "annotations": { "org.opencontainers.image.created": "2024-03-02T15:16:17Z", "org.opencontainers.image.description": "Example artifact for image sha256:21ed..." }, "artifactType": "application/example" }, { "mediaType": "application/vnd.oci.image.manifest.v1+json", "digest": "sha256:e40ce69ad428e47eb72ea76d9...", "size": 701, "annotations": { "org.opencontainers.image.created": "2024-03-03T15:15:15Z", "org.opencontainers.image.description": "Another example artifact for same image" }, "artifactType": "application/example2" } ] } </code></pre><h2 id=support-for-existing-registries>Support For Existing Registries <a class=headline-hash href=#support-for-existing-registries><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h2><p>The design of the changes to the image and distribution specifications assume that it will take time for registries to upgrade. To facilitate this transition period, changes to the image spec added new fields which should be ignored by registries without generating errors or modifying the content of the manifest. Clients pushing a manifest with a <code>subject</code> field and querying for referrers have an additional responsibility to manage and use a <a href=https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#unavailable-referrers-api>fallback tagged Index when the registry does not support the referrers API</a>. When a registry supports the referrers API, it will return the header <code>OCI-Subject</code> set to the digest in the <code>subject</code> field in response to a client pushing a manifest with the <code>subject</code> field. Similarly, when querying for referrers, a registry that supports the API will always return a <code>200</code> response, even if the response is an empty Index, to distinguish between registries that have not implemented the API and may respond with a <code>404</code> or similar error.</p><p>The fallback tag is the digest of the requested subject, with the <code>:</code> replaced by a <code>-</code>. Clients would fetch that tag similar to pulling any other tagged image. For example if <code>GET /v2/<name>/referrers/sha256:21edd7d11800e94bae9f4...</code> returned a 404, clients should fallback to requesting <code>GET /v2/<name>/manifests/sha256-21edd7d11800e94bae9f4...</code>. The content of the fallback tag on older registries is maintained by clients to be identical to the referrers response on upgraded registries.</p><p>The client requirement to manage the fallback tag is subject to race conditions since the existing content of the fallback tag must first be queried to add the new entry. The fallback tags also clutter the tag listing with entries that are not the images end users are searching for. Because of this, having registries upgrade to support the referrers API is preferred.</p><h1 id=data-field>Data Field <a class=headline-hash href=#data-field><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h1><p>A <code>data</code> field was added to the definition of a <a href=https://github.com/opencontainers/image-spec/blob/v1.1.0/descriptor.md>descriptor</a> in the image specification. This optional field contains the base64 encoded content of the blob. When a client supports the field and encounters it, the additional requests to get the blob may be skipped. Because many clients do not support this field, and base64 encoding adds overhead, it is recommended to only use this feature for small blobs.</p><h1 id=manifest-maximum-size>Manifest Maximum Size <a class=headline-hash href=#manifest-maximum-size><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h1><p>When <a href=https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#pushing-manifests>pushing manifests</a>, many clients and registries have size limits to prevent various resource exhaustion attacks. The distribution specification now clarifies that a registry seeing its limit exceeded should return a 413 (payload too large) response to clients. And the specification also recommends that registries should support up to a 4MiB image manifest (containing JSON descriptors, not the image layer content). For portability, clients should avoid exceeding this limit by limiting the usage of the <code>data</code> field and annotations.</p><h1 id=deprecation-of-non-distributable-layers>Deprecation of Non-Distributable Layers <a class=headline-hash href=#deprecation-of-non-distributable-layers><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h1><p>OCI has deprecated the creation of <a href=https://github.com/opencontainers/image-spec/blob/v1.1.0/layer.md#non-distributable-layers>non-distributable layers</a>. These layers were used to indicate content that should not be uploaded to registries but rather downloaded from an original distributor. Because the primary use case for these layers no longer required the feature, and the use case breaks many scenarios, including air-gapped network support, OCI recommends against their usage going forward.</p><h1 id=support-for-zstd-compression>Support for zstd Compression <a class=headline-hash href=#support-for-zstd-compression><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h1><p>Media types have been added for <a href=https://github.com/opencontainers/image-spec/blob/v1.1.0/layer.md#zstd-media-types>zstd image layers</a> in the image specification. Compared to the traditional gzip compression, zstd typically uses less CPU and compresses content to a smaller size.</p><h1 id=anonymous-blob-mounts>Anonymous Blob Mounts <a class=headline-hash href=#anonymous-blob-mounts><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h1><p>When pushing blobs, a client may first attempt to <a href=https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#mounting-a-blob-from-another-repository>mount the blob from another repository</a>, avoiding the need to upload the blob content. A blob mount traditionally required a source repository. This <code>from</code> parameter is now optional, and the registry may support the blob mount without a defined source. This is useful for scenarios where the base image location on a registry is not known to the client, perhaps because the base image was originally pulled from another registry but has already been pushed to the target registry by other image builds.</p><p>If the mount fails for any reason, the registry should still default to initiating the blob upload session, making a blob push with or without the attempted blob mount take the same number of API requests.</p><h1 id=resumable-chunked-blob-uploads>Resumable Chunked Blob Uploads <a class=headline-hash href=#resumable-chunked-blob-uploads><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h1><p><a href=https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#pushing-a-blob-in-chunks>Chunked uploads</a> allow a blob to be pushed across multiple requests to the registry, which may be useful for pushing large blobs over an unreliable network. In order to recover an interrupted blob push, it is necessary to know the current progress of the upload on the registry, which the client would not have received. To update the client state, a <code>GET</code> request to one of the preceding <code>POST</code> or <code>PATCH</code> request locations now returns the current upload location and the received range.</p><h1 id=registry-api-extensions>Registry API Extensions <a class=headline-hash href=#registry-api-extensions><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h1><p><a href=https://github.com/opencontainers/distribution-spec/blob/v1.1.0/extensions/README.md>Extensions to the registry API</a> may be added by implementations without requiring a change to the OCI distribution specification. This allows development and testing of new features, in addition to custom features in a registry. Extensions are denoted by a leading <code>_</code> in their API path, which is invalid for a repository name. The syntax for an extension API is either <code>/v2/_<extension>/<component>/<module>[?params]</code> for registry level extensions, or <code>/v2/<name>/_<extension>/<component>/<module>[?params]</code> for repository level extensions. For example, the following extension is used to list installed extensions: <code>GET /v2/<name>/_oci/ext/discover</code>. To prevent conflicts, extensions should register their name with the distribution specification.</p><h1 id=multiple-matching-platforms>Multiple Matching Platforms <a class=headline-hash href=#multiple-matching-platforms><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h1><p>When multiple entries in an <a href=https://github.com/opencontainers/image-spec/blob/v1.1.0/image-index.md>OCI Index</a> appear to be the same, runtime tooling should prefer the first match. This clarification allows future extensibility for tooling that may wish to add additional images for the same platform that would be detected and used by their tooling.</p><p>To get involved with efforts to increase the platform extensibility, see the <a href=https://github.com/opencontainers/wg-image-compatibility>OCI Working Group on Image Compatibility</a>.</p><h1 id=warning-header>Warning Header <a class=headline-hash href=#warning-header><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h1><p>Registries may now include a <a href=https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#warnings>warning header</a> in responses. This can be used to notify users of issues that are not yet error conditions, including deprecation announcements.</p><h1 id=no-artifact-manifest>No Artifact Manifest <a class=headline-hash href=#no-artifact-manifest><span class="icon hashlink"><ion-icon name=link-sharp class=align-middle></ion-icon></span></a></h1><p>Notably absent from this release is a new type of manifest dedicated to artifacts. This was removed from the release candidates because of a combination of portability concerns and a lack of added value.</p><p>A new manifest type is inherently non-portable to older registries since registries parse manifests and reject unknown manifest media types. This would typically be handled by defining a new type, upgrading the various consumer tools and registries to be ready, and later upgrade the tooling that produces artifacts after time had passed to allow a controlled upgrade. In practice, OCI saw a notable uptake of the new manifest by content producers in the very early release candidates, long before registries and other consumers had the opportunity to upgrade.</p><p>While debating whether and how OCI could phase a rollout of a new manifest type, the alternative of reusing the existing image manifest was revisited. The image manifest was already being used by artifact producers, including projects like Helm and Sigstore. By adding the <code>artifactType</code> field to the image manifest, and defining the empty JSON descriptor, all of the use cases that previously required a new artifact manifest could be retrofitted into the existing image manifest.</p><p>Without any requirements that necessitated the new manifest type, and no easy solution to the portability concerns, the difficult decision was made to remove the new manifest type from the release candidates. Future work in OCI may revisit a new manifest type by focusing on use cases and capabilities that cannot be provided with the existing manifests. To participate in the development of the OCI specifications, please <a href=https://opencontainers.org/community/overview/>join the open community</a>.</p></div></article></main><footer class="container flex grid self-center grid-cols-12 p-4 md:w-full"><p class="col-span-12 lg:col-span-4">Copyright 漏 The Linux Foundation庐. All rights reserved. The Linux Foundation has registered trademarks and uses trademarks. For a list of trademarks of The Linux Foundation, please see our <a href=https://www.linuxfoundation.org/trademark-usage target=_blank>Trademark Usage</a> page. Linux is a registered trademark of Linus Torvalds. <a href=https://www.linuxfoundation.org/trademark-usage target=_blank>Privacy Policy</a> and <a href=https://www.linuxfoundation.org/terms target=_blank>Terms of Use</a></p></footer><script type=module src=https://unpkg.com/ionicons@5.0.0/dist/ionicons/ionicons.esm.js></script> <script nomodule src=https://unpkg.com/ionicons@5.0.0/dist/ionicons/ionicons.js></script></body></html>