OLS-3171: Google vertex AI documentation

configure/ols-configuring-integrating-google-vertex-ai.adoc

@@ -0,0 +1,16 @@
+:_content-type: ASSEMBLY
+[id="ols-configuring-integrating-google-vertex-ai"]
+= Integrating Google Vertex AI with {ols-long}
+include::_attributes/common-attributes.adoc[]
+:context: ols-configuring-integrating-google-vertex-ai
+
+toc::[]
+
+[role="_abstract"]
+As an administrator, you can integrate Google Vertex AI as a large language model (LLM) provider for {ols-long}.
+
+include::../modules/ols-configuring-ref-google-vertex-ai-provider-types.adoc[leveloffset=+1]
+
+include::../modules/ols-configuring-proc-configuring-google-vertex-ai.adoc[leveloffset=+1]
+
+include::../modules/ols-configuring-ref-olsconfig-google-vertex-fields.adoc[leveloffset=+1]

modules/ols-1-1-release-notes.adoc

@@ -37,3 +37,7 @@
 //OLS-1188
 
 * With this update, you can attach Prometheus alerting rules and `Alertmanager` silences to a prompt directly from their details pages. 
+
+//OLS-3171
+
+* With this update, {ols-long} supports Google Vertex AI as an LLM provider. You can configure Google-native models, such as Gemini, by using the `google_vertex` provider type. You can also configure Anthropic models, such as Claude hosted on Vertex AI, by using the `google_vertex_anthropic` provider type. Both provider types authenticate by using a Google Cloud Platform (GCP) service account JSON key stored within a {k8s} Secret.

modules/ols-configuring-proc-configuring-google-vertex-ai.adoc

@@ -0,0 +1,104 @@
+// Module included in the following assemblies:
+// * lightspeed-docs-main/configure/ols-configuring-openshift-lightspeed.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ols-configuring-proc-configuring-google-vertex-ai_{context}"]
+= Configuring Google Vertex AI
+
+[role="_abstract"]
+To use Google Vertex AI, create a credentials secret and apply an `OLSConfig` custom resource (CR).
+
+.Prerequisites
+
+* The {ols-long} Operator must be installed.
+* You must possess a valid GCP service account JSON key file.
+* The Vertex AI API must be enabled in your Google Cloud project.
+* Your GCP service account must have appropriate Vertex AI permissions.
+
+.Procedure
+
+. Create the credentials Secret in the operator namespace by running the following command:
++
+[source,bash]
+----
+oc create secret generic llmcreds \
+  --from-file=gcp-service-account.json=/path/to/service-account-key.json \
+  -n openshift-lightspeed
+----
++
+[NOTE] 
+====
+The Operator looks for a key named `apitoken` by default if you omit the `credentialKey` field later.
+====
+. Create an `OLSConfig` CR file named `olsconfig.yaml` using one of the following examples:
+
+* Example configuration for Gemini (`google_vertex`):
++
+[source,yaml]
+----
+apiVersion: ols.openshift.io/v1alpha1
+kind: OLSConfig
+metadata:
+  name: cluster
+spec:
+  llm:
+    providers:
+      - name: google
+        type: google_vertex
+        credentialsSecretRef:
+          name: llmcreds
+        credentialKey: gcp-service-account.json
+        googleVertexConfig:
+          projectID: my-gcp-project-123
+          location: us-central1
+        models:
+          - name: gemini-2.5-flash-lite
+  ols:
+    defaultModel: gemini-2.5-flash-lite
+    defaultProvider: google
+----
+
+* Example configuration for Claude (`google_vertex_anthropic`):
++
+[source,yaml]
+----
+apiVersion: ols.openshift.io/v1alpha1
+kind: OLSConfig
+metadata:
+  name: cluster
+spec:
+  llm:
+    providers:
+      - name: google-anthropic
+        type: google_vertex_anthropic
+        credentialsSecretRef:
+          name: llmcreds
+        credentialKey: gcp-service-account.json
+        googleVertexAnthropicConfig:
+          projectID: my-gcp-project-123
+          location: us-east4
+        models:
+          - name: claude-3-sonnet
+  ols:
+    defaultModel: claude-3-sonnet
+    defaultProvider: google-anthropic
+----
+
+. Apply the configuration file to your cluster:
++
+[source,bash]
+----
+oc apply -f olsconfig.yaml
+----
+
+.Verification
+
+. Verify that the Operator has completed reconciliation:
++
+[source,bash]
+----
+oc get olsconfig cluster -o jsonpath='{.status.overallStatus}'
+----
++
+Expected output: `Ready`
+

modules/ols-configuring-ref-google-vertex-ai-provider-types.adoc

@@ -0,0 +1,25 @@
+// Module included in the following assemblies:
+// * lightspeed-docs-main/configure/ols-configuring-openshift-lightspeed.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="ols-configuring-ref-google-vertex-ai-provider-types_{context}"]
+= Google Vertex AI provider types
+
+[role="_abstract"]
+{ols-long} supports Google Vertex AI as an LLM provider. You can deploy Google-native models or Anthropic models hosted on the Google Cloud Platform (GCP) infrastructure.
+
+Both provider types authenticate using a GCP service account JSON key stored within a {k8s} Secret.
+
+.Supported provider types
+[cols="1,1,1", options="header"]
+|===
+| Provider type | Use case | Required configuration field
+
+| `google_vertex`
+| Google-native models like Gemini.
+| `googleVertexConfig`
+
+| `google_vertex_anthropic`
+| Anthropic models like Claude hosted on Vertex AI.
+| `googleVertexAnthropicConfig`
+|===

