checkId: check.integration.oci.capabilities plugin: stellaops.doctor.integration severity: info tags: [registry, oci, capabilities, compatibility]

OCI Registry Capability Matrix

This Doctor check probes the configured OCI registry to discover which optional Distribution Spec features it supports, so operators know upfront which Stella Ops release operations will work and which need a fallback. It is aimed at operators and DevOps engineers planning or troubleshooting registry-backed workflows.

What It Checks

Probes the configured OCI registry for five capabilities using a test repository (OCI:TestRepository, default library/alpine):

  1. Distribution version – GET /v2/, reads OCI-Distribution-API-Version or Docker-Distribution-API-Version header.
  2. Referrers API – GET /v2/<repo>/referrers/<digest> with OCI accept header; passes if 200 or if a 404 response contains OCI index JSON.
  3. Chunked upload – POST /v2/<repo>/blobs/uploads/; passes on 202 Accepted (upload session is immediately cancelled).
  4. Cross-repo mount – POST /v2/<repo>/blobs/uploads/?mount=<digest>&from=library/alpine; passes on 201 Created or 202 Accepted.
  5. Delete support (manifests and blobs) – OPTIONS request to check if DELETE appears in the Allow header.

Calculates a capability score (N/5). Warns if referrers API is unsupported, info if any other capability is missing, passes if all 5 are supported. Fails on connection errors.

Why It Matters

Different OCI registries support different subsets of the OCI Distribution Spec. Stella Ops uses referrers for attestation linking, chunked uploads for large SBOMs, cross-repo mounts for efficient promotion, and deletes for garbage collection. Knowing the capability matrix upfront prevents mysterious failures during release operations and allows operators to configure appropriate fallbacks.

Common Causes

How to Fix

Docker Compose

# Check registry type and version
docker compose exec gateway curl -sv https://registry.example.com/v2/ \
  -o /dev/null 2>&1 | grep -i 'distribution-api-version'

# If referrers API is missing, consider upgrading the registry
# Harbor 2.6+, Quay 3.12+, ACR, ECR, GCR/Artifact Registry support referrers

# Enable delete in Harbor
# Update harbor.yml: delete_enabled: true
# Restart Harbor

Bare Metal / systemd

# Test referrers API directly
curl -H "Accept: application/vnd.oci.image.index.v1+json" \
  https://registry.example.com/v2/library/alpine/referrers/sha256:abc...

# Test chunked upload
curl -X POST https://registry.example.com/v2/test/blobs/uploads/

# Enable delete in Docker Distribution
# In /etc/docker/registry/config.yml:
#   storage:
#     delete:
#       enabled: true
sudo systemctl restart docker-registry

Kubernetes / Helm

# values.yaml (for Harbor)
harbor:
  registry:
    deleteEnabled: true

# values.yaml (for Stella Ops)
oci:
  registryUrl: https://registry.example.com
  testRepository: library/alpine

helm upgrade stellaops ./chart -f values.yaml

Verification

stella doctor --check check.integration.oci.capabilities