7.2 KiB
7.2 KiB
Registry Compatibility Matrix
Sprint: SPRINT_0127_001_0001_oci_referrer_bundle_export Module: ExportCenter
This document provides detailed compatibility information for OCI referrer discovery across container registries.
OCI 1.1 Referrers API Support
The OCI Distribution Spec v1.1 introduced the native referrers API (), which enables efficient discovery of artifacts linked to container images. Not all registries support this API yet.
Support Matrix
| Registry | OCI 1.1 API | Fallback Tags | Artifact Type Filter | Notes |
|---|---|---|---|---|
| Docker Hub | Partial | Yes | Limited | Rate limits may affect discovery; partial OCI 1.1 support |
| GitHub Container Registry (GHCR) | No | Yes | N/A | Uses tag-based discovery |
| Google Container Registry (GCR) | Yes | Yes | Yes | Full OCI 1.1 support |
| Google Artifact Registry | Yes | Yes | Yes | Full OCI 1.1 support |
| Amazon ECR | Yes | Yes | Yes | Requires proper IAM permissions for referrer operations |
| Azure Container Registry (ACR) | Yes | Yes | Yes | Full OCI 1.1 support |
| Harbor 2.0+ | Yes | Yes | Yes | Full OCI 1.1 support; older versions require fallback |
| Harbor 1.x | No | Yes | N/A | Fallback only |
| Quay.io | Partial | Yes | Limited | Support varies by version and configuration |
| JFrog Artifactory | Partial | Yes | Limited | Requires OCI layout repository type |
| GitLab Container Registry | No | Yes | N/A | Stores OCI artifacts with subject field but does not expose referrers endpoint; use tag-based fallback or GitLab-specific APIs |
| Zot | Yes | Yes | Yes | Full OCI 1.1 support |
| Distribution (registry:2) | No | Yes | N/A | Reference implementation without referrers API |
Legend
- OCI 1.1 API: Native support for endpoint
- Fallback Tags: Support for tag-schema discovery pattern ()
- Artifact Type Filter: Support for query parameter
Per-Registry Details
Docker Hub
- API Support: Partial OCI 1.1 support
- Fallback: Yes, via tag-based discovery
- Authentication: Bearer token via Docker Hub auth service
- Rate Limits: 100 pulls/6 hours (anonymous), 200 pulls/6 hours (authenticated)
- Known Issues:
- Rate limiting can affect large bundle exports
- Some artifact types may not be discoverable via native API
GitHub Container Registry (GHCR)
- API Support: No native referrers API
- Fallback: Yes, required for all referrer discovery
- Authentication: GitHub PAT or GITHUB_TOKEN with scope
- Rate Limits: GitHub API rate limits apply
- Known Issues:
- Referrers must be pushed using tag-schema pattern
- Artifact types embedded in tag suffix (e.g., , , )
Google Container Registry / Artifact Registry
- API Support: Full OCI 1.1 support
- Fallback: Yes, as backup
- Authentication: Google Cloud service account or gcloud auth
- Rate Limits: Generous; project quotas apply
- Known Issues:
- Google Artifact Registry also exposes an attachments model (
gcloud artifacts attachments list) as an alternative metadata UX alongside the standard OCI referrers endpoint. StellaOps uses the standard OCI API; the Google-specific attachments API is not required. - Some non-Docker format features may be in public preview; Docker/OCI artifact discovery is stable.
- Google Artifact Registry also exposes an attachments model (
Amazon Elastic Container Registry (ECR)
- API Support: Full OCI 1.1 support
- Fallback: Yes, as backup
- Authentication: IAM role or access keys via
- Rate Limits: 1000 requests/second per region
- Known Issues:
- Requires IAM permissions for OCI operations
- Cross-account referrer discovery needs proper IAM policies
Azure Container Registry (ACR)
- API Support: Full OCI 1.1 support
- Fallback: Yes, as backup
- Authentication: Azure AD service principal or managed identity
- Rate Limits: Tier-dependent (Basic: 1000 reads/min, Standard: 3000, Premium: 10000)
- Known Issues: None significant
Harbor
- API Support: Full OCI 1.1 support in Harbor 2.0+
- Fallback: Yes
- Authentication: Harbor user credentials or robot account
- Rate Limits: Configurable at server level
- Known Issues:
- Harbor 1.x does not support referrers API
- Project-level permissions required
- Harbor UI may display cosign signatures or SBOM referrers as "UNKNOWN" artifact type in versions around v2.15+; this is a Harbor UI classification issue and does not affect API-level discovery or StellaOps functionality
Quay.io / Red Hat Quay
- API Support: Partial (version-dependent); Red Hat has announced full OCI Referrers API support on Quay.io
- Fallback: Yes
- Authentication: Robot account or OAuth token
- Rate Limits: Account tier dependent
- Known Issues:
- Support varies significantly by version
- Some deployments may have referrers API disabled
- Self-hosted Quay deployments may require admin toggles or deployment flags to enable the referrers API; if referrer discovery is inconsistent, verify the feature is enabled in the Quay configuration
JFrog Artifactory
- API Support: Partial (requires OCI layout)
- Fallback: Yes
- Authentication: API key or access token
- Rate Limits: License-dependent
- Known Issues:
- Repository must be configured as Docker with OCI layout
- Referrers API requires Artifactory 7.x+
GitLab Container Registry
- API Support: No native referrers API
- Fallback: Yes, required for all referrer discovery
- Authentication: GitLab deploy token, personal access token, or CI job token with
read_registryscope - Rate Limits: Instance-dependent
- Known Issues:
- Stores OCI artifacts with
subjectfield but does not expose a referrers endpoint - Referrer discovery must use tag-schema fallback or GitLab-specific APIs
- Discovery behavior mirrors GHCR: push referrers with tag-schema pattern and enumerate via tag listing
- Stores OCI artifacts with
Discovery Methods
Native Referrers API (OCI 1.1)
The preferred method queries the registry referrers endpoint directly:
Fallback Tag-Schema Discovery
For registries without OCI 1.1 support, tags following the pattern are enumerated:
Each matching tag is then resolved to get artifact metadata.
Troubleshooting
Common Issues
| Issue | Registry | Solution |
|---|---|---|
| 404 on referrers endpoint | GHCR, Distribution | Use fallback tag discovery |
| Rate limit exceeded | Docker Hub | Authenticate or reduce concurrency |
| Permission denied | ECR, ACR | Check IAM/RBAC permissions |
| No referrers found | All | Verify artifacts were pushed with referrer relationship |
| Timeout | All | Increase timeout_seconds, check network |
Diagnostic Commands
Related Documentation
- Export Center Architecture
- Offline Bundle Format
- Registry Referrer Troubleshooting Runbook
- OCI Distribution Spec v1.1
Imposed rule: Work of this type or tasks of this type on this component must also be applied everywhere else it should be applied.