RHOAI Model catalog bridge

Author: pabel-rh

artifacts/attributes.adoc

@@ -65,6 +65,7 @@
 :rhdeveloper-name: Red Hat Developer
 :rhel: Red Hat Enterprise Linux
 :rhoai-brand-name: Red Hat OpenShift AI
+:rhoai-short: RHOAI
 :rhoserverless-brand-name: Red Hat OpenShift Serverless
 :rhsso-brand-name: Red Hat Single-Sign On
 :rhsso: RHSSO
@@ -168,3 +169,9 @@
 :upgrading-book-title: Upgrading {product}
 :using-dynamic-plugins-book-link: {product-docs-link}/html-single/installing_and_viewing_plugins_in_red_hat_developer_hub/index
 :using-dynamic-plugins-book-title: Using dynamic plugins
+
+:openshift-ai-connector-for-rhdh-link: {product-docs-link}/html-single/integrating_rhdh_with_openshift_ai_connector_for_rhdh/index
+:openshift-ai-connector-for-rhdh-title: Integrate {product} with {openshift-ai-connector-name} to leverage AI models
+
+:openshift-ai-connector-name: OpenShift AI Connector for {product}
+:openshift-ai-connector-name-short: OpenShift AI Connector for {product-very-short}

artifacts/snip-developer-preview.adoc renamed to artifacts/snip-developer-preview-lightspeed.adoc

@@ -0,0 +1,6 @@
+[IMPORTANT]
+====
+This section describes Developer Preview features in the {openshift-ai-connector-name} plugin. Developer Preview features are not supported by Red Hat in any way and are not functionally complete or production-ready. Do not use Developer Preview features for production or business-critical workloads. Developer Preview features provide early access to functionality in advance of possible inclusion in a Red Hat product offering. Customers can use these features to test functionality and provide feedback during the development process. Developer Preview features might not have any documentation, are subject to change or removal at any time, and have received limited testing. Red Hat might provide ways to submit feedback on Developer Preview features without an associated SLA.
+
+For more information about the support scope of Red Hat Developer Preview features, see https://access.redhat.com/support/offerings/devpreview/[Developer Preview Support Scope].
+====

artifacts/snip-developer-preview-rhoai.adoc

@@ -3,7 +3,7 @@
 [id="con-about-developer-lightspeed_{context}"]
 = About {ls-short}
 
-include::{docdir}/artifacts/snip-developer-preview.adoc[]
+include::{docdir}/artifacts/snip-developer-preview-lightspeed.adoc[]
 
 This early access program enables customers to share feedback on the user experience, features, capabilities, and any issues encountered. Your input helps ensure that {ls-short} better meets your needs when it is officially released and made generally available.
 

modules/developer-lightspeed/con-about-developer-lightspeed.adoc

@@ -0,0 +1,8 @@
+:_mod-docs-content-type: CONCEPT
+
+[id="con-understand-how-ai-assets-map-to-rhdh-catalog_{context}"]
+= Understand how AI assets map to the {product} Catalog
+
+include::{docdir}/artifacts/snip-developer-preview-rhoai.adoc[]
+
+The {openshift-ai-connector-name} ({openshift-ai-connector-name-short}) serves as a crucial link, enabling the discovery and accessibility of AI assets managed within the {rhoai-brand-name} offering directly within your {product-very-short} instance.

modules/openshift-ai-connector-for-rhdh/con-understand-how-ai-assets-map-to-rhdh-catalog.adoc

@@ -0,0 +1,27 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-populating-the-api-definition-tab_{context}"]
+= Populating the API Definition tab
+
+The AI platform engineer must follow these steps to provide this valuable information because {rhoai-short} does not expose the OpenAPI specification by default.
+
+.Procedure
+
+. Retrieve OpenAPI JSON: Use a tool like `curl` to fetch the specification directly from the running endpoint of the AI model server. The following command provides the precise endpoint (`/openapi.json`) and shows how to include a `Bearer` token if the model requires authentication for access.
++
+[source,bash]
+----
+curl -k -H "Authorization: Bearer $MODEL_API_KEY" https://$MODEL_ROOT_URL_INCLUDING_PORT/openapi.json | jq > open-api.json
+----
+
+. Set Property in {rhoai-short}.
+.. In the *{rhoai-short}* dashboard, go to *Model Registry* and select the appropriate *Model Version*.
++
+[NOTE]
+====
+We recommend using *Model Version* instead of *Registered Model* to maintain stability if the API changes between versions.
+====
+
+.. In the **Properties** section, set a key/value pair where the key is `API Spec` and the value is the entire JSON content from the `open-api.json` file.
+
+. Propagation: The {openshift-ai-connector-name} periodically polls the {rhoai-short} Model Registry, propagates this JSON, and renders the interactive API documentation in the {product-very-short} API Entity *Definition* tab.

