stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity
Files
c58a236d70742082c8dda5a967972d08424732f2
git.stella-ops.org/docs/doctor/articles/integration/registry-capability-probe.md
master c58a236d70 Doctor plugin checks: implement health check classes and documentation 
Implement remediation-aware health checks across all Doctor plugin modules
(Agent, Attestor, Auth, BinaryAnalysis, Compliance, Crypto, Environment,
EvidenceLocker, Notify, Observability, Operations, Policy, Postgres, Release,
Scanner, Storage, Vex) and their backing library counterparts (AI, Attestation,
Authority, Core, Cryptography, Database, Docker, Integration, Notify,
Observability, Security, ServiceGraph, Sources, Verification).

Each check now emits structured remediation metadata (severity, category,
runbook links, and fix suggestions) consumed by the Doctor dashboard
remediation panel.

Also adds:
- docs/doctor/articles/ knowledge base for check explanations
- Advisory AI search seed and allowlist updates for doctor content
- Sprint plan for doctor checks documentation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-27 12:28:00 +02:00

3.4 KiB
Raw Blame History

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

OCI Registry Capability Matrix

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

  • Registry does not implement OCI Distribution Spec v1.1 (no referrers API)
  • Registry has delete operations disabled by policy
  • Chunked upload is disabled in registry configuration
  • Cross-repo mount is not supported by the registry implementation
  • Registry version is too old for newer OCI features

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 run --check check.integration.oci.capabilities

Related Checks

  • check.integration.oci.registry -- basic registry connectivity
  • check.integration.oci.referrers -- focused referrers API check with digest resolution
  • check.integration.oci.credentials -- credential validation
  • check.integration.oci.pull -- pull authorization
  • check.integration.oci.push -- push authorization