feat: refactor MaasModelRef into ExternalModel CRs (#586)

<!--- Provide a general summary of your changes in the Title above -->

## Description
Implements typed reference pattern for ModelReference to replace
inlining variant-specific config, enabling extensible model kinds
without schema changes to ModelReference.

## How Has This Been Tested?
- Unit tests: All existing unit tests pass, new ExternalModel handler
tests added
- E2E tests: Enhanced test_namespace_scoping.py to create ExternalModel
CRs inline using existing _apply_cr pattern
- Manual testing: ExternalModel CRD generation and controller
reconciliation verified

## Merge criteria:
<!--- This PR will be merged by any repository approver when it meets
all the points in the checklist -->
<!--- Go over all the following points, and put an `x` in all the boxes
that apply. -->

- [x] The commits are squashed in a cohesive manner and have meaningful
messages.
- [x] Testing instructions have been added in the PR body (for PRs
involving changes that are not immediately obvious).
- [x] The developer has manually tested the changes and verified that
the changes work


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

* **New Features**
* Introduced external model provider support, enabling configuration of
external models as an alternative backend alongside inference services.

* **Documentation**
* Added comprehensive guide for external model configuration, including
credential and endpoint management.
* Updated model reference documentation to clarify support for both
inference services and external models.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: ishitasequeira

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

@@ -0,0 +1,169 @@
+---
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  annotations:
+    controller-gen.kubebuilder.io/version: v0.16.4
+  name: externalmodels.maas.opendatahub.io
+spec:
+  group: maas.opendatahub.io
+  names:
+    kind: ExternalModel
+    listKind: ExternalModelList
+    plural: externalmodels
+    singular: externalmodel
+  scope: Namespaced
+  versions:
+  - additionalPrinterColumns:
+    - jsonPath: .spec.provider
+      name: Provider
+      type: string
+    - jsonPath: .spec.endpoint
+      name: Endpoint
+      type: string
+    - jsonPath: .status.phase
+      name: Phase
+      type: string
+    - jsonPath: .metadata.creationTimestamp
+      name: Age
+      type: date
+    name: v1alpha1
+    schema:
+      openAPIV3Schema:
+        description: |-
+          ExternalModel is the Schema for the externalmodels API.
+          It defines an external LLM provider (e.g., OpenAI, Anthropic) that can be
+          referenced by MaaSModelRef resources.
+        properties:
+          apiVersion:
+            description: |-
+              APIVersion defines the versioned schema of this representation of an object.
+              Servers should convert recognized schemas to the latest internal value, and
+              may reject unrecognized values.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources
+            type: string
+          kind:
+            description: |-
+              Kind is a string value representing the REST resource this object represents.
+              Servers may infer this from the endpoint the client submits requests to.
+              Cannot be updated.
+              In CamelCase.
+              More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds
+            type: string
+          metadata:
+            type: object
+          spec:
+            description: ExternalModelSpec defines the desired state of ExternalModel
+            properties:
+              credentialRef:
+                description: |-
+                  CredentialRef references a Kubernetes Secret containing the provider API key.
+                  The Secret must contain a data key "api-key" with the credential value.
+                properties:
+                  name:
+                    description: Name is the name of the Secret
+                    maxLength: 253
+                    minLength: 1
+                    type: string
+                  namespace:
+                    description: Namespace is the namespace of the Secret. Defaults
+                      to the ExternalModel namespace if omitted.
+                    maxLength: 253
+                    type: string
+                required:
+                - name
+                type: object
+              endpoint:
+                description: |-
+                  Endpoint is the FQDN of the external provider (no scheme or path).
+                  e.g. "api.openai.com".
+                  This field is metadata for downstream consumers (e.g. BBR provider-resolver plugin)
+                  and is not used by the controller for endpoint derivation.
+                maxLength: 253
+                pattern: ^[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?)*$
+                type: string
+              provider:
+                description: |-
+                  Provider identifies the API format and auth type for the external model.
+                  e.g. "openai", "anthropic".
+                maxLength: 63
+                type: string
+            required:
+            - credentialRef
+            - endpoint
+            - provider
+            type: object
+          status:
+            description: ExternalModelStatus defines the observed state of ExternalModel
+            properties:
+              conditions:
+                description: Conditions represent the latest available observations
+                  of the external model's state
+                items:
+                  description: Condition contains details for one aspect of the current
+                    state of this API Resource.
+                  properties:
+                    lastTransitionTime:
+                      description: |-
+                        lastTransitionTime is the last time the condition transitioned from one status to another.
+                        This should be when the underlying condition changed.  If that is not known, then using the time when the API field changed is acceptable.
+                      format: date-time
+                      type: string
+                    message:
+                      description: |-
+                        message is a human readable message indicating details about the transition.
+                        This may be an empty string.
+                      maxLength: 32768
+                      type: string
+                    observedGeneration:
+                      description: |-
+                        observedGeneration represents the .metadata.generation that the condition was set based upon.
+                        For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date
+                        with respect to the current state of the instance.
+                      format: int64
+                      minimum: 0
+                      type: integer
+                    reason:
+                      description: |-
+                        reason contains a programmatic identifier indicating the reason for the condition's last transition.
+                        Producers of specific condition types may define expected values and meanings for this field,
+                        and whether the values are considered a guaranteed API.
+                        The value should be a CamelCase string.
+                        This field may not be empty.
+                      maxLength: 1024
+                      minLength: 1
+                      pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$
+                      type: string
+                    status:
+                      description: status of the condition, one of True, False, Unknown.
+                      enum:
+                      - "True"
+                      - "False"
+                      - Unknown
+                      type: string
+                    type:
+                      description: type of condition in CamelCase or in foo.example.com/CamelCase.
+                      maxLength: 316
+                      pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$
+                      type: string
+                  required:
+                  - lastTransitionTime
+                  - message
+                  - reason
+                  - status
+                  - type
+                  type: object
+                type: array
+              phase:
+                description: Phase represents the current phase of the external model
+                enum:
+                - Pending
+                - Ready
+                - Failed
+                type: string
+            type: object
+        type: object
+    served: true
+    storage: true
+    subresources:
+      status: {}

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

@@ -55,25 +55,6 @@ spec:
           spec:
             description: MaaSModelSpec defines the desired state of MaaSModelRef
             properties:
-              credentialRef:
-                description: |-
-                  CredentialRef references a Kubernetes Secret containing the provider API key.
-                  The Secret must contain a data key "api-key" with the credential value.
-                  Only used when modelRef.kind=ExternalModel.
-                properties:
-                  name:
-                    description: Name is the name of the Secret
-                    maxLength: 253
-                    minLength: 1
-                    type: string
-                  namespace:
-                    description: Namespace is the namespace of the Secret. Defaults
-                      to the MaaSModelRef namespace if omitted.
-                    maxLength: 253
-                    type: string
-                required:
-                - name
-                type: object
               endpointOverride:
                 description: |-
                   EndpointOverride, when set, overrides the endpoint URL that the controller
@@ -83,39 +64,26 @@ spec:
               modelRef:
                 description: ModelRef references the actual model endpoint
                 properties:
-                  endpoint:
-                    description: |-
-                      Endpoint is the FQDN of the external provider (no scheme or path).
-                      e.g. "api.openai.com". Only used when kind=ExternalModel.
-                      This field is metadata for downstream consumers (e.g. BBR provider-resolver plugin)
-                      and is not used by the controller for endpoint derivation. Use spec.endpointOverride
-                      to override the controller-derived endpoint.
-                    maxLength: 253
-                    pattern: ^[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9\-]*[a-zA-Z0-9])?)*$
-                    type: string
                   kind:
-                    description: Kind determines which fields are available
+                    description: |-
+                      Kind determines which backend handles this model reference.
+                      LLMInferenceService: references a KServe LLMInferenceService.
+                      ExternalModel: references an ExternalModel CR containing provider config.
                     enum:
                     - LLMInferenceService
                     - ExternalModel
                     type: string
                   name:
-                    description: Name is the name of the model resource
-                    type: string
-                  provider:
                     description: |-
-                      Provider identifies the API format and auth type for external models.
-                      e.g. "openai", "anthropic". Only used when kind=ExternalModel.
-                    maxLength: 63
+                      Name is the name of the model resource.
+                      For LLMInferenceService, this is the InferenceService name.
+                      For ExternalModel, this is the ExternalModel CR name.
+                    maxLength: 253
                     type: string
                 required:
                 - kind
                 - name
                 type: object
-                x-kubernetes-validations:
-                - message: provider is required when kind is ExternalModel
-                  rule: self.kind != 'ExternalModel' || has(self.provider) && self.provider
-                    != ''
             required:
             - modelRef
             type: object

deployment/base/maas-controller/crd/kustomization.yaml

@@ -1,5 +1,6 @@
 # This kustomization.yaml is used for CRD generation.
 resources:
+  - bases/maas.opendatahub.io_externalmodels.yaml
   - bases/maas.opendatahub.io_maasauthpolicies.yaml
   - bases/maas.opendatahub.io_maasmodelrefs.yaml
   - bases/maas.opendatahub.io_maassubscriptions.yaml

