From 2078be9a2050da9f81a81eef05bd2e0ba9adb49e Mon Sep 17 00:00:00 2001 From: Oleksii Orel Date: Wed, 12 Aug 2026 18:21:38 +0300 Subject: [PATCH] docs: document arch-aware filtering and version picker for AI tools Documents two features shipped in eclipse-che/che-dashboard#1643: - arch-aware filtering: add the optional `arch` field to the tool registry JSON example, document accepted values (x86_64, arm64, s390x, ppc64le), and explain that the backend filters the tool list by the architectures present in the cluster before sending it to the dashboard (a tool is shown if at least one cluster node matches). Add a NOTE that OpenCode supports only x86_64 and arm64 because the official upstream image does not publish s390x/ppc64le builds. - version picker: document that when a provider has multiple tool entries with different tag values, the AI Selector shows a version picker. Update the end-user guide with a dedicated section and explain the same picker is available on the workspace Overview tab. Update the change-AI-tool procedure to cover selecting a specific image variant via the ellipsis menu. relates to https://redhat.atlassian.net/browse/CRW-11779 Assisted-by: Claude Sonnet 4.6 Signed-off-by: Oleksii Orel --- .../pages/configuring-ai-providers.adoc | 25 +++++++++++++------ .../changing-the-ai-tool-on-a-workspace.adoc | 12 ++++++--- .../using-ai-assistants-in-workspaces.adoc | 8 ++++++ 3 files changed, 34 insertions(+), 11 deletions(-) diff --git a/modules/administration-guide/pages/configuring-ai-providers.adoc b/modules/administration-guide/pages/configuring-ai-providers.adoc index 8be4bd5f88..7eef2df746 100644 --- a/modules/administration-guide/pages/configuring-ai-providers.adoc +++ b/modules/administration-guide/pages/configuring-ai-providers.adoc @@ -1,6 +1,6 @@ :_content-type: PROCEDURE :description: Register AI providers in Eclipse Che so that developers can select and use AI coding assistants when creating workspaces. -:keywords: administration, ai, ai provider, opencode, configmap, ai-tool-registry, api key, injector image, dockerfile +:keywords: administration, ai, ai provider, opencode, configmap, ai-tool-registry, api key, injector image, dockerfile, architecture, arch, version :navtitle: Configuring AI providers :page-aliases: @@ -10,11 +10,20 @@ :FeatureName: The AI provider feature include::example$snip_che-technology-preview.adoc[] +[NOTE] +==== +OpenCode supports only `x86_64` and `arm64`. IBM Z (`s390x`) and IBM Power (`ppc64le`) builds are not available because the upstream OpenCode project does not publish releases for those architectures. +==== + [role="_abstract"] Register one or more AI providers in {prod-short} so that developers can select and use AI coding assistants when creating workspaces. The AI tool registry is stored in a {kubernetes} `ConfigMap` with specific labels. When the ConfigMap exists and contains at least one provider with a matching tool, the AI Selector widget is displayed on the dashboard. When the ConfigMap is absent or empty, the widget is hidden. +{prod-short} reads the node architectures present in the cluster and filters the tool list before sending it to the dashboard. A tool is shown if at least one cluster node matches an architecture in the tool's `arch` list. Tools that omit the `arch` field are shown on all architectures. + +When a provider has multiple tool entries with different `tag` values, the AI Selector displays a version picker so developers can choose which image variant to inject. + .Prerequisites * An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. @@ -68,7 +77,7 @@ Key design points: + ** *Multi-stage build*: the `builder` stage downloads the architecture-specific binary; the minimal runtime stage keeps the final image small. ** *Wrapper script*: redirects `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, and related variables to writable paths under `/tmp`, allowing the tool to run as an arbitrary UID on OpenShift. -** *Multi-arch*: pass `--platform linux/amd64,linux/arm64` to `docker build` to produce a multi-arch image. +** *Multi-arch*: pass `--platform` to `docker build` to produce a multi-arch image. OpenCode supports `linux/amd64` and `linux/arm64` only. + Build and push the image: + @@ -105,22 +114,24 @@ See link:https://github.com/che-incubator/che-ai-tool-images[che-incubator/che-a "binary": "opencode", <4> "pattern": "init", <5> "injectorImage": "____/____/opencode:next", <6> - "envVarName": "OPENAI_API_KEY" <7> + "envVarName": "OPENAI_API_KEY", <7> + "arch": ["x86_64", "arm64"] <8> } ], - "defaultAiProviders": ["opencodeai/opencode"] <8> + "defaultAiProviders": ["opencodeai/opencode"] <9> } ---- <1> Unique provider identifier in `____/____` format. <2> Links the tool to its provider by `id`. -<3> Version tag. When multiple tools share the same `providerId`, the dashboard selects by priority: `next` > `latest` > highest semver. +<3> Version tag. When multiple tools share the same `providerId`, the dashboard shows a version picker so developers can choose which image variant to inject. <4> Binary name that must be available in `PATH` inside the workspace after injection. <5> Injection pattern: `init` copies a single binary into the shared volume; `bundle` copies a full runtime directory and creates a symlink. <6> Container image that carries the tool binary. Run as an init container at workspace start. <7> Environment variable name for the API key. The dashboard creates a {kubernetes} Secret using this name as the data key. -<8> Optional. Provider IDs pre-selected in the AI Selector widget for new workspaces. +<8> Optional. List of node architectures on which this tool is available. Accepted values: `x86_64`, `arm64`. When omitted, the tool is shown on all architectures. The dashboard reads the cluster node architecture and hides tools whose `arch` list does not include the running architecture. +<9> Optional. Provider IDs pre-selected in the AI Selector widget for new workspaces. -. Create the `ConfigMap` in the `{prod-namespace}` namespace with the required labels: +. Create the `ConfigMap` in the `{prod-namespace}` {orch-namespace} with the required labels: + [subs="+quotes,+attributes"] ---- diff --git a/modules/end-user-guide/pages/changing-the-ai-tool-on-a-workspace.adoc b/modules/end-user-guide/pages/changing-the-ai-tool-on-a-workspace.adoc index 8d6e8c3ebe..af3c933ae3 100644 --- a/modules/end-user-guide/pages/changing-the-ai-tool-on-a-workspace.adoc +++ b/modules/end-user-guide/pages/changing-the-ai-tool-on-a-workspace.adoc @@ -1,6 +1,6 @@ :_content-type: PROCEDURE -:description: Switch or remove the AI coding assistant on a stopped workspace without recreating it. -:keywords: user-guide, ai, ai tool, ai provider, workspace, change, update +:description: Switch or remove the AI coding assistant on a stopped workspace without recreating it, and optionally choose a specific version. +:keywords: user-guide, ai, ai tool, ai provider, workspace, change, update, version :navtitle: Changing the AI tool on a workspace :page-aliases: @@ -8,7 +8,7 @@ = Change the AI tool on a workspace [role="_abstract"] -Switch or remove the AI coding assistant on a stopped workspace without recreating it. +Switch or remove the AI coding assistant on a stopped workspace without recreating it, and optionally choose a specific image version. .Prerequisites @@ -18,7 +18,11 @@ Switch or remove the AI coding assistant on a stopped workspace without recreati . Navigate to *Workspaces* and click the workspace name. . On the *Overview* tab, find the *AI Tool* section. -. Click the edit icon, select a different tool or *None*, and click *Save*. +. Click the edit icon. +. In the *Change AI Tools* dialog: +.. Select a different tool or deselect all tools to remove the AI assistant. +.. Optional: If the tool offers multiple versions, click the ellipsis menu (⋮) next to the tool name and select the version you want. +. Click *Save*. NOTE: The AI tool can only be changed while the workspace is stopped. diff --git a/modules/end-user-guide/pages/using-ai-assistants-in-workspaces.adoc b/modules/end-user-guide/pages/using-ai-assistants-in-workspaces.adoc index 03c84cece4..2bfa89229d 100644 --- a/modules/end-user-guide/pages/using-ai-assistants-in-workspaces.adoc +++ b/modules/end-user-guide/pages/using-ai-assistants-in-workspaces.adoc @@ -14,10 +14,18 @@ When your administrator configures AI providers, an *AI Provider* section is dis If no AI providers are configured, the *AI Provider* section is hidden. +NOTE: The dashboard only shows tools that are compatible with the architecture of your cluster nodes. On IBM Z (s390x) or Power (ppc64le) clusters, tools that do not support those architectures are hidden automatically. + == Default AI provider If your administrator has set a default AI provider, the *Create Workspace* page displays it automatically. To override, expand *Choose an AI Provider* and select a different provider. +== Selecting a tool version + +When an AI provider offers multiple image variants (for example, `next` and `insiders`), an ellipsis menu (⋮) is displayed on the provider card. Click the menu to choose the version you want injected into your workspace. The selected version is shown as a label on the card. + +The same version picker is available on the *Overview* tab of an existing workspace under *AI Tool > edit*. + == AI Provider column in the Workspaces page The *Workspaces* page displays an *AI Provider(s)* column showing the injected AI tool for each workspace.