modules/openshift-ai-connector-for-rhdh/proc-populating-the-api-definition-tab.adoc

@@ -0,0 +1,143 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-setting-up-openshift-ai-connector-for-rhdh-with-rhoai_{context}"]
+= Setting up {openshift-ai-connector-name} with {rhoai-brand-name}
+
+The installation of the {openshift-ai-connector-name} requires manual updates to {product-very-short}-related Kubernetes resources.
+
+.{rhoai-short} Prerequisites
+
+* To have Model Cards from the Model Catalog imported as Tech Docs, you must use {rhoai-short} version 2.25 or later, and the Model Catalog dashboard and a Model Registry need to be enabled (they are both off by default).
+* If you employed Model Catalog at earlier versions of {rhoai-short}, Tech Doc propagation does not work for any models you registered into the Model Registry while at those earlier versions; only models registered into Model Registry from a 2.25 (or later) Model Catalog have their Model Cards transferred to {product-very-short} as TechDocs.
+* For the rest of the features, version 2.20 or later suffices. Enabling Model Registry and its associated dashboard allows for a user experience that more directly allows for customizing AI Model metadata.
+
+//connect with Lindsey to update the above prereqs
+
+.Procedure
+
+. Configure {rhoai-short}-related RBAC and credentials.
+A Kubernetes `ServiceAccount` and a `service-account-token` Secret are required for the connector to retrieve data from {rhoai-short}. The following resources must be created, replacing namespace names (`ai-rhdh` for {product-very-short}, `rhoai-model-registries` for {rhoa``}) as needed:
+** `ServiceAccount` (`rhdh-rhoai-bridge`)
+** `ClusterRole` and `ClusterRoleBinding` (`rhdh-rhoai-bridge`) to allow access to OCP resources like `routes`, `services`, and `inferenceservices`.
+** `Role` and `RoleBinding` to allow ConfigMap updates within the {product-very-short} namespace.
+** `RoleBinding` in the {rhoai-short} namespace to grant the {product-very-short} `ServiceAccount` read permissions to the Model Registry data (binding to `registry-user-modelregistry-public`).
+** Secret (`rhdh-rhoai-bridge-token`) of type `kubernetes.io/service-account-token` that goes along with the `rhdh-rhoai-bridge` `ServiceAccount`.
+
+. Update your {product-very-short} dynamic plugin configuration.
+The {product-very-short} Pod requires two dynamic plugins. 
+.. In your {product-very-short} dynamic plugins ConfigMap, add the following code:
++
+[source,yaml]
+----
+plugins:
+  - disabled: false
+    package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-catalog-backend-module-model-catalog:bs_1.42.5__0.7.0!red-hat-developer-hub-backstage-plugin-catalog-backend-module-model-catalog
+  - disabled: false
+    package: oci://ghcr.io/redhat-developer/rhdh-plugin-export-overlays/red-hat-developer-hub-backstage-plugin-catalog-techdoc-url-reader-backend:bs_1.42.5__0.3.0!red-hat-developer-hub-backstage-plugin-catalog-techdoc-url-reader-backend
+----
+
+. Add Connector sidecar containers to the {product-very-short} Pod.
+The system relies on three sidecar containers (Model Catalog Bridge) running alongside the `backstage-backend` container. These sidecar containers must be added to your {product-very-short} deployment specification, referencing the `rhdh-rhoai-bridge-token` Secret:
+** `location`: Provides the REST API for RHDH plugins to fetch model metadata.
+** `storage-rest`: Maintains a cache of AI Model metadata in a ConfigMap called `bac-import-model`.
+** `rhoai-normalizer`: Acts as a Kubernetes controller and RHOAI client, normalizing RHOAI metadata for the connector. The following code block is an example:
++
+[source,yaml]
+----
+spec:
+  template:
+    spec:
+      containers:
+        - name: backstage-backend
+        - env:
+            - name: NORMALIZER_FORMAT
+              value: JsonArrayFormat
+            - name: POD_IP
+              valueFrom:
+                fieldRef:
+                  fieldPath: status.podIP
+            - name: POD_NAMESPACE
+              valueFrom:
+                fieldRef:
+                  fieldPath: metadata.namespace
+          envFrom:
+            - secretRef:
+                name: rhdh-rhoai-bridge-token
+          image: quay.io/redhat-ai-dev/model-catalog-location-service@sha256:4f6ab6624a29f627f9f861cfcd5d18177d46aa2c67a81a75a1502c49bc2ff012
+
+          imagePullPolicy: Always
+          name: location
+          ports:
+            - containerPort: 9090
+              name: location
+              protocol: TCP
+          volumeMounts:
+            - mountPath: /opt/app-root/src/dynamic-plugins-root
+              name: dynamic-plugins-root
+            workingDir: /opt/app-root/src
+          - env:
+            - name: NORMALIZER_FORMAT
+              value: JsonArrayFormat
+            - name: STORAGE_TYPE
+              value: ConfigMap
+            - name: BRIDGE_URL
+              value: http://localhost:9090
+            - name: POD_IP
+              valueFrom:
+                fieldRef:
+                  fieldPath: status.podIP
+            - name: POD_NAMESPACE
+              valueFrom:
+                fieldRef:
+                  fieldPath: metadata.namespace
+          envFrom:
+            - secretRef:
+                name: rhdh-rhoai-bridge-token
+          image: quay.io/redhat-ai-dev/model-catalog-storage-rest@sha256:398095e7469e86d84b1196371286363f4b7668aa3e26370b4d78cb8d4ace1dc9
+
+          imagePullPolicy: Always
+          name: storage-rest
+          volumeMounts:
+            - mountPath: /opt/app-root/src/dynamic-plugins-root
+              name: dynamic-plugins-root
+            workingDir: /opt/app-root/src
+          - env:
+            - name: NORMALIZER_FORMAT
+              value: JsonArrayFormat
+            - name: POD_IP
+              valueFrom:
+                fieldRef:
+                  fieldPath: status.podIP
+            - name: POD_NAMESPACE
+              valueFrom:
+                fieldRef:
+                  fieldPath: metadata.namespace
+          envFrom:
+            - secretRef:
+                name: rhdh-rhoai-bridge-token
+          image: quay.io/redhat-ai-dev/model-catalog-rhoai-normalizer@sha256:fe6c05d57495d6217c4d584940ec552c3727847ff60f39f5d04f94be024576d8
+
+          imagePullPolicy: Always
+          name: rhoai-normalizer
+          volumeMounts:
+            - mountPath: /opt/app-root/src/dynamic-plugins-root
+              name: dynamic-plugins-root
+            workingDir: /opt/app-root/src
+----
+
+. Enable `Connector` in your `{product-very-short}{my-app-config-file}` file.
+In your `{backstage} `app-config.extra.yaml` file, configure `Entity Provider` under the `catalog.providers` section:
++
+[source,yaml]
+----
+providers:
+  modelCatalog:
+    development:
+      baseUrl: http://localhost:9090
+----
+
+where:
+
+`modelCatalog`:: Specifies the name of the provider.
+`development`:: Defines future connector capability beyond a single `baseUrl`.
+`baseUrl`:: For Developer Preview, this value is the only one supported. Future releases might support external routes.

modules/openshift-ai-connector-for-rhdh/proc-setting-up-openshift-ai-connector-for-rhdh-with-rhoai.adoc

@@ -0,0 +1,67 @@
+:_mod-docs-content-type: PROCEDURE
+
+[id="proc-troubleshooting-connector-functionality_{context}"]
+= Troubleshooting Connector functionality
+
+The connector system consists of the two dynamic plugins and the three Model Catalog Bridge sidecar containers. Generally speaking, the logs collected should be provided to {company-name} Support for analysis.
+
+== Checking Dynamic Plugins status
+
+Validate that the dynamic plugins have been successfully installed into your {product-very-short} project Pod by using the following command:
++
+[source,bash]
+----
+oc logs -c install-dynamic-plugins deployment/<your RHDH deployment>
+----
+
+The `install-dynamic-plugin` logs allow you to check the following installation logs for successful logs:
+
+* `red-hat-developer-hub-backstage-plugin-catalog-backend-module-model-catalog` (Entity Provider)
+* `red-hat-developer-hub-backstage-plugin-catalog-techdoc-url-reader-backend` (TechDoc URL Reader)
+
+== Inspecting plugin logs
+
+View the {openshift-ai-connector-name}plugins in the `backstage-backend` container. Items to look for:
+
+[cols="3,4,4"]
+|===
+|Plugin Component |Logger Service Target |Common Log Text
+
+|Model Catalog Entity Provider
+|`ModelCatalogResourceEntityProvider`
+|`Discovering ResourceEntities from Model Server...`
+
+|Model Catalog TechDoc URL Reader
+|`ModelCatalogBridgeTechdocUrlReader`
+|`ModelCatalogBridgeTechdocUrlReader.readUrl`
+|===
+
+To enable debug logging, set the `LOG_LEVEL` environment variable to `debug` on the `backstage-backend` container. For more information, see {monitoring-and-logging-book-link}[{monitoring-and-logging-book-title}].
+
+== Inspecting the Model Catalog Bridge
+
+The Model Catalog Bridge sidecars manage the data fetching and storage:
+
+. Check Cached Data (ConfigMap): The processed AI Model metadata is stored in a `ConfigMap`.
++
+[source,bash]
+----
+oc get configmap bac-import-model -o json | jq -r '.binaryData | to_entries[] | "=== \(.key) ===\n" + (.value | @base64d | fromjson | .body | @base64d | fromjson | tostring)' | jq -R 'if startswith("=== ") then . else (. | fromjson) end'
+----
+
+. Check Location Service API: Confirm the location service is providing data to the {product-very-short} Entity Provider.
++
+[source,bash]
+----
+oc rsh -c backstage-backend deployment/<your RHDH deployment>
+curl http://localhost:9090/list
+----
+
+. Check Sidecar Container Logs:
++
+[source,bash]
+----
+oc logs -c rhoai-normalizer deployment/<your RHDH deployment>
+oc logs -c storage-rest deployment/<your RHDH deployment>
+oc logs -c location deployment/<your RHDH deployment>
+----

modules/openshift-ai-connector-for-rhdh/proc-troubleshooting-connector-functionality.adoc

@@ -0,0 +1,42 @@
+:_mod-docs-content-type: REFERENCE
+
+[id="ref-enrich-ai-model-metadata_{context}"]
+= Enrich AI model metadata for enhanced {product} experience
+
+While {rhoai-short} provides essential data, an AI platform engineer can enrich the {backstage} experience by adding custom properties to the `ModelVersion` or `RegisteredModel` (or annotations to the `KServe InferenceService` if the Model Registry is not used) so that the {openshift-ai-connector-name} can add the information to the {product-very-short} entities it creates.
+
+|===
+|Property Key |Entity Field Populated |Description
+
+|`API Spec`
+|API Definition Tab
+|The OpenAPI / Swagger JSON specification for the model REST API.
+
+|`API Type`
+|API Type
+|Correlates to supported {product-very-short}/{backstage} API types (defaults to `openapi`).
+
+|`TechDocs`
+|TechDocs
+|URL pointing to a Git repository that follows {product-very-short} TechDocs conventions for the Model Card.
+
+|`Homepage URL`
+|Links
+|A URL considered the home page for the model.
+
+|`Owner`
+|Owner
+|Overrides the default OpenShift user as the entity owner.
+
+|`Lifecycle`
+|Lifecycle
+|Serves a means to express the lifecycle notion of {product-very-short}/{backstage}.
+
+|`How to use`
+|Links
+|A URL that points to usage documentation.
+
+|`License`
+|Links
+|A URL to the license file of the model.
+|===

modules/openshift-ai-connector-for-rhdh/ref-enrich-ai-model-metadata.adoc

@@ -0,0 +1,34 @@
+:_mod-docs-content-type: REFERENCE
+
+[id="ref-model-to-entity-mapping_{context}"]
+= Model-to-Entity mapping
+
+This offering interfaces with the {openshift-ai-connector-name-short}, Model Catalog, and KServe-based Model Deployments (InferenceServices) to create familiar {backstage} entities.
+
+|===
+|{rhoai-short} Artifact |{product-very-short}/{backstage} Entity Kind |{product-very-short}/{backstage} Entity Type |Purpose
+
+|Model Server (InferenceService)
+|Component
+|`model-server`
+|Represents a running, accessible AI model endpoint. //Requires RHOAI 2.20 or later to obtain this mapping.
+
+|AI Model (Model Registry Version)
+|Resource
+|`ai-model`
+|Represents the specific AI model artifact (e.g., Llama-3-8B). Requires RHOAI 2.20 or later to obtain this mapping.
+
+|Model Server API Details
+|API
+|`openapi` (Default)
+|Provides the OpenAPI/Swagger specification for the model's REST endpoint. Requires RHOAI 2.20 or later to obtain this mapping.
+
+|Model Cards
+|TechDocs
+|N/A
+|Model Cards from the {rhoai-short} Model Catalog are associated with the Component and Resource entities. Requires RHOAI 2.25 to obtain this mapping.
+|===
+
+Once the {openshift-ai-connector-name-short} is installed and connected with {rhoai-short}, the transfer of information commences automatically.
+
+//To connect with Lindsey to update links here