deployment/base/maas-controller/rbac/clusterrole.yaml

@@ -4,13 +4,13 @@ metadata:
   name: maas-controller-role
 rules:
 - apiGroups: ["maas.opendatahub.io"]
-  resources: ["maasauthpolicies", "maasmodelrefs", "maassubscriptions"]
+  resources: ["externalmodels", "maasauthpolicies", "maasmodelrefs", "maassubscriptions"]
   verbs: ["create", "delete", "get", "list", "patch", "update", "watch"]
 - apiGroups: ["maas.opendatahub.io"]
-  resources: ["maasauthpolicies/finalizers", "maasmodelrefs/finalizers", "maassubscriptions/finalizers"]
+  resources: ["externalmodels/finalizers", "maasauthpolicies/finalizers", "maasmodelrefs/finalizers", "maassubscriptions/finalizers"]
   verbs: ["update"]
 - apiGroups: ["maas.opendatahub.io"]
-  resources: ["maasauthpolicies/status", "maasmodelrefs/status", "maassubscriptions/status"]
+  resources: ["externalmodels/status", "maasauthpolicies/status", "maasmodelrefs/status", "maassubscriptions/status"]
   verbs: ["get", "patch", "update"]
 - apiGroups: ["gateway.networking.k8s.io"]
   resources: ["gateways"]

docs/content/configuration-and-management/maas-model-kinds.md

@@ -1,4 +1,4 @@
-# MaaSModelRef kinds (future)
+# MaaSModelRef Kinds
 
 The MaaS API lists models from **MaaSModelRef** CRs only. Each MaaSModelRef defines a **backend reference** (`spec.modelRef`) that identifies the type and location of the model endpoint—similar in spirit to how [Gateway API's BackendRef](https://gateway-api.sigs.k8s.io/reference/spec/#backendref) defines how a Route forwards requests to a Kubernetes resource (group, kind, name, namespace).
 
@@ -41,11 +41,31 @@ spec:
 
 The controller still validates the backend (HTTPRoute exists, LLMInferenceService is ready, etc.) — the override only affects the final endpoint URL written to `status.endpoint`. When the field is empty or omitted, the controller uses its normal discovery logic.
 
-## Current behavior
+## Supported Kinds
 
-- **Supported kind today:** `LLMInferenceService` (also accepts the alias `llmisvc` for backwards compatibility). The MaaS controller reconciles MaaSModelRefs whose **modelRef** points to an LLMInferenceService (by name and optional namespace). It sets `status.endpoint` from the LLMInferenceService status and `status.phase` from its readiness.
-- **API behavior:** The API reads MaaSModelRefs from the informer cache, maps each to an API model (`id`, `url`, `ready`, `kind`, etc.), then **validates access** by probing each model's `/v1/models` endpoint with the request's **Authorization header** (passed through as-is). Only models that return 2xx or 405 are included.
-- **Kind on the wire:** Each model in the GET /v1/models response can carry a `kind` field (e.g. `LLMInferenceService`) from `spec.modelRef.kind` for clients or tooling.
+### LLMInferenceService
+
+The `LLMInferenceService` kind (also accepts the alias `llmisvc` for backwards compatibility) references models deployed on the cluster via the LLMInferenceService CRD. The controller:
+- Sets `status.endpoint` from the LLMInferenceService status
+- Sets `status.phase` from LLMInferenceService readiness
+
+### ExternalModel
+
+The `ExternalModel` kind references external AI/ML providers (e.g., OpenAI, Anthropic, Azure OpenAI). When using this kind:
+1. Create an [ExternalModel](../reference/crds/external-model.md) CR with provider, endpoint, and credential reference
+2. Create a MaaSModelRef that references the ExternalModel by name
+
+The controller:
+- Fetches the ExternalModel CR from the same namespace
+- Validates the user-supplied HTTPRoute references the correct gateway
+- Derives `status.endpoint` from HTTPRoute hostnames or gateway addresses
+- Sets `status.phase` based on HTTPRoute acceptance by the gateway
+
+## API Behavior
+
+- The API reads MaaSModelRefs from the informer cache, maps each to an API model (`id`, `url`, `ready`, `kind`, etc.)
+- **Access validation**: Probes each model's `/v1/models` endpoint with the request's Authorization header. Only models that return 2xx or 405 are included.
+- **Kind on the wire**: Each model in the GET /v1/models response carries a `kind` field from `spec.modelRef.kind`
 
 ## Adding a new kind in the future
 

docs/content/reference/crds/external-model.md

@@ -0,0 +1,69 @@
+# ExternalModel
+
+Defines an external AI/ML model hosted outside the cluster (e.g., OpenAI, Anthropic, Azure OpenAI). The ExternalModel CRD contains provider details, endpoint URL, and credential references that were previously inlined in MaaSModelRef.
+
+## ExternalModelSpec
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| provider | string | Yes | Provider identifier (e.g., `openai`, `anthropic`, `azure`). Max length: 63 characters. |
+| endpoint | string | Yes | FQDN of the external provider (no scheme or path), e.g., `api.openai.com`. This is metadata for downstream consumers. Max length: 253 characters. |
+| credentialRef | CredentialReference | Yes | Reference to the Secret containing API credentials. Must exist in the same namespace as the ExternalModel. |
+
+## CredentialReference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | Name of the Secret containing the credentials. Max length: 253 characters. |
+| namespace | string | No | Namespace of the Secret. Defaults to the ExternalModel's namespace if not specified. |
+
+## ExternalModelStatus
+
+| Field | Type | Description |
+|-------|------|-------------|
+| phase | string | One of: `Pending`, `Ready`, `Failed` |
+| conditions | []Condition | Latest observations of the external model's state |
+
+## Example
+
+```yaml
+apiVersion: maas.opendatahub.io/v1alpha1
+kind: ExternalModel
+metadata:
+  name: gpt4
+  namespace: models
+spec:
+  provider: openai
+  endpoint: api.openai.com
+  credentialRef:
+    name: openai-credentials
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: openai-credentials
+  namespace: models
+type: Opaque
+stringData:
+  api-key: "sk-..."
+---
+# MaaSModelRef referencing the ExternalModel
+apiVersion: maas.opendatahub.io/v1alpha1
+kind: MaaSModelRef
+metadata:
+  name: gpt4-model
+  namespace: models
+spec:
+  modelRef:
+    kind: ExternalModel
+    name: gpt4
+```
+
+## Relationship with MaaSModelRef
+
+ExternalModel is a dedicated CRD for external model configuration. MaaSModelRef references ExternalModel by name using `spec.modelRef.kind: ExternalModel` and `spec.modelRef.name: <external-model-name>`.
+
+This separation allows:
+- **Reusability**: One ExternalModel can be referenced by multiple MaaSModelRefs
+- **Clean separation**: Provider-specific configuration lives in ExternalModel; MaaSModelRef handles listing and access control
+- **Extensibility**: Adding new external providers requires no MaaSModelRef schema changes

docs/content/reference/crds/maas-model-ref.md

@@ -13,7 +13,9 @@ Identifies an AI/ML model on the cluster. The MaaS API lists models from MaaSMod
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | kind | string | Yes | One of: `LLMInferenceService`, `ExternalModel` |
-| name | string | Yes | Name of the model resource (e.g. LLMInferenceService name). Must be in the same namespace as the MaaSModelRef. |
+| name | string | Yes | Name of the model resource (e.g. LLMInferenceService name, ExternalModel name). Must be in the same namespace as the MaaSModelRef. Max length: 253 characters. |
+
+For `kind: ExternalModel`, the MaaSModelRef references an [ExternalModel](external-model.md) CR that contains the provider configuration.
 
 ## MaaSModelRefStatus
 

docs/mkdocs.yml

@@ -89,6 +89,7 @@ nav:
     - MaaS API (Swagger): reference/api-reference.md
     - MaaS CRDs:
       - MaaSModelRef: reference/crds/maas-model-ref.md
+      - ExternalModel: reference/crds/external-model.md
       - MaaSAuthPolicy: reference/crds/maas-auth-policy.md
       - MaaSSubscription: reference/crds/maas-subscription.md