From 75734ae7eda8f1b3cb6dc31cfc5dfbe05dbde3e9 Mon Sep 17 00:00:00 2001 From: Priyanka Abel Date: Fri, 22 May 2026 00:29:48 +0530 Subject: [PATCH] Google vertex AI documentation --- ...figuring-integrating-google-vertex-ai.adoc | 16 +++ modules/ols-1-1-release-notes.adoc | 4 + ...ing-proc-configuring-google-vertex-ai.adoc | 104 +++++++++++++++++ ...g-ref-google-vertex-ai-provider-types.adoc | 25 ++++ ...ng-ref-olsconfig-google-vertex-fields.adoc | 109 ++++++++++++++++++ ...ai-configuration-resource-is-rejected.adoc | 16 +++ ...issues-with-conversation-history copy.adoc | 13 +++ ...-troubleshooting-openshift-lightspeed.adoc | 1 + 8 files changed, 288 insertions(+) create mode 100644 configure/ols-configuring-integrating-google-vertex-ai.adoc create mode 100644 modules/ols-configuring-proc-configuring-google-vertex-ai.adoc create mode 100644 modules/ols-configuring-ref-google-vertex-ai-provider-types.adoc create mode 100644 modules/ols-configuring-ref-olsconfig-google-vertex-fields.adoc create mode 100644 modules/ols-proc-google-vertex-ai-configuration-resource-is-rejected.adoc create mode 100644 modules/ols-proc-resolving-issues-with-conversation-history copy.adoc diff --git a/configure/ols-configuring-integrating-google-vertex-ai.adoc b/configure/ols-configuring-integrating-google-vertex-ai.adoc new file mode 100644 index 000000000000..623e99bc0615 --- /dev/null +++ b/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] \ No newline at end of file diff --git a/modules/ols-1-1-release-notes.adoc b/modules/ols-1-1-release-notes.adoc index 0508e93ac822..81edd3fc3c94 100644 --- a/modules/ols-1-1-release-notes.adoc +++ b/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. diff --git a/modules/ols-configuring-proc-configuring-google-vertex-ai.adoc b/modules/ols-configuring-proc-configuring-google-vertex-ai.adoc new file mode 100644 index 000000000000..a365984d3aab --- /dev/null +++ b/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` + diff --git a/modules/ols-configuring-ref-google-vertex-ai-provider-types.adoc b/modules/ols-configuring-ref-google-vertex-ai-provider-types.adoc new file mode 100644 index 000000000000..8e4a120fb207 --- /dev/null +++ b/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` +|=== diff --git a/modules/ols-configuring-ref-olsconfig-google-vertex-fields.adoc b/modules/ols-configuring-ref-olsconfig-google-vertex-fields.adoc new file mode 100644 index 000000000000..4b046d46d8a6 --- /dev/null +++ b/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. +|=== + diff --git a/modules/ols-proc-google-vertex-ai-configuration-resource-is-rejected.adoc b/modules/ols-proc-google-vertex-ai-configuration-resource-is-rejected.adoc new file mode 100644 index 000000000000..bc4b905d92f6 --- /dev/null +++ b/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`. diff --git a/modules/ols-proc-resolving-issues-with-conversation-history copy.adoc b/modules/ols-proc-resolving-issues-with-conversation-history copy.adoc new file mode 100644 index 000000000000..a70822310b10 --- /dev/null +++ b/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. diff --git a/troubleshoot/ols-troubleshooting-openshift-lightspeed.adoc b/troubleshoot/ols-troubleshooting-openshift-lightspeed.adoc index bc7b41ecc42f..7126e7dfd274 100644 --- a/troubleshoot/ols-troubleshooting-openshift-lightspeed.adoc +++ b/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]