feat: require tokenRateLimits and remove tokenRateLimitRef for 3.4 (opendatahub-io#644)

## Summary

Related to - https://redhat.atlassian.net/browse/RHOAIENG-55976

This PR makes `tokenRateLimits` required on each `MaaSSubscription`
model reference and removes the unused `tokenRateLimitRef` field from
the CRD.

## Changes

### API Changes
- ✅ Removed `tokenRateLimitRef` field from `ModelSubscriptionRef`
- ✅ Made `tokenRateLimits` required with `MinItems=1` validation
- ✅ Regenerated CRD manifests and deepcopy code

### Tests
- ✅ Fixed 4 unit tests (added missing field indexes)
- ✅ All tests passing
- ✅ Live cluster validation complete

### Documentation
- ✅ Updated CRD reference docs
- ✅ Updated architecture overview
- ✅ Created migration guide:
`docs/content/migration/tokenratelimits-required-3.4.md`
- ✅ Added v3.4.0 release notes with breaking change notice

## Live Cluster Testing Results
(https://console-openshift-console.apps.ci-ln-hdzds3t-76ef8.aws-4.ci.openshift.org/)

Deployed custom controller and verified:
- ✅ Subscriptions **without** `tokenRateLimits` → **REJECTED** with
"Required value" error
- ✅ Subscriptions **with** `tokenRateLimits` → **ACCEPTED**
- ✅ Subscriptions with old `tokenRateLimitRef` → **REJECTED** with
"unknown field" error
- ✅ Controller reconciliation working correctly
- ✅ No RBAC errors

## Migration Impact

**Before (3.3 and earlier):**
```yaml
modelRefs:
  - name: my-model
    namespace: llm
    tokenRateLimits:  # Optional
      - limit: 1000
        window: 1m
    tokenRateLimitRef: "some-ref"  # Unused by controller
```

**After (3.4+):**
```yaml
modelRefs:
  - name: my-model
    namespace: llm
    tokenRateLimits:  # REQUIRED - at least one
      - limit: 1000
        window: 1m
    # tokenRateLimitRef removed
```

## Migration Guide

See detailed migration instructions in
`docs/content/migration/tokenratelimits-required-3.4.md`

Users must add inline `tokenRateLimits` to all `MaaSSubscription`
resources before upgrading to 3.4.

## Acceptance Criteria

All criteria from the user story met:

- [x] `tokenRateLimitRef` not present in API
- [x] Each `modelRefs` entry must include non-empty `tokenRateLimits`
- [x] Validation rejects non-compliant resources with clear messages
- [x] Tests cover required limits, no `tokenRateLimitRef` references
- [x] Generated CRD YAML matches types
- [x] Documentation updated
- [x] Migration guide provided
- [x] Breaking change documented in release notes

## Files Changed

- `maas-controller/api/maas/v1alpha1/maassubscription_types.go` - API
types
-
`deployment/base/maas-controller/crd/bases/maas.opendatahub.io_maassubscriptions.yaml`
- CRD manifest
- `maas-controller/api/maas/v1alpha1/zz_generated.deepcopy.go` -
Generated code
-
`maas-controller/pkg/controller/maas/maassubscription_controller_test.go`
- Test fixes
-
`docs/content/configuration-and-management/maas-controller-overview.md`
- Architecture docs
- `docs/content/reference/crds/maas-subscription.md` - CRD reference
- `docs/content/migration/tokenratelimits-required-3.4.md` - Migration
guide (new)
- `docs/content/release-notes/index.md` - Release notes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

## Release Notes

* **Breaking Changes**
* Rate limit configuration for each model subscription is now mandatory
and must be specified inline rather than referenced externally
  * At least one rate limit entry is required per model
  * Rate limit values must be greater than zero

* **Documentation**
* Updated configuration and CRD documentation to reflect new rate limit
requirements
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: somya-bhatnagar

deployment/base/maas-controller/crd/bases/maas.opendatahub.io_maassubscriptions.yaml

@@ -76,10 +76,6 @@ spec:
                       maxLength: 63
                       minLength: 1
                       type: string
-                    tokenRateLimitRef:
-                      description: TokenRateLimitRef references an existing TokenRateLimit
-                        resource
-                      type: string
                     tokenRateLimits:
                       description: TokenRateLimits defines token-based rate limits
                         for this model
@@ -89,6 +85,7 @@ spec:
                           limit:
                             description: Limit is the maximum number of tokens allowed
                             format: int64
+                            minimum: 1
                             type: integer
                           window:
                             description: Window is the time window (e.g., "1m", "1h",
@@ -99,10 +96,12 @@ spec:
                         - limit
                         - window
                         type: object
+                      minItems: 1
                       type: array
                   required:
                   - name
                   - namespace
+                  - tokenRateLimits
                   type: object
                 minItems: 1
                 type: array

docs/content/configuration-and-management/maas-controller-overview.md

@@ -192,7 +192,7 @@ erDiagram
 
 - **MaaSModelRef**: `spec.modelRef.kind` = LLMInferenceService or ExternalModel; `spec.modelRef.name` = name of the referenced model resource.
 - **MaaSAuthPolicy**: `spec.modelRefs` (list of ModelRef objects with name and namespace), `spec.subjects` (groups, users).
-- **MaaSSubscription**: `spec.owner` (groups, users), `spec.modelRefs` (list of ModelSubscriptionRef objects with name, namespace, and either `tokenRateLimits` array or `tokenRateLimitRef` reference to define per-model rate limits).
+- **MaaSSubscription**: `spec.owner` (groups, users), `spec.modelRefs` (list of ModelSubscriptionRef objects with name, namespace, and required `tokenRateLimits` array to define per-model rate limits).
 
 ---
 

docs/content/reference/crds/maas-subscription.md

@@ -24,8 +24,7 @@ Defines a subscription plan with per-model token rate limits. Creates Kuadrant T
 |-------|------|----------|-------------|
 | name | string | Yes | Name of the MaaSModelRef |
 | namespace | string | Yes | Namespace where the MaaSModelRef lives |
-| tokenRateLimits | []TokenRateLimit | No | Token-based rate limits for this model |
-| tokenRateLimitRef | string | No | Reference to an existing TokenRateLimit resource |
+| tokenRateLimits | []TokenRateLimit | Yes | Token-based rate limits for this model (at least one required) |
 | billingRate | BillingRate | No | Cost per token |
 
 ## TokenRateLimit

docs/content/release-notes/index.md

@@ -1,5 +1,15 @@
 # Release Notes
 
+## v3.4.0
+
+### Major Changes
+
+Version 3.4.0 introduces new CRDs and API resources that are not compatible with previous versions. All MaaS custom resources (`MaaSModelRef`, `MaaSAuthPolicy`, `MaaSSubscription`) are new in this release.
+
+**Migration:** See the overall migration plan for detailed upgrade instructions from previous versions.
+
+---
+
 ## v0.1.0
 
 *Initial release.*

maas-controller/api/maas/v1alpha1/maassubscription_types.go

@@ -64,12 +64,8 @@ type ModelSubscriptionRef struct {
 	Namespace string `json:"namespace"`
 
 	// TokenRateLimits defines token-based rate limits for this model
-	// +optional
-	TokenRateLimits []TokenRateLimit `json:"tokenRateLimits,omitempty"`
-
-	// TokenRateLimitRef references an existing TokenRateLimit resource
-	// +optional
-	TokenRateLimitRef *string `json:"tokenRateLimitRef,omitempty"`
+	// +kubebuilder:validation:MinItems=1
+	TokenRateLimits []TokenRateLimit `json:"tokenRateLimits"`
 
 	// BillingRate defines the cost per token
 	// +optional
@@ -79,6 +75,7 @@ type ModelSubscriptionRef struct {
 // TokenRateLimit defines a token rate limit
 type TokenRateLimit struct {
 	// Limit is the maximum number of tokens allowed
+	// +kubebuilder:validation:Minimum=1
 	Limit int64 `json:"limit"`
 
 	// Window is the time window (e.g., "1m", "1h", "24h")

maas-controller/api/maas/v1alpha1/zz_generated.deepcopy.go

@@ -397,6 +397,7 @@ func TestMaaSSubscriptionReconciler_RemoveModelRef(t *testing.T) {
 		WithRESTMapper(testRESTMapper()).
 		WithObjects(modelRefA, modelRefB, routeA, routeB, sub).
 		WithStatusSubresource(&maasv1alpha1.MaaSSubscription{}).
+		WithIndex(&maasv1alpha1.MaaSSubscription{}, "spec.modelRef", subscriptionModelRefIndexer).
 		Build()
 
 	r := &MaaSSubscriptionReconciler{Client: c, Scheme: scheme}
@@ -492,6 +493,7 @@ func TestMaaSSubscriptionReconciler_RemoveModelRef_Aggregation(t *testing.T) {
 		WithRESTMapper(testRESTMapper()).
 		WithObjects(modelRefA, modelRefB, routeA, routeB, sub1, sub2).
 		WithStatusSubresource(&maasv1alpha1.MaaSSubscription{}).
+		WithIndex(&maasv1alpha1.MaaSSubscription{}, "spec.modelRef", subscriptionModelRefIndexer).
 		Build()
 
 	r := &MaaSSubscriptionReconciler{Client: c, Scheme: scheme}
@@ -717,6 +719,7 @@ func TestMaaSSubscriptionReconciler_SimplifiedTRLP(t *testing.T) {
 		WithRESTMapper(testRESTMapper()).
 		WithObjects(model, route, maasSub).
 		WithStatusSubresource(&maasv1alpha1.MaaSSubscription{}).
+		WithIndex(&maasv1alpha1.MaaSSubscription{}, "spec.modelRef", subscriptionModelRefIndexer).
 		Build()
 
 	r := &MaaSSubscriptionReconciler{Client: c, Scheme: scheme}
@@ -810,6 +813,7 @@ func TestMaaSSubscriptionReconciler_MultipleSubscriptionsSimplified(t *testing.T
 		WithRESTMapper(testRESTMapper()).
 		WithObjects(model, route, subA, subB).
 		WithStatusSubresource(&maasv1alpha1.MaaSSubscription{}).
+		WithIndex(&maasv1alpha1.MaaSSubscription{}, "spec.modelRef", subscriptionModelRefIndexer).
 		Build()
 
 	r := &MaaSSubscriptionReconciler{Client: c, Scheme: scheme}