Overview

Enable OCI Referrers API pass-through in the registry-proxy service that fronts registry.redhat.io and registry.access.redhat.com. The backend quay.io already supports the OCI 1.1 Referrers API, but the registry-proxy currently lacks a handler for the /v2/:name/referrers/:digest endpoint, causing referrer queries to fail when accessing images through the Red Hat container registries.

Context

The registry-proxy is a Go-based reverse proxy that sits in front of quay.io, providing:

• SSO/JWT authentication integration
• Authorization and access control
• Terms filtering and content policies
• ISV published-image verification
• Namespace translation for Quay backend

Current State:

• quay.io fully supports the OCI Referrers API: GET /v2/:name/referrers/:digest
• registry-proxy handles manifests, blobs, tags, catalog endpoints
• registry-proxy has no handler for the referrers endpoint - requests fail

Technical Root Cause: The registry-proxy URL pattern matching and routing logic does not recognize or handle the /v2/:name/referrers/:digest path pattern. The endpoint needs to be added with appropriate middleware (auth, authorization, filtering) applied.

Original Feature: PROJQUAY-10176 (RFE-8487)

Scope

In Scope

• Add URL pattern recognition for /v2/:name/referrers/:digest endpoint
• Create referrers handler to proxy requests to quay.io backend
• Apply existing middleware chain (auth, authorization, terms filtering)
• Support artifactType query parameter pass-through
• Handle namespace translation for Quay backend (slash to ----)
• Return proper OCI-compliant error responses
• Add appropriate logging and metrics

Out of Scope

• Modifying quay.io referrers implementation (already works)
• Caching referrer responses (can be added later if needed)
• Filtering referrers based on artifact type (pass-through only)
• Modifying referrer content (pure proxy)

Child Stories

1. Add referrers URL pattern to registry-proxy: Update pkg/registry/url.go to recognize /v2/:name/referrers/:digest path pattern with regex matching.
2. Create referrers handler: Implement pkg/handlers/referrers.go to handle referrers requests, extract repo name and digest, and route to backend.
3. Integrate referrers handler into routing: Update main.go to register the referrers handler with the appropriate middleware chain.
4. Apply namespace translation for Quay backend: Ensure referrers requests apply the same namespace escaping as manifests/blobs.
5. Add referrers authorization checks: Ensure existing auth middleware validates access to the subject image before proxying referrers request.
6. Handle ISV published-only mode for referrers: In ISV mode, verify the subject image is published before allowing referrers access.
7. Add unit tests for referrers handler: Test URL pattern matching, handler logic, namespace translation, and error cases.
8. Add integration tests for referrers pass-through: End-to-end tests verifying referrers work through the full proxy stack.

Components Affected

• pkg/registry/url.go - Add referrers path regex pattern
• pkg/handlers/referrers.go (new) - Referrers endpoint handler
• pkg/handlers/backend.go - May need minor updates for referrers path handling
• main.go - Register referrers route with middleware chain
• pkg/log/path_resolver.go - Add referrers path for logging/metrics

Technical Approach

Architecture

Client Request: GET /v2/redhat/ubi9/referrers/sha256:abc123
                            |
                            v
                    registry-proxy
                            |
            +-------------------------------+
            |  Logging Middleware           |
            |  Auth Middleware (JWT)        |
            |  Terms Filtering              |
            |  Authorization                |
            |  Referrers Handler (NEW)      |
            +-------------------------------+
                            |
                            v
            Backend: quay.io/redhat----ubi9/referrers/sha256:abc123
                            |
                            v
            Response: OCI Index with referrer manifests

Key Technical Decisions

1. Pure pass-through: The referrers handler will proxy requests directly to quay.io without modifying the response. This keeps the implementation simple and ensures compatibility.
2. Reuse existing middleware: Apply the same auth, authorization, and filtering middleware used for manifests. If a user can pull the manifest, they can query its referrers.
3. Namespace translation: Apply the same namespace escaping logic used for manifests (slash to ----) when proxying to Quay backend.
4. Query parameter forwarding: Pass through the artifactType query parameter to the backend for filtering.

Success Criteria

• GET /v2/:name/referrers/:digest returns referrers from quay.io backend
• artifactType query parameter filtering works correctly
• Authentication required (same as manifest access)
• Authorization checks applied (user must have access to repo)
• Terms filtering applied (if repo requires terms acceptance)
• ISV published-only mode verified (if enabled)
• Namespace translation works for Quay backend
• Proper OCI-compliant error responses for 404, 401, 403
• Metrics and logging capture referrers requests
• No regression in existing manifest/blob/tags endpoints

Risks and Mitigations

• Risk: Backend quay.io referrers API changes format
  • Mitigation: Pure pass-through means no parsing; format changes pass through transparently

• Risk: Performance impact from additional endpoint
  • Mitigation: Referrers requests are typically low-volume; monitor metrics after rollout

• Risk: Authorization complexity for referrer artifacts
  • Mitigation: Start with subject-image authorization only; if user can pull image, they can see referrers

Testing Strategy

• Unit tests: Test URL pattern matching, path parsing, namespace translation
• Handler tests: Mock backend responses, verify correct proxying behavior
• Integration tests: Test full middleware chain with real HTTP requests
• E2E tests: Verify referrers work through deployed proxy against quay.io staging

Rollout Strategy

• Feature is additive (new endpoint) - no feature flag needed
• Deploy to staging first, verify with test images that have referrers
• Monitor error rates and latency metrics
• Rollback: Remove route registration if issues arise

Documentation Needs

• Update registry-proxy API documentation to include referrers endpoint
• Note any limitations (pass-through only, no caching)
• Add troubleshooting guidance for referrers not working

Related Work

• Feature: PROJQUAY-10176
• Original RFE: RFE-8487
• Blocks: RHAIRFE-817 (Model signing for AI artifacts)
• Reference: OCI Image Spec v1.1 Referrers API specification