Add referrers fetcher to remotes #12309

dmcgowan · 2025-09-17T03:46:24Z

Adds an implementation of the referrers API from OCI distribution-spec 1.1.

Update from #7644

* **OCI Referrers Support** ([#12309](https://github.com/containerd/containerd/pull/12309))

  Adds new referrers fetcher to remote registry interface using the [new referrers endpoint added in OCI distribution-spec 1.1](https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#listing-referrers)

core/remotes/docker/referrers.go

tonistiigi · 2025-09-17T06:29:19Z

core/remotes/docker/referrers.go

+			desc.Size = cl
+			// Digest is not known ahead of time and there is nothing in the distribution
+			// specification defining an HTTP header to return the digest on referrers.
+			return rc, desc, nil


What is this descriptor? What's the use case of returning Descriptor without a Digest (other than hoping to cause a panic in the caller)?

The original idea was the caller would fill this in and use it to save the referrers index, however I think we discussed that we probably don't want to save the referrers index at all. We could return the index directly, we just don't currently use those parsed objects at this level of the interface normally.

And other places we do use partial descriptors for content verification, it can certainly be a trap for callers though.

core/remotes/docker/registry.go

tonistiigi · 2025-09-18T04:26:00Z

core/remotes/docker/referrers.go

+	defer rc.Close()
+
+	var index ocispec.Index
+	if err := json.NewDecoder(io.LimitReader(rc, size)).Decode(&index); err != nil {


Safe usage of json.NewDecoder requires calling smth like

if _, err := dec.Token(); !errors.Is(err, io.EOF) { return nil, errors.Errorf("unexpected data after JSON object") }

after Decode. No actual security issue in here, just potentially not validating garbage data from registry.

tonistiigi · 2025-09-18T04:29:02Z

core/remotes/docker/referrers.go

+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+)
+
+func (r dockerFetcher) FetchReferrers(ctx context.Context, dgst digest.Digest, artifactTypes ...string) ([]ocispec.Descriptor, error) {


If you change this to take descriptor instead of digest I could avoid defining https://github.com/containerd/containerd/compare/main...tonistiigi:containerd:referrers-wip?expand=1#diff-85dea1ce2bec55085339d4ec90127de60f896bae284b627e7c03c1ff7bcb6533R214 and just use remotes. ReferrersFetcher as input to puller/exporter etc. Ok if you wish to keep them separate.

In that case, when are the artifact types injected?

The callbacks in client will always set it to empty (as containerd library should not be opinionated about what referrers should be included) but provider interface implementation can add its own filters. I you prefer to keep callback interface separate (and without the artifacttype), then that is fine by me.

tonistiigi · 2025-09-18T04:33:45Z

core/remotes/docker/referrers.go

+		}
+	}
+
+	for i, host := range fallbackHosts {


Ideally there should be a way to opt-out of this fallback mechanism as eventually this should die and polluting repositories with these tags should stop. Maybe an item in ResolverOptions?

We could just avoid populating the fallback hosts if there are any referrers hosts

tonistiigi · 2025-09-19T17:47:36Z

core/remotes/docker/referrers.go

+	if err := json.NewDecoder(io.LimitReader(rc, size)).Decode(&index); err != nil {
+		return nil, fmt.Errorf("failed to decode referrers index: %w", err)
+	}
+	return index.Manifests, nil


As matching the artifactType is not guaranteed, then this should reapply the filter manually before returning.

Updated, if artifact is missing from a descriptor, it will include

Why skip the filter the user asked for, if not defined? Btw, the spec defines some response headers for this as well https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-referrers (I don't quite get what benefit they provide).

Updated to omit empty artifact types when artifact filters provided

If filtering is requested and applied, the response MUST include a header OCI-Filters-Applied: artifactType denoting that an artifactType filter was applied. If multiple filters are applied, the header MUST contain a comma separated list of applied filters.

I don't think there is anything we would want to do with this on our side, maybe just useful for caching or head requests.

core/remotes/docker/referrers.go

estesp

nit about an error message, but otherwise LGTM

Adds an implementation of the referrers API from OCI distribution-spec 1.1. Signed-off-by: Derek McGowan <derek@mcg.dev>

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>

Signed-off-by: Derek McGowan <derek@mcg.dev>

lujinda · 2025-11-06T07:14:43Z

core/remotes/docker/referrers.go

+	ocispec "github.com/opencontainers/image-spec/specs-go/v1"
+)
+
+func (r dockerFetcher) FetchReferrers(ctx context.Context, dgst digest.Digest, artifactTypes ...string) ([]ocispec.Descriptor, error) {


@dmcgowan Has the FetchReferrers function not been called yet? I don't see any references to it (except for the test function).

Currently being used by BuildKit. How we want to integrate it into transfer service and image validation still needs to be decided.

github-project-automation bot added this to Pull Request Review Sep 17, 2025

github-project-automation bot moved this to Needs Triage in Pull Request Review Sep 17, 2025

k8s-ci-robot added the size/L label Sep 17, 2025

dmcgowan assigned tonistiigi Sep 17, 2025

dmcgowan requested a review from tonistiigi September 17, 2025 03:46

dmcgowan unassigned tonistiigi Sep 17, 2025

dmcgowan added the impact/changelog label Sep 17, 2025

dosubot bot added the area/distribution Image Distribution label Sep 17, 2025

tonistiigi reviewed Sep 17, 2025

View reviewed changes

core/remotes/docker/registry.go Show resolved Hide resolved

dmcgowan force-pushed the remote-referrers branch from fc864f5 to c33374d Compare September 18, 2025 04:09

tonistiigi reviewed Sep 18, 2025

View reviewed changes

tonistiigi reviewed Sep 19, 2025

View reviewed changes

tonistiigi mentioned this pull request Sep 19, 2025

client: add referrers support to client #12311

Merged

dmcgowan force-pushed the remote-referrers branch 2 times, most recently from 3570a21 to ddf479c Compare September 19, 2025 21:10

k8s-ci-robot added the needs-rebase label Sep 19, 2025

dmcgowan force-pushed the remote-referrers branch from ddf479c to 984b99a Compare September 19, 2025 21:17

k8s-ci-robot removed the needs-rebase label Sep 19, 2025

tonistiigi approved these changes Sep 19, 2025

View reviewed changes

dmcgowan added this to the 2.2 milestone Sep 19, 2025

dmcgowan moved this from Needs Triage to Review In Progress in Pull Request Review Sep 22, 2025

dmcgowan requested review from estesp and fuweid September 24, 2025 18:27

estesp reviewed Sep 24, 2025

View reviewed changes

core/remotes/docker/referrers.go Outdated Show resolved Hide resolved

estesp approved these changes Sep 24, 2025

View reviewed changes

dmcgowan and others added 4 commits September 24, 2025 17:59

Add referrers fetcher to remotes

09b4ac1

Adds an implementation of the referrers API from OCI distribution-spec 1.1. Signed-off-by: Derek McGowan <derek@mcg.dev>

Update capabilities for referrers

c1b1297

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>

Add referrers to host config

b668614

Signed-off-by: Derek McGowan <derek@mcg.dev>

Add referrers to default registries

a7537cb

Signed-off-by: Derek McGowan <derek@mcg.dev>

dmcgowan force-pushed the remote-referrers branch from 984b99a to a7537cb Compare September 25, 2025 00:59

fuweid approved these changes Sep 26, 2025

View reviewed changes

fuweid added this pull request to the merge queue Sep 26, 2025

Merged via the queue into containerd:main with commit 1b613ba Sep 26, 2025
130 of 137 checks passed

github-project-automation bot moved this from Review In Progress to Done in Pull Request Review Sep 26, 2025

dmcgowan mentioned this pull request Oct 26, 2025

Prepare release notes for v2.2.0-rc.0 #12413

Merged

dmcgowan mentioned this pull request Nov 5, 2025

Prepare release notes for v2.2.0 #12473

Merged

lujinda reviewed Nov 6, 2025

View reviewed changes

Add referrers fetcher to remotes #12309

Add referrers fetcher to remotes #12309

Uh oh!

Conversation

dmcgowan commented Sep 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmcgowan Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

estesp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

dmcgowan commented Sep 17, 2025 •

edited

Loading

dmcgowan Sep 19, 2025 •

edited

Loading