From 695241380f98322ee4792d403dcb74f18020493c Mon Sep 17 00:00:00 2001 From: Brandon Mitchell Date: Tue, 20 Feb 2024 16:21:43 -0500 Subject: [PATCH] Support referrers responses in the Image Layout Signed-off-by: Brandon Mitchell --- annotations.md | 6 ++++++ image-layout.md | 17 ++++++++++++++++- specs-go/v1/annotations.go | 10 ++++++++++ 3 files changed, 32 insertions(+), 1 deletion(-) diff --git a/annotations.md b/annotations.md index 137eaed3e..f26db2015 100644 --- a/annotations.md +++ b/annotations.md @@ -53,6 +53,12 @@ This specification defines the following annotation keys, intended for but not l - This SHOULD be the immediate image sharing zero-indexed layers with the image, such as from a Dockerfile `FROM` statement. - This SHOULD NOT reference any other images used to generate the contents of the image (e.g., multi-stage Dockerfile builds). - If the `image.base.name` annotation is specified, the `image.base.digest` annotation SHOULD be the digest of the manifest referenced by the `image.ref.name` annotation. +- **org.opencontainers.image.referrer.subject** Digest of the subject referenced by the referrers response (string) + - This SHOULD only be considered valid when on descriptors on `index.json` within [image layout](image-layout.md). + - The descriptor SHOULD be the referrers response for the subject digest. +- **org.opencontainers.image.referrer.convert** Defined and set to `true` when tooling has converted any referrers from the fallback tag to using the `org.opencontainers.image.referrer.subject` annotation. + - This SHOULD only be considered valid when on the manifest of the `index.json` within [image layout](image-layout.md). + - Tooling that reads an [image layout](image-layout.md) MAY skip the referrers conversion process when the annotation is detected. ## Back-compatibility with Label Schema diff --git a/image-layout.md b/image-layout.md index 112561e1f..e4c9c78c1 100644 --- a/image-layout.md +++ b/image-layout.md @@ -155,6 +155,11 @@ For example, an image may have a tag for different versions or builds of the sof In the wild you often see "tags" like "v1.0.0-vendor.0", "2.0.0-debug", etc. Those tags will often be represented in an image-layout repository with matching "org.opencontainers.image.ref.name" annotations like "v1.0.0-vendor.0", "2.0.0-debug", etc. +**Referrers Support:** +Referrers MAY be referenced using the fallback tag if the "org.opencontainers.image.referrer.convert" annotation is not set to "true". +Before writing descriptors with the "org.opencontainers.image.referrer.subject" annotation, implementations MUST ensure the "org.opencontainers.image.referrer.convert" annotation is set to "true" and convert any existing content referenced with the fallback tag if the annotation was not set. +If the "org.opencontainers.image.referrer.convert" annotation is set to "true", implementations MAY skip the conversion of referrers stored with the fallback tag and depend on the "org.opencontainers.image.referrer.subject" annotation to detect any referrers. + ### Index Example ```json,title=Image%20Index&mediatype=application/vnd.oci.image.index.v1%2Bjson @@ -190,9 +195,18 @@ Those tags will often be represented in an image-layout repository with matching "org.freedesktop.specifications.metainfo.version": "1.0", "org.freedesktop.specifications.metainfo.type": "AppStream" } + }, + { + "mediaType": "application/vnd.oci.image.index.v1+json", + "size": 7143, + "digest": "sha256:1efe7ab979c486a5af7a29d2c4603d84a3b934a7253d61b37e8573afecf47c03", + "annotations": { + "org.opencontainers.image.referrer.subject": "sha256:0228f90e926ba6b96e4f39cf294b2586d38fbb5a1e385c05cd1ee40ea54fe7fd" + } } ], "annotations": { + "org.opencontainers.image.referrer.convert": "true", "com.example.index.revision": "r124356" } } @@ -201,7 +215,8 @@ Those tags will often be represented in an image-layout repository with matching This illustrates an index that provides two named references and an auxiliary mediatype for this image layout. The first named reference (`stable-release`) points to another index that might contain multiple references with distinct platforms and annotations. -Note that the [`org.opencontainers.image.ref.name` annotation](annotations.md) SHOULD only be considered valid when on descriptors on `index.json`. +Note that the [`org.opencontainers.image.ref.name` and `org.opencontainers.image.referrer.subject` annotations](annotations.md) SHOULD only be considered valid when on descriptors on `index.json`. +The [`org.opencontainers.image.referrer.convert` annotation](annotations.md) SHOULD only be considered valid when on manifest of the `index.json`. The second named reference (`v1.0`) points to a manifest that is specific to the linux/ppc64le platform. diff --git a/specs-go/v1/annotations.go b/specs-go/v1/annotations.go index 581cf7cdf..c1fd529d1 100644 --- a/specs-go/v1/annotations.go +++ b/specs-go/v1/annotations.go @@ -59,4 +59,14 @@ const ( // AnnotationBaseImageName is the annotation key for the image reference of the image's base image. AnnotationBaseImageName = "org.opencontainers.image.base.name" + + // AnnotationReferrerSubject is the annotation key for the digest of the subject referenced by the referrers response. + // This SHOULD only be considered valid when on descriptors on `index.json` within image layout. + // The descriptor SHOULD be the referrers response for the subject digest. + AnnotationReferrerSubject = "org.opencontainers.image.referrer.subject" + + // AnnotationReferrerConvert is the annotation key that is set to "true" when tooling has converted any referrers from the fallback tag to using the `org.opencontainers.image.referrer.subject` annotation. + // This SHOULD only be considered valid when on the manifest of the `index.json` within image layout. + // Tooling that reads an image layout MAY skip the referrers conversion process when the annotation is detected. + AnnotationReferrerConvert = "org.opencontainers.image.referrer.convert" )