docs: proposal for MCPBackend CRD

[aishwaryaraimule21]

Description

This proposal introduces a standalone MCPBackend CRD to replace the inline backend configuration currently embedded in MCPRoute.spec.backendRefs[]. The inline model hits Kubernetes object size limits as backends scale, and becomes untenable with the addition of token exchange (RFC-8693) which adds ~25 lines of nested config per backend and conflation of concerns.

The proposal evaluates multiple design approaches — inline security policy, separate security policy with Policy Attachment, backend-refs-policy, and route-refs-policy — analyzing each for reconciliation complexity, use case coverage, backward compatibility, and consistency with the LLM-side AIServiceBackend + BackendSecurityPolicy pattern.

The recommended approach is MCPBackend CRD + extending the existing BackendSecurityPolicy with Policy Attachment (targetRefs), combined with explicit Name/Group/Kind fields on MCPRouteBackendRef for backward compatibility. The existing securityPolicy field is reused with mode-dependent semantics (full definition in legacy mode, per-route scope override in MCPBackend mode).

Related Issues/PRs (if applicable)

Special notes for reviewers (if applicable)

This is a design proposal document only — no implementation code is included.
Key decision points for review:

1. Whether to define security policy inline in MCPBackend CRD or as a
   separate CRD — Approach 1 (inline) is simpler but couples backend and
   security lifecycles. Approach 2 (separate) decouples them at the cost of
   additional reconciliation hops (Section 4).

2. How to associate MCPBackend with BackendSecurityPolicy — Policy
   Attachment (BSP targets MCPBackend via targetRefs), backend-refs-policy
   (MCPBackend points to BSP), or route-refs-policy (MCPRoute points to BSP
   per backend). Each has different reconciliation and reuse tradeoffs
   (Section 4.2).

3. Whether to reuse the existing BackendSecurityPolicy CRD or create a new
   MCPBackendSecurityPolicy CRD — Extending the existing CRD unifies the
   model but grows the discriminated union; a new CRD avoids bloat but adds
   CRD proliferation (Section 5).

4. Backward compatibility of MCPRouteBackendRef — Keep the inline
   BackendObjectReference embedding (minimal Go change, dangling fields) or
   switch to explicit Name/Group/Kind fields following the
   AIGatewayRouteRuleBackendRef pattern (cleaner but requires controller
   updates). Both preserve the JSON wire format (Section 6).

[Hritik003]

we would also need a field index for MCPBackend ---> BSP. Because there's no kind discrimination in the index. If an AIServiceBackend and an MCPBackend happen to have the same name in the same namespace, the index would return BSPs targeting both kinds.

ref :

ai-gateway/internal/controller/controller.go

Line 306 in 7a303f9

k8sClientIndexAIServiceBackendToTargetingBackendSecurityPolicy = "AIServiceBackendToTargetingBackendSecurityPolicy"

[nacx]

Thanks for the detailed and thought-through proposal. Thanks for showcasing different options!
It LGTM and I agree with the proposed recommendations.

[nacx]

Mind addressing the formatting issues so we can merge this? (You can run make precommit locally).

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.30%. Comparing base (3509761) to head (497a664).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #2144      +/-   ##
==========================================
- Coverage   84.33%   84.30%   -0.03%     
==========================================
  Files         134      134              
  Lines       19352    19313      -39     
==========================================
- Hits        16320    16282      -38     
+ Misses       2033     2032       -1     
  Partials      999      999              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.