#27
Issues/iximiuz/labs/#27

Support for OCI Referrers API and Alternate Registries in Labs Platform

Openrossbachpopened 1y ago

Hi Ivan,

I’ve been experimenting with the OCI Referrers API and noticed that the awesome labs platform currently uses Docker’s registry:2 as the default:

#examples/iximiuz/labs-platform/bender/plays
LL1279: if out, err := exeutils.ExecOut("docker", append(cmd, "registry:2")...); err != nil {

Would you consider supporting alternative registries that implement the Referrers API, such as:

Why Zot?

Zot is an OCI-native registry with first-class support for artifacts and references, making it ideal for learning and experimenting with emerging OCI features like oras attach and oras discover.

Key Features of Zot Registry:

  • Fully OCI-compliant with native Referrers API support
  • Lightweight, fast startup, and minimal dependencies
  • Built-in authentication (OAuth, LDAP, etc.)
  • Image search and filtering
  • Artifact signing (Cosign, Notary v2)
  • Metrics via Prometheus
  • Web UI for image browsing
  • Multi-arch and remote registry proxying support

This would allow use cases like attaching artifacts with oras attach and discovering them with oras discover, which currently work great with Zot:

curl -sL -H "Accept: application/vnd.oci.image.index.v1+json" \
  127.0.0.1:5000/v2/myimage/referrers/<digest> | jq

Testing Referrers API with Zot

Distribution Registry 2/3 has no support for OCI Referrers API

  • or you know the option to acitvate this?

Start Registry:

#dosen't work
#docker run -d --name registry -p 5000:5000 registry:3

# works
docker run -d \
  --name zot \
  -p 5000:5000 \
  ghcr.io/project-zot/zot:v2.1.2

Copy Container Image

IMAGE=k8sstormcenter/webapp@sha256:e323014ec9befb76bc551f8cc3bf158120150e2e277bae11844c2da6c56c0a2b

# 2. Download to local registry
docker pull ghcr.io/$IMAGE
docker tag ghcr.io/$IMAGE \
  127.0.0.1:5000/k8sstormcenter/webapp:latest
docker push 127.0.0.1:5000/k8sstormcenter/webapp:latest

Prepapre Bob Arfifact and Attach

cat > bob-artifact.yaml <<EOF
spec:
  build: bob
  arch: amd64
  url: https://bob.artifact/reference
EOF

VERSION="1.2.3"
curl -LO "https://github.com/oras-project/oras/releases/download/v${VERSION}/oras_${VERSION}_linux_amd64.tar.gz"
mkdir -p oras-install/
tar -zxf oras_${VERSION}_*.tar.gz -C oras-install/
sudo mv oras-install/oras /usr/local/bin/
rm -rf oras_${VERSION}_*.tar.gz oras-install/

oras attach --plain-http 127.0.0.1:5000/k8sstormcenter/webapp:latest  \
  --artifact-type "application/vnd.bob.artifact+yaml" \
  --annotation "org.opencontainers.artifact.description=BoB Security Policy" \
   \
  bob-artifact.yaml:application/yaml

Discover Referrers


oras discover 127.0.0.1:5000/k8sstormcenter/webapp:latest --plain-http
127.0.0.1:5000/k8sstormcenter/webapp@sha256:dab18b4d7784d33644f02f88e4df384c37cfc8a4c038e345af24d6d666d12e0e
└── application/vnd.bob.artifact+yaml
    └── sha256:bfc8b997c2afe38ae48b813a0c2a767777b311b28e07d7095fb91541db073bb7
oras manifest fetch --plain-http 127.0.0.1:5000/k8sstormcenter/webapp@sha256:dab18b4d7784d33644f02f88e4df384c37cfc8a4c038e345af24d6d666d12e0e

# zot support this!
curl -sL -H "Accept: application/vnd.oci.image.index.v1+json"  \
  127.0.0.1:5000/v2/k8sstormcenter/webapp/referrers/sha256:dab18b4d7784d33644f02f88e4df384c37cfc8a4c038e345af24d6d666d12e0e \
  | jq .
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.index.v1+json",
  "manifests": [
    {
      "mediaType": "application/vnd.oci.image.manifest.v1+json",
      "digest": "sha256:5f67a899efa5d1a52913adba22be99883cd3a227c9cc0a0bd9f7fe5d568fbcde",
      "size": 813,
      "annotations": {
        "org.opencontainers.artifact.description": "BoB Security Policy",
        "org.opencontainers.image.created": "2025-05-09T12:59:40Z"
      },
      "artifactType": "application/vnd.bob.artifact+yaml"
    }
  ]
}

Why This Matters

Adding support for alternate registries like Zot in the labs platform would enable:

  • Experiments with real-world artifact metadata use cases (e.g., SBOMs, policies)
  • Learning hands-on OCI features (attach/discover)
  • Exploring OCI 1.1 workflows in controlled environments
  • A single integrated solution with authentication, a built-in web UI, and proxy support for remote registries!

Would love to hear your thoughts on making this an optional or configurable backend!

Thanks so much, Peter

Activity

3
Vad1mo1y ago

Big fan of ZoT, but since I am a Harbor maintainer.. I suggest using Harbor for the use case as its a widly common and adopted registry.

It also supports referrers-api

Docker Distribution 3 does also support referrers-api

rossbachp1y ago

I tested this with Docker Distribution v3, but the Referrers API endpoint responds with a 404. Is there a configuration option required to enable it?

rossbachp1y ago

The Bob Artifact can be access with:

curl -sL   -H "Accept: application/vnd.oci.image.manifest.v1+json"   http://127.0.0.1:5000/v2/k8sstormcenter/webapp/manifests/sha256:a408d2fbb03e45d01948f40489d73cb62007ffe28d5eafa746d4f88cc39700f0 | jq .
{
  "schemaVersion": 2,
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "artifactType": "application/vnd.bob.artifact+yaml",
  "config": {
    "mediaType": "application/vnd.oci.empty.v1+json",
    "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
    "size": 2,
    "data": "e30="
  },
  "layers": [
    {
      "mediaType": "application/yaml",
      "digest": "sha256:b8cef3b4a04518718395f0156a7f033b9218316871a57f8194a381f3d64eb95b",
      "size": 71,
      "annotations": {
        "org.opencontainers.image.title": "bob-artifact.yaml"
      }
    }
  ],
  "subject": {
    "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
    "digest": "sha256:dab18b4d7784d33644f02f88e4df384c37cfc8a4c038e345af24d6d666d12e0e",
    "size": 3660
  },
  "annotations": {
    "org.opencontainers.artifact.description": "BoB Security Policy",
    "org.opencontainers.image.created": "2025-05-12T18:15:47Z"
  }
}

You can see that the subject is correctly set in the artifact.
However, Docker Distribution v3 does not support the Referrers API so discovering attached artifacts like SBOMs won't work with it.