modules/ols-configuring-ref-olsconfig-google-vertex-fields.adoc

@@ -0,0 +1,109 @@
+// Module included in the following assemblies:
+// * lightspeed-docs-main/configure/ols-configuring-openshift-lightspeed.adoc
+
+:_mod-docs-content-type: REFERENCE
+[id="ols-configuring-ref-olsconfig-google-vertex-fields_{context}"]
+= OLSConfig field reference for Google Vertex AI
+
+[role="_abstract"]
+The following reference tables describe the configuration schema for Google Vertex AI providers.
+
+.Provider fields (`spec.llm.providers[]`)
+[cols="2,1,1,4", options="header"]
+|===
+| Field | Type | Required | Description
+
+| `name`
+| `string`
+| Yes
+| Logical name for the provider. Referenced by `spec.ols.defaultProvider`.
+
+| `type`
+| `string`
+| Yes
+| Must be set to `google_vertex` or `google_vertex_anthropic`.
+
+| `credentialsSecretRef.name`
+| `string`
+| Yes
+| Name of the Secret in the operator namespace that contains provider credentials.
+
+| `credentialKey`
+| `string`
+| No
+| Key name inside the Secret to read. Defaults to `apitoken`.
+
+| `url`
+| `string`
+| No
+| The provider API endpoint URL. This field is typically not required for Vertex AI.
+
+| `models`
+| `array`
+| Yes
+| List of models available from the provider.
+|===
+
+.Google Vertex configuration (`spec.llm.providers[].googleVertexConfig`)
+[cols="2,1,1,4", options="header"]
+|===
+| Field | Type | Required | Description
+
+| `projectID`
+| `string`
+| Yes
+| The Google Cloud project ID (for example, `my-gcp-project-123`).
+
+| `location`
+| `string`
+| Yes
+| The target GCP region for Vertex AI (for example, `us-central1`).
+|===
+
+.Google Vertex Anthropic configuration (`spec.llm.providers[].googleVertexAnthropicConfig`)
+[cols="2,1,1,4", options="header"]
+|===
+| Field | Type | Required | Description
+
+| `projectID`
+| `string`
+| Yes
+| The Google Cloud project ID.
+
+| `location`
+| `string`
+| Yes
+| The target GCP region for Vertex AI (for example, `us-east4`).
+|===
+
+.Model fields (`spec.llm.providers[].models[]`)
+[cols="2,1,1,4", options="header"]
+|===
+| Field | Type | Required | Description
+
+| `name`
+| `string`
+| Yes
+| Model name (such as `gemini-2.5-flash-lite`). Referenced by `spec.ols.defaultModel`.
+
+| `url`
+| `string`
+| No
+| The model-specific API endpoint URL.
+
+| `contextWindowSize`
+| `integer`
+| No
+| Context window size in tokens. Minimum value: 1024.
+
+| `parameters.maxTokensForResponse`
+| `integer`
+| No
+| Maximum tokens allowed for responses. Default value: 2048.
+
+| `parameters.toolBudgetRatio`
+| `float`
+| No
+| Ratio of the context window allocated for the tool token budget. Range: 0.1 to 0.5. Default value: 0.5.
+|===
+

modules/ols-proc-google-vertex-ai-configuration-resource-is-rejected.adoc

@@ -0,0 +1,16 @@
+// Module included in the following assemblies:
+// lightspeed-docs-main/troubleshoot/ols-troubleshooting-openshift-lightspeed.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ols-proc-google-vertex-ai-configuration-resource-is-rejected_{context}"]
+= Google Vertex AI configuration resource is rejected
+
+[role="_abstract"]
+Review common validation errors if the `OLSConfig` custom resource (CR) is rejected during deployment:
+
+* Error: `googleVertexConfig is required for google_vertex provider`
+** Resolution: You must provide the `googleVertexConfig` object containing both `projectID` and `location` when using `type: google_vertex`.
+* Error: `googleVertexConfig may only be set when type is google_vertex`
+** Resolution: Remove `googleVertexConfig`. For the `google_vertex_anthropic` type, you must use `googleVertexAnthropicConfig` instead.
+* Error: `credentialKey must not be empty or whitespace`
+** Resolution: Provide a valid key name string, or omit the field entirely to default to `apitoken`.

modules/ols-proc-resolving-issues-with-conversation-history copy.adoc

@@ -0,0 +1,13 @@
+// Module included in the following assemblies:
+// lightspeed-docs-main/troubleshoot/ols-troubleshooting-openshift-lightspeed.adoc
+
+:_mod-docs-content-type: PROCEDURE
+[id="ols-proc-resolving-issues-with-conversation-history_{context}"]
+= Resolving issues with conversation history
+
+[role="_abstract"]
+To maintain conversation history, optimize the balance between the context window and response tokens. This prevents earlier dialogue from being truncated when the model reaches its context limit.
+
+.Procedure
+. Verify the context window is correctly set for your specific model and provider.
+. Lower the max response tokens value to increase the remaining space available for conversation history.

troubleshoot/ols-troubleshooting-openshift-lightspeed.adoc

@@ -25,3 +25,4 @@ include::modules/ols-proc-resolving-truncated-responses.adoc[leveloffset=+1]
 
 include::modules/ols-proc-resolving-issues-with-conversation-history.adoc[leveloffset=+1]
 
+include::modules/ols-proc-google-vertex-ai-configuration-resource-is-rejected.adoc[leveloffset=+1]