fix: standardize CRDs (#520)

https://issues.redhat.com/browse/RHOAIENG-49788

## Description
**Context**
MaaS CRDs (MaaSModelRef, MaaSAuthPolicy, MaaSSubscription) have no
human-readable display metadata. The `GET /v1/models` API already has a
Details struct with `displayName`, `description`, and `genaiUseCase`
fields, and annotation constants already exist
(openshift.io/display-name, openshift.io/description,
opendatahub.io/genai-use-case), but `maasModelRefToModel()` never reads
annotations — so modelDetails is always `nil`.

**Approach**: mainly using Annotations
- [x] Use existing OpenShift-standard annotations for display
name/description on all 3 CRDs
- [x] Use opendatahub.io/* annotations for model-specific metadata
(contextWindow)
- [x] No CRD spec field changes — no regeneration needed
- [x] Enrich GET /v1/models API response with annotation data

## How Has This Been Tested?
Successfully ran the full test suite locally.

## 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

* **Documentation**
* Added a CRD Annotations Reference and updated configuration/flow
guides to document supported annotations (display name, description,
GenAI use case, context window) and their appearance in model listings;
added tier-based access guidance.

* **New Features**
* Model listing/response now surfaces annotation-driven metadata
(modelDetails: displayName, description, genaiUseCase, contextWindow).
  * Sample manifests and examples updated with annotation usage.

* **Tests**
  * Tests updated to validate annotation-driven model details.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Yuriy Teodorovych <Yuriy@ibm.com>

Author: yu-teo

docs/content/configuration-and-management/crd-annotations.md

@@ -0,0 +1,84 @@
+# CRD Annotations Reference
+
+This page documents the standard annotations supported on MaaS custom resources.
+
+## Common annotations (all CRDs)
+
+These annotations are supported on **MaaSModelRef**, **MaaSAuthPolicy**, and **MaaSSubscription**. They follow OpenShift conventions and are recognized by the OpenShift console, `kubectl`, and other tooling.
+
+| Annotation | Description | Example |
+| ---------- | ----------- | ------- |
+| `openshift.io/display-name` | Human-readable display name | `"Llama 2 7B Chat"` |
+| `openshift.io/description` | Free-text description of the resource | `"A general-purpose LLM for chat"` |
+
+## MaaSModelRef annotations
+
+In addition to the common annotations above, the MaaS API reads these annotations from **MaaSModelRef** and returns them in the `modelDetails` field of the `GET /v1/models` response.
+
+| Annotation | Description | Returned in API | Example |
+| ---------- | ----------- | --------------- | ------- |
+| `openshift.io/display-name` | Human-readable model name | `modelDetails.displayName` | `"Llama 2 7B Chat"` |
+| `openshift.io/description` | Model description | `modelDetails.description` | `"A large language model optimized for chat"` |
+| `opendatahub.io/genai-use-case` | GenAI use case category | `modelDetails.genaiUseCase` | `"chat"` |
+| `opendatahub.io/context-window` | Context window size | `modelDetails.contextWindow` | `"4096"` |
+
+### Example MaaSModelRef with annotations
+
+```yaml
+apiVersion: maas.opendatahub.io/v1alpha1
+kind: MaaSModelRef
+metadata:
+  name: llama-2-7b-chat
+  namespace: opendatahub
+  annotations:
+    openshift.io/display-name: "Llama 2 7B Chat"
+    openshift.io/description: "A large language model optimized for chat use cases"
+    opendatahub.io/genai-use-case: "chat"
+    opendatahub.io/context-window: "4096"
+spec:
+  modelRef:
+    kind: LLMInferenceService
+    name: llama-2-7b-chat
+```
+
+### API response
+
+When annotations are set, the `GET /v1/models` response includes a `modelDetails` object:
+
+```json
+{
+  "id": "llama-2-7b-chat",
+  "object": "model",
+  "created": 1672531200,
+  "owned_by": "opendatahub",
+  "ready": true,
+  "url": "https://...",
+  "modelDetails": {
+    "displayName": "Llama 2 7B Chat",
+    "description": "A large language model optimized for chat use cases",
+    "genaiUseCase": "chat",
+    "contextWindow": "4096"
+  }
+}
+```
+
+When no annotations are set (or all values are empty), `modelDetails` is omitted from the response.
+
+## MaaSAuthPolicy and MaaSSubscription annotations
+
+The common annotations (`openshift.io/display-name`, `openshift.io/description`) can be set on MaaSAuthPolicy and MaaSSubscription resources for use by `kubectl`, the OpenShift console, and other tooling. They are **not** returned in the `GET /v1/models` API response.
+
+### Example
+
+```yaml
+apiVersion: maas.opendatahub.io/v1alpha1
+kind: MaaSAuthPolicy
+metadata:
+  name: premium-access
+  namespace: models-as-a-service
+  annotations:
+    openshift.io/display-name: "Premium Access Policy"
+    openshift.io/description: "Grants premium-users group access to premium models"
+spec:
+  # ...
+```

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

@@ -84,7 +84,7 @@ To support a new backend type (a new **kind** in `spec.modelRef`):
      - **Option B:** Extend the API's access-validation logic to branch on **kind** and use a kind-specific probe (different URL path or client), while keeping the same contract: include a model only if the probe with the user's token succeeds.
 
 3. **Enrichment (optional)**
-   - Extra metadata (e.g. display name) can be set by the controller in status or annotations and mapped into the model response. For a new kind, add a small branch in the MaaSModelRef → API model conversion if needed.
+   - The API reads standard annotations from MaaSModelRef (`openshift.io/display-name`, `openshift.io/description`, `opendatahub.io/genai-use-case`, `opendatahub.io/context-window`) and returns them in the `modelDetails` field of the GET /v1/models response. See [CRD annotations](crd-annotations.md) for the full list. For a new kind, add a small branch in the MaaSModelRef → API model conversion if needed.
 
 4. **RBAC**
    - If the new kind’s reconciler or the API needs to read another resource, add the corresponding **list/watch** (and optionally **get**) permissions to the maas-api ClusterRole and/or the controller’s RBAC.

docs/content/configuration-and-management/model-listing-flow.md

@@ -25,7 +25,9 @@ When the [MaaS controller](https://github.com/opendatahub-io/models-as-a-service
 
 3. **Access validation**: The API probes each model’s `/v1/models` endpoint with the **exact Authorization header** the client sent (passed through as-is). Only models that return **2xx**, **3xx** or **405** are included in the response. This ensures the list only shows models the client is authorized to use.
 
-4. The filtered list is returned to the client.
+4. For each model, the API reads **annotations** from the MaaSModelRef to populate `modelDetails` in the response (display name, description, use case, context window). See [CRD annotations](crd-annotations.md) for the full list.
+
+5. The filtered list is returned to the client.
 
 ```mermaid
 sequenceDiagram
@@ -172,7 +174,12 @@ To have models appear via the **MaaSModelRef** flow:
         kind: MaaSModelRef
         metadata:
           name: my-model-name   # This becomes the model "id" in GET /v1/models
-          namespace: llm        # Same namespace as the LLMInferenceService
+          namespace: llm          # Same namespace as the LLMInferenceService
+          annotations:
+            openshift.io/display-name: "My Model"                  # optional: human-readable name
+            openshift.io/description: "A general-purpose LLM"      # optional: description
+            opendatahub.io/genai-use-case: "chat"                  # optional: use case
+            opendatahub.io/context-window: "4096"                  # optional: context window
         spec:
           modelRef:
             kind: LLMInferenceService

docs/content/configuration-and-management/model-setup.md

@@ -122,6 +122,77 @@ spec:
 
 ### Complete example
 
+Add the `alpha.maas.opendatahub.io/tiers` annotation to enable automatic RBAC setup for tier-based access:
+
+```yaml
+apiVersion: serving.kserve.io/v1alpha1
+kind: LLMInferenceService
+metadata:
+  name: my-production-model
+  namespace: llm
+  annotations:
+    alpha.maas.opendatahub.io/tiers: '[]'
+spec:
+  # ... rest of spec ...
+```
+
+**Annotation Values:**
+
+- **Empty list `[]`**: Grants access to **all tiers** (recommended for most models)
+- **List of tier names**: Grants access to specific tiers only
+  - Example: `'["premium","enterprise"]'` - only premium and enterprise tiers can access
+- **Missing annotation**: **No tiers** have access by default (model won't be accessible via MaaS)
+
+**Examples:**
+
+Allow all tiers:
+
+```yaml
+annotations:
+  alpha.maas.opendatahub.io/tiers: '[]'
+```
+
+Allow specific tiers:
+
+```yaml
+annotations:
+  alpha.maas.opendatahub.io/tiers: '["premium","enterprise"]'
+```
+
+### Step 3: Add Display Metadata (Optional)
+
+Add standard annotations to your **MaaSModelRef** to provide human-readable names and descriptions in the `GET /v1/models` API response:
+
+```yaml
+apiVersion: maas.opendatahub.io/v1alpha1
+kind: MaaSModelRef
+metadata:
+  name: my-production-model
+  namespace: llm
+  annotations:
+    openshift.io/display-name: "My Production Model"
+    openshift.io/description: "A fine-tuned model for production workloads"
+    opendatahub.io/genai-use-case: "chat"
+    opendatahub.io/context-window: "8192"
+spec:
+  modelRef:
+    kind: LLMInferenceService
+    name: my-production-model
+```
+
+These annotations are returned in the `modelDetails` field of the API response. All are optional. See [CRD annotations](crd-annotations.md) for the full list of supported annotations across all MaaS CRDs.
+
+### What the Annotation Does
+
+This annotation automatically creates the necessary RBAC resources (Roles and RoleBindings) that allow tier-specific service accounts to POST to your `LLMInferenceService`. The ODH Controller handles this automatically when the annotation is present.
+
+Behind the scenes, it creates:
+
+- **Role**: Grants `POST` permission on `llminferenceservices` resource
+- **RoleBinding**: Binds tier service account groups (e.g., `system:serviceaccounts:maas-default-gateway-tier-premium`) to the role
+
+### Complete Example
+
 Here's a complete example of an LLMInferenceService configured for MaaS:
 
 ```yaml

docs/samples/maas-system/free/maas/maas-auth-policy.yaml

@@ -3,6 +3,9 @@ kind: MaaSAuthPolicy
 metadata:
   name: simulator-access
   namespace: models-as-a-service
+  annotations:
+    openshift.io/display-name: "Simulator Access (Free)"
+    openshift.io/description: "Grants all authenticated users access to the free-tier simulator model"
 spec:
   modelRefs:
     - name: facebook-opt-125m-simulated

docs/samples/maas-system/free/maas/maas-model.yaml

@@ -3,6 +3,9 @@ kind: MaaSModelRef
 metadata:
   name: facebook-opt-125m-simulated
   namespace: llm
+  annotations:
+    openshift.io/display-name: "Facebook OPT 125M (Simulated)"
+    openshift.io/description: "A simulated OPT-125M model for free-tier testing"
 spec:
   modelRef:
     kind: LLMInferenceService

docs/samples/maas-system/free/maas/maas-subscription.yaml

@@ -3,6 +3,9 @@ kind: MaaSSubscription
 metadata:
   name: simulator-subscription
   namespace: models-as-a-service
+  annotations:
+    openshift.io/display-name: "Simulator Subscription (Free)"
+    openshift.io/description: "Free-tier subscription with 100 tokens/min rate limit"
 spec:
   owner:
     groups:

docs/samples/maas-system/premium/maas/maas-auth-policy.yaml

@@ -3,6 +3,9 @@ kind: MaaSAuthPolicy
 metadata:
   name: premium-simulator-access
   namespace: models-as-a-service
+  annotations:
+    openshift.io/display-name: "Premium Simulator Access"
+    openshift.io/description: "Grants premium-user group access to the premium simulator model"
 spec:
   modelRefs:
     - name: premium-simulated-simulated-premium

docs/samples/maas-system/premium/maas/maas-model.yaml

@@ -5,6 +5,9 @@ kind: MaaSModelRef
 metadata:
   name: premium-simulated-simulated-premium
   namespace: llm
+  annotations:
+    openshift.io/display-name: "Premium Simulator"
+    openshift.io/description: "A simulated model for premium-tier testing"
 spec:
   modelRef:
     kind: LLMInferenceService

docs/samples/maas-system/premium/maas/maas-subscription.yaml

@@ -3,6 +3,9 @@ kind: MaaSSubscription
 metadata:
   name: premium-simulator-subscription
   namespace: models-as-a-service
+  annotations:
+    openshift.io/display-name: "Premium Simulator Subscription"
+    openshift.io/description: "Premium-tier subscription with 1000 tokens/min rate limit"
 spec:
   owner:
     groups: