From a79d84a171ff7e0794f91117c653c3ef9cdd44bc Mon Sep 17 00:00:00 2001 From: Oleksii Orel Date: Mon, 11 May 2026 05:11:35 +0300 Subject: [PATCH 1/4] docs: add AI provider configuration and usage docs Assisted-by: Claude Sonnet 4.6 Signed-off-by: Oleksii Orel --- modules/administration-guide/nav.adoc | 2 + .../ai-provider-api-key-secret-reference.adoc | 113 ++++++++++++++++++ ...ster-custom-resource-fields-reference.adoc | 95 +++++++++++++++ .../pages/configuring-ai-providers.adoc | 111 +++++++++++++++++ modules/end-user-guide/nav.adoc | 3 + .../configuring-an-ai-provider-api-key.adoc | 55 +++++++++ .../pages/mounting-secrets.adoc | 3 + ...the-urls-for-starting-a-new-workspace.adoc | 1 + .../url-parameter-for-the-ai-provider.adoc | 25 ++++ .../using-ai-assistants-in-workspaces.adoc | 44 +++++++ ...ials-and-configurations-in-workspaces.adoc | 3 +- .../partials/proc_creating-workspaces.adoc | 1 + 12 files changed, 455 insertions(+), 1 deletion(-) create mode 100644 modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc create mode 100644 modules/administration-guide/pages/configuring-ai-providers.adoc create mode 100644 modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc create mode 100644 modules/end-user-guide/pages/url-parameter-for-the-ai-provider.adoc create mode 100644 modules/end-user-guide/pages/using-ai-assistants-in-workspaces.adoc diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index e26825866c..550c1647bf 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -97,6 +97,8 @@ *** xref:configuring-default-editor.adoc[] *** xref:concealing-editors.adoc[] *** xref:configuring-editors-download-urls.adoc[] +*** xref:configuring-ai-providers.adoc[] +**** xref:ai-provider-api-key-secret-reference.adoc[] *** xref:customizing-openshift-che-branding-images.adoc[] ** xref:managing-identities-and-authorizations.adoc[] *** xref:configuring-oauth-for-git-providers.adoc[] diff --git a/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc b/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc new file mode 100644 index 0000000000..6ab80b0702 --- /dev/null +++ b/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc @@ -0,0 +1,113 @@ +:_content-type: REFERENCE +:description: Reference for the Kubernetes Secret schema used by the Eclipse Che AI Selector to store and auto-mount AI provider API keys into workspace containers. +:keywords: administration, ai, api key, secret, kubernetes, devworkspace controller, environment variable, mount +:navtitle: AI Provider API Key Secret Reference +:page-aliases: + +[id="ai-provider-api-key-secret-reference"] += AI provider API key Secret reference + +The {prod-short} dashboard stores each user's AI provider API key as a Kubernetes `Opaque` Secret in the user's personal {orch-namespace}. The {devworkspace} Controller automatically mounts matching Secrets as environment variables into all workspace containers. No modification of the `{devworkspace}` spec or devfile is required. + +== Secret schema + +[source,yaml,subs="+quotes,+attributes"] +---- +apiVersion: v1 +kind: Secret +metadata: + name: ai-provider-gemini-api-key <1> + namespace: ____ + labels: + controller.devfile.io/mount-to-devworkspace: 'true' <2> + controller.devfile.io/watch-secret: 'true' <3> + che.eclipse.org/ai-provider-id: google-gemini <4> + annotations: + controller.devfile.io/mount-as: env <5> +type: Opaque +data: + GEMINI_API_KEY: ____ <6> +---- +<1> Secret name is derived as `ai-provider-` + `envVarName.toLowerCase().replace(/_/g, '-')`. For `GEMINI_API_KEY` the name is `ai-provider-gemini-api-key`. +<2> Instructs the DevWorkspace Controller to mount this Secret into all `DevWorkspace` containers in the namespace. +<3> Instructs the DevWorkspace Controller to watch for Secret changes and re-mount without a workspace restart. +<4> Sanitized provider ID (slashes replaced with dashes). Identifies which AI provider this Secret belongs to. Used by the {prod-short} dashboard to detect existing keys. +<5> Mounts the Secret data keys as environment variables (not as files). +<6> The data key is the environment variable name. The value is base64-encoded. The variable is injected directly into all workspace containers. + +== Label and annotation reference + +[cols="1,1,2",options="header"] +|=== +| Label / Annotation | Value | Purpose + +| `controller.devfile.io/mount-to-devworkspace` +| `'true'` +| Causes the DevWorkspace Controller to mount this Secret into every `DevWorkspace` in the namespace. + +| `controller.devfile.io/watch-secret` +| `'true'` +| The DevWorkspace Controller re-mounts the Secret when its data changes, without requiring a workspace restart. + +| `controller.devfile.io/mount-as` +| `env` +| Each data key in the Secret becomes an environment variable with the key as the variable name and the decoded value as the variable value. + +| `che.eclipse.org/ai-provider-id` +| Sanitized provider ID (for example, `google-gemini`). Slashes in the provider `id` are replaced with dashes. +| Used by the {prod-short} dashboard to identify and list AI provider key Secrets when rendering the AI Selector widget. +|=== + +== Secret naming convention + +Secret names follow the pattern: + +---- +ai-provider- +---- + +Examples: + +[cols="1,1",options="header"] +|=== +| `envVarName` | Secret name + +| `GEMINI_API_KEY` +| `ai-provider-gemini-api-key` + +| `ANTHROPIC_API_KEY` +| `ai-provider-anthropic-api-key` + +| `OPENAI_API_KEY` +| `ai-provider-openai-api-key` +|=== + +== Manual Secret creation + +Advanced users can create AI provider key Secrets manually using `{orch-cli}` instead of the dashboard UI. Use the same labels and annotations as shown in the schema above: + +[subs="+quotes,+attributes"] +---- +$ {orch-cli} apply -f - <__ + labels: + controller.devfile.io/mount-to-devworkspace: 'true' + controller.devfile.io/watch-secret: 'true' + che.eclipse.org/ai-provider-id: google-gemini + annotations: + controller.devfile.io/mount-as: env +type: Opaque +data: + GEMINI_API_KEY: ____ +EOF +---- + +.Additional resources + +* xref:configuring-ai-providers.adoc[] +* xref:mounting-secrets.adoc[Mounting Secrets (end-user guide)] +* link:https://devfile.io/docs/2.2.0/what-is-a-devfile[DevWorkspace Operator documentation] diff --git a/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc b/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc index a755b3fa02..9e1c76cb26 100644 --- a/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc +++ b/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc @@ -11,9 +11,11 @@ This section describes all fields available to customize the `CheCluster` Custom * xref:a-minimal-checluster-custom-resource-example[] * xref:checluster-custom-resource-devEnvironments-settings[] +** xref:checluster-custom-resource-devEnvironments-aiProviders-settings[] ** xref:checluster-custom-resource-devEnvironments-allowedSources-settings[] ** xref:checluster-custom-resource-devEnvironments-containerBuildConfiguration-settings[] ** xref:checluster-custom-resource-devEnvironments-containerRunConfiguration-settings[] +** xref:checluster-custom-resource-devEnvironments-defaultAiProvider-settings[] ** xref:checluster-custom-resource-devEnvironments-defaultNamespace-settings[] ** xref:checluster-custom-resource-devEnvironments-defaultPlugins-settings[] ** xref:checluster-custom-resource-devEnvironments-editorsDownloadUrls-settings[] @@ -100,3 +102,96 @@ spec: ==== include::example$checluster-properties/checluster-properties.adoc[leveloffset=+1] + +[id="ai-tool-registry-configmap-reference"] +== AI tool registry ConfigMap + +AI providers and tools are configured through a {kubernetes} `ConfigMap` in the `{prod-namespace}` namespace, not through the `{prod-checluster}` custom resource. The ConfigMap must have the following labels to be discovered by the dashboard: + +* `app.kubernetes.io/component=ai-tool-registry` +* `app.kubernetes.io/part-of=che.eclipse.org` + +The ConfigMap contains a `registry.json` key with three sections: `providers`, `tools`, and `defaultAiProviders`. + +=== Provider fields + +[cols="1,1,3",options="header"] +|=== +| Field | Type | Description + +| `id` +| `string` +| Unique identifier for the provider (for example, `google/gemini`). + +| `name` +| `string` +| Display name shown in the dashboard (for example, `Gemini`). + +| `publisher` +| `string` +| Publisher name (for example, `Google`). + +| `description` +| `string` (optional) +| Short description shown in the provider card. + +| `docsUrl` +| `string` (optional) +| URL to the provider's API key documentation, shown as a link in the dashboard. + +| `icon` +| `string` (optional) +| URL to the provider's SVG icon. +|=== + +=== Tool fields + +[cols="1,1,3",options="header"] +|=== +| Field | Type | Description + +| `providerId` +| `string` +| Links the tool to a provider by `id` (for example, `google/gemini`). + +| `tag` +| `string` +| Version tag (for example, `next`, `latest`, `3.21`). When multiple tools share the same `providerId`, the dashboard selects by priority: `next` > `latest` > highest semver. + +| `name` +| `string` +| Display name for the tool (for example, `Gemini CLI`). + +| `url` +| `string` +| URL to the tool's homepage. + +| `binary` +| `string` +| Binary name available in `PATH` after injection (for example, `gemini`). + +| `pattern` +| `string` +| Injection pattern: `init` (single binary copied to `/injected-tools/bin/`) or `bundle` (full runtime directory copied and symlinked). + +| `injectorImage` +| `string` +| Container image used as an init container to copy the tool binary into a shared volume. + +| `envVarName` +| `string` (optional) +| Name of the environment variable for the API key (for example, `GEMINI_API_KEY`). This is also the data key in the {kubernetes} Secret. + +| `setupCommand` +| `string` (optional) +| One-time setup command run in the editor container at postStart. +|=== + +=== defaultAiProviders + +Optional. A JSON array of provider `id` values that are pre-selected in the AI Selector widget for new workspaces. + +.Additional resources + +* xref:configuring-ai-providers.adoc[] +* xref:ai-provider-api-key-secret-reference.adoc[] diff --git a/modules/administration-guide/pages/configuring-ai-providers.adoc b/modules/administration-guide/pages/configuring-ai-providers.adoc new file mode 100644 index 0000000000..694ea8c8aa --- /dev/null +++ b/modules/administration-guide/pages/configuring-ai-providers.adoc @@ -0,0 +1,111 @@ +:_content-type: PROCEDURE +:description: Enable and configure AI provider support in Eclipse Che so that users can select an AI assistant when creating workspaces. +:keywords: administration, ai, ai provider, gemini, claude, configmap, ai-tool-registry, api key +:navtitle: Configuring AI Providers +:page-aliases: + +[id="configuring-ai-providers"] += Configuring AI providers + +Enable one or more AI providers in {prod-short} so that users can select an AI coding assistant from the *Create Workspace* page and have the tool binary injected into the workspace editor container. + +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. + +.Prerequisites + +* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}. +* The {prod-operator} is installed and a `{prod-checluster}` custom resource exists in the `{prod-namespace}` namespace. + +.Procedure + +. Create a `registry.json` file defining providers, tools, and default selections: ++ +[source,json,subs="+quotes"] +---- +{ + "providers": [ + { + "id": "google/gemini", + "name": "Gemini", + "publisher": "Google", + "description": "Google Gemini AI assistant for the terminal.", + "docsUrl": "https://ai.google.dev/gemini-api/docs/quickstart", + "icon": "https://example.com/gemini-icon.svg" + }, + { + "id": "anthropic/claude", + "name": "Claude", + "publisher": "Anthropic", + "description": "Anthropic Claude AI coding assistant for terminal.", + "docsUrl": "https://docs.anthropic.com/claude/reference/getting-started-with-the-api", + "icon": "https://example.com/claude-icon.svg" + } + ], + "tools": [ + { + "providerId": "google/gemini", <1> + "tag": "next", <2> + "name": "Gemini CLI", + "url": "https://ai.google.dev/gemini-api/docs", + "binary": "gemini", <3> + "pattern": "bundle", <4> + "injectorImage": "quay.io/example/gemini-cli:next", <5> + "envVarName": "GEMINI_API_KEY" <6> + }, + { + "providerId": "anthropic/claude", + "tag": "next", + "name": "Claude Code", + "url": "https://claude.ai/code", + "binary": "claude", + "pattern": "init", + "injectorImage": "quay.io/example/claude-code:next", + "envVarName": "ANTHROPIC_API_KEY" + } + ], + "defaultAiProviders": ["google/gemini"] <7> +} +---- +<1> Links the tool to a provider by the provider's `id`. +<2> Version tag. When multiple tools share the same `providerId`, the dashboard selects by tag priority: `next` > `latest` > highest semver. +<3> Binary name available in `PATH` after injection. +<4> Injection pattern: `init` copies a single binary; `bundle` copies a full runtime directory and creates a symlink. +<5> Container image used as an init container to copy the tool binary into a shared volume. +<6> Environment variable name for the API key. The dashboard creates a {kubernetes} Secret with this key. +<7> Optional. List of provider IDs pre-selected in the AI Selector widget for new workspaces. + +. Create the `ConfigMap` in the `{prod-namespace}` namespace with the required labels: ++ +[subs="+quotes,+attributes"] +---- +$ {orch-cli} create configmap ai-tool-registry \ + --from-file=registry.json=registry.json \ + -n {prod-namespace} \ + --dry-run=client -o yaml | \ + {orch-cli} label --local -f - \ + app.kubernetes.io/component=ai-tool-registry \ + app.kubernetes.io/part-of=che.eclipse.org \ + -o yaml | \ + {orch-cli} apply -f - +---- + +.Verification + +. Open the {prod-short} dashboard. +. Navigate to *Create Workspace*. +. Verify that an *AI Provider* section is visible, listing the providers you configured. + +[NOTE] +==== +To disable the AI Selector widget, delete the `ai-tool-registry` ConfigMap. Users will no longer see the AI Provider section on the Create Workspace page. Existing API key Secrets in user namespaces are not deleted automatically. +==== + +[NOTE] +==== +When an administrator updates the registry (for example, removes a tool or changes the injector image tag), existing workspaces are updated automatically before their next start. The dashboard removes stale tool injectors and replaces outdated image tags without user intervention. +==== + +.Additional resources + +* xref:ai-provider-api-key-secret-reference.adoc[] +* xref:using-ai-assistants-in-workspaces.adoc[] diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index 18c9c36cf4..88a4dfa26e 100644 --- a/modules/end-user-guide/nav.adoc +++ b/modules/end-user-guide/nav.adoc @@ -15,6 +15,7 @@ **** xref:url-parameter-for-memory-limit.adoc[] **** xref:url-parameter-for-cpu-limit.adoc[] **** xref:url-parameter-for-the-existing-workspace-name.adoc[] +**** xref:url-parameter-for-the-ai-provider.adoc[] ** xref:starting-a-workspace-from-a-raw-devfile-url.adoc[] ** xref:basic-actions-you-can-perform-on-a-workspace.adoc[] ** xref:restoring-workspaces-from-backups.adoc[] @@ -36,6 +37,8 @@ ** xref:microsoft-visual-studio-code-open-source-ide.adoc[] ** xref:connect-visual-studio-code-to-che-workspace.adoc[] ** xref:defining-a-common-ide.adoc[] +* xref:using-ai-assistants-in-workspaces.adoc[] +** xref:configuring-an-ai-provider-api-key.adoc[] * xref:using-credentials-and-configurations-in-workspaces.adoc[] ** xref:mounting-secrets.adoc[] *** xref:creating-image-pull-secrets.adoc[] diff --git a/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc b/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc new file mode 100644 index 0000000000..418c6e9fd2 --- /dev/null +++ b/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc @@ -0,0 +1,55 @@ +:_content-type: PROCEDURE +:description: Configuring an AI provider API key in Eclipse Che. +:keywords: user-guide, ai, api key, gemini, claude, ai provider, environment variable, secret +:navtitle: Configuring an AI Provider API Key +:page-aliases: + +[id="configuring-an-ai-provider-api-key"] += Configuring an AI provider API key + +Configure an AI provider API key so that it is automatically injected as an environment variable into all your workspaces. + +.Prerequisites + +* Your administrator has enabled at least one AI provider. +* You have a valid API key from your AI provider. + +.Procedure + +You can configure an API key from the *Create Workspace* page or from *User Preferences*. + +=== From the Create Workspace page + +. Navigate to *Create Workspace*. +. In the *AI Provider* section, expand *Choose an AI Provider*. +. Click the provider card. +. Enter your API key and click *Save key*. ++ +A *Key configured* badge is displayed on the provider card. + +=== From User Preferences + +. Navigate to *User Preferences > AI Providers Keys*. +. Click *Add API Key*. +. Select the AI provider and enter the API key. +. Click *Save*. + +To update or delete a key, use the edit or delete icons in the table row. + +.Verification + +. Start a workspace with the configured AI provider. +. Open a terminal and verify: ++ +[subs="+quotes"] +---- +$ which gemini +$ echo $GEMINI_API_KEY +---- + +NOTE: The API key is available in all workspaces in your {orch-namespace}, including already running ones. + +.Additional resources + +* xref:using-ai-assistants-in-workspaces.adoc[] +* xref:mounting-secrets.adoc[] diff --git a/modules/end-user-guide/pages/mounting-secrets.adoc b/modules/end-user-guide/pages/mounting-secrets.adoc index 4057d35bd2..f21f96482a 100644 --- a/modules/end-user-guide/pages/mounting-secrets.adoc +++ b/modules/end-user-guide/pages/mounting-secrets.adoc @@ -99,5 +99,8 @@ $ mvn --settings /home/user/.m2/settings.xml clean install ==== + .Additional resources + * link:https://github.com/devfile/devworkspace-operator/blob/main/docs/additional-configuration.adoc#automatically-mounting-volumes-configmaps-and-secrets[Automatically mounting volumes, configmaps, and secrets] +* xref:configuring-an-ai-provider-api-key.adoc[] (the {prod-short} dashboard uses this same auto-mount mechanism to inject AI provider API keys into workspaces) diff --git a/modules/end-user-guide/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc b/modules/end-user-guide/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc index 21d2ae1445..a64e5f46c9 100644 --- a/modules/end-user-guide/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc +++ b/modules/end-user-guide/pages/optional-parameters-for-the-urls-for-starting-a-new-workspace.adoc @@ -21,3 +21,4 @@ When you start a new workspace, {prod-short} configures the workspace according * xref:url-parameter-for-memory-limit.adoc[] * xref:url-parameter-for-cpu-limit.adoc[] * xref:url-parameter-for-the-existing-workspace-name.adoc[] +* xref:url-parameter-for-the-ai-provider.adoc[] diff --git a/modules/end-user-guide/pages/url-parameter-for-the-ai-provider.adoc b/modules/end-user-guide/pages/url-parameter-for-the-ai-provider.adoc new file mode 100644 index 0000000000..4eca20a372 --- /dev/null +++ b/modules/end-user-guide/pages/url-parameter-for-the-ai-provider.adoc @@ -0,0 +1,25 @@ +:_content-type: CONCEPT +:description: URL parameter for the AI provider +:keywords: parameter, URL, ai, ai provider, ai tool +:navtitle: URL parameter for the AI provider +:page-aliases: + +[id="url-parameter-for-the-ai-provider"] += URL parameter for the AI provider + +You can use the `ai-provider=` URL parameter to specify one or more AI providers to inject into the workspace. + +The URL parameter accepts a comma-separated list of provider IDs: + +[source,subs="+quotes,+attributes,+macros"] +---- +pass:c,a,q[{prod-url}]#____?ai-provider=____ +---- + +.Example with a single provider +`pass:c,a,q[{prod-url}]#____?ai-provider=google/gemini` + +.Example with multiple providers +`pass:c,a,q[{prod-url}]#____?ai-provider=google/gemini,anthropic/claude,opencodeai/opencode` + +NOTE: The `ai-provider=` parameter requires that the AI tool registry ConfigMap is configured by the administrator. Provider IDs not found in the registry are ignored. 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 new file mode 100644 index 0000000000..dd7d133837 --- /dev/null +++ b/modules/end-user-guide/pages/using-ai-assistants-in-workspaces.adoc @@ -0,0 +1,44 @@ +:_content-type: CONCEPT +:description: Using AI coding assistants in Eclipse Che workspaces. +:keywords: user-guide, ai, ai assistant, ai provider, ai selector, gemini, claude +:navtitle: Using AI Assistants in Workspaces +:page-aliases: + +[id="using-ai-assistants-in-workspaces"] += Using AI assistants in workspaces + +When your administrator configures AI providers, an *AI Provider* section is displayed on the *Create Workspace* page. Selecting a provider injects the tool binary into the workspace editor container and adds it to `PATH`. + +You can select one or more AI providers when creating a workspace. + +If no AI providers are configured, the *AI Provider* section is hidden. + +== Default AI provider + +If a default AI provider is configured, the *Create Workspace* page displays: + +____ +The default AI provider "Gemini" configured by your administrator will be used. +____ + +To override, expand *Choose an AI Provider* and select a different provider. + +== AI Provider column in the Workspaces page + +The *Workspaces* page displays an *AI Provider(s)* column showing the injected AI tool for each workspace. + +== Changing the AI tool on an existing workspace + +On a stopped workspace: + +. 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*. + +NOTE: The AI tool can only be changed while the workspace is stopped. + +.Additional resources + +* xref:configuring-an-ai-provider-api-key.adoc[] +* xref:url-parameter-for-the-ai-provider.adoc[] +* xref:mounting-secrets.adoc[] \ No newline at end of file diff --git a/modules/end-user-guide/pages/using-credentials-and-configurations-in-workspaces.adoc b/modules/end-user-guide/pages/using-credentials-and-configurations-in-workspaces.adoc index 27033ff9a9..3e6e5afdfa 100644 --- a/modules/end-user-guide/pages/using-credentials-and-configurations-in-workspaces.adoc +++ b/modules/end-user-guide/pages/using-credentials-and-configurations-in-workspaces.adoc @@ -23,13 +23,14 @@ The mounting process uses the standard {kubernetes} mounting mechanism and requi You can create permanent mount points for various components: -* Maven configuration, such as the link:https://maven.apache.org/settings.html[user-specific] `settings.xml` file +* Maven configuration, such as the link:https://maven.apache.org/settings.html[user-specific] `settings.xml` file * SSH key pairs * xref:using-a-git-provider-access-token.adoc[Git-provider access tokens] * xref:mounting-git-configuration.adoc[Git configuration] * AWS authorization tokens * Configuration files * Persistent storage +* xref:configuring-an-ai-provider-api-key.adoc[AI provider API keys] for AI coding assistants such as Gemini or Claude .Additional resources diff --git a/modules/end-user-guide/partials/proc_creating-workspaces.adoc b/modules/end-user-guide/partials/proc_creating-workspaces.adoc index 58e7f0d039..abd1d59e8d 100644 --- a/modules/end-user-guide/partials/proc_creating-workspaces.adoc +++ b/modules/end-user-guide/partials/proc_creating-workspaces.adoc @@ -19,6 +19,7 @@ Creating workspaces through the {prod-short} dashboard provides better user expe ** Default IDE is specified with `devEnvironments.defaultEditor`. ** Default plugins are specified with `devEnvironments.defaultPlugins`. ** Container build configuration is specified with `devEnvironments.containerBuildConfiguration`. +** Available AI providers are configured through an `ai-tool-registry` ConfigMap in the `{prod-namespace}` namespace. ==== From add517ebc27b314754eb32546cb848ed0441b8c6 Mon Sep 17 00:00:00 2001 From: Oleksii Orel Date: Mon, 11 May 2026 05:11:45 +0300 Subject: [PATCH 2/4] docs: fix broken cross-references and section levels in AI docs - Fix section title levels in configuring-an-ai-provider-api-key.adoc (=== to == to follow expected sequence after = heading) - Add end-user-guide: module prefix to cross-module xrefs in ai-provider-api-key-secret-reference.adoc and configuring-ai-providers.adoc - Remove non-existent aiProviders and defaultAiProvider xrefs from checluster-custom-resource-fields-reference.adoc (AI config is ConfigMap-based, not CheCluster CR fields) Assisted-by: Claude Sonnet 4.6 Signed-off-by: Oleksii Orel --- .../pages/ai-provider-api-key-secret-reference.adoc | 2 +- .../pages/checluster-custom-resource-fields-reference.adoc | 2 -- .../administration-guide/pages/configuring-ai-providers.adoc | 2 +- .../pages/configuring-an-ai-provider-api-key.adoc | 4 ++-- 4 files changed, 4 insertions(+), 6 deletions(-) diff --git a/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc b/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc index 6ab80b0702..d7aba70b03 100644 --- a/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc +++ b/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc @@ -109,5 +109,5 @@ EOF .Additional resources * xref:configuring-ai-providers.adoc[] -* xref:mounting-secrets.adoc[Mounting Secrets (end-user guide)] +* xref:end-user-guide:mounting-secrets.adoc[Mounting Secrets (end-user guide)] * link:https://devfile.io/docs/2.2.0/what-is-a-devfile[DevWorkspace Operator documentation] diff --git a/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc b/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc index 9e1c76cb26..feccd8d0af 100644 --- a/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc +++ b/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc @@ -11,11 +11,9 @@ This section describes all fields available to customize the `CheCluster` Custom * xref:a-minimal-checluster-custom-resource-example[] * xref:checluster-custom-resource-devEnvironments-settings[] -** xref:checluster-custom-resource-devEnvironments-aiProviders-settings[] ** xref:checluster-custom-resource-devEnvironments-allowedSources-settings[] ** xref:checluster-custom-resource-devEnvironments-containerBuildConfiguration-settings[] ** xref:checluster-custom-resource-devEnvironments-containerRunConfiguration-settings[] -** xref:checluster-custom-resource-devEnvironments-defaultAiProvider-settings[] ** xref:checluster-custom-resource-devEnvironments-defaultNamespace-settings[] ** xref:checluster-custom-resource-devEnvironments-defaultPlugins-settings[] ** xref:checluster-custom-resource-devEnvironments-editorsDownloadUrls-settings[] diff --git a/modules/administration-guide/pages/configuring-ai-providers.adoc b/modules/administration-guide/pages/configuring-ai-providers.adoc index 694ea8c8aa..e566dd483b 100644 --- a/modules/administration-guide/pages/configuring-ai-providers.adoc +++ b/modules/administration-guide/pages/configuring-ai-providers.adoc @@ -108,4 +108,4 @@ When an administrator updates the registry (for example, removes a tool or chang .Additional resources * xref:ai-provider-api-key-secret-reference.adoc[] -* xref:using-ai-assistants-in-workspaces.adoc[] +* xref:end-user-guide:using-ai-assistants-in-workspaces.adoc[] diff --git a/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc b/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc index 418c6e9fd2..feeb2baa78 100644 --- a/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc +++ b/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc @@ -18,7 +18,7 @@ Configure an AI provider API key so that it is automatically injected as an envi You can configure an API key from the *Create Workspace* page or from *User Preferences*. -=== From the Create Workspace page +== From the Create Workspace page . Navigate to *Create Workspace*. . In the *AI Provider* section, expand *Choose an AI Provider*. @@ -27,7 +27,7 @@ You can configure an API key from the *Create Workspace* page or from *User Pref + A *Key configured* badge is displayed on the provider card. -=== From User Preferences +== From User Preferences . Navigate to *User Preferences > AI Providers Keys*. . Click *Add API Key*. From 733140c1627b3202ca6108156fcbfbdacfbd73ed Mon Sep 17 00:00:00 2001 From: Oleksii Orel Date: Mon, 11 May 2026 16:39:10 +0300 Subject: [PATCH 3/4] docs: address PR review feedback for AI docs - Sentence-case all :navtitle: values - Add [role="_abstract"] to all 5 modules with JTBD-focused text - Use imperative verb in procedure titles (Configure, not Configuring) - Use noun phrase for concept title (AI assistants in workspaces) - Fix :description: fields to explain what/why, not restate the title - Add Tech-Preview note to configuring-ai-providers.adoc - Consolidate two consecutive NOTE admonitions into one - Remove custom subheadings from procedure module; present both paths as a single numbered list with choice items - Fix hardcoded Gemini verification commands to generic placeholders - Fix callout 4: correct regex description (all non-identifier chars, not just slashes, are replaced with dashes) - Fix additional resources link: DevWorkspace Operator -> Devfile docs - Extract changing-the-ai-tool procedure into its own module and add xref from the concept page - Add changing-the-ai-tool-on-a-workspace.adoc to end-user nav Assisted-by: Claude Sonnet 4.6 Signed-off-by: Oleksii Orel --- .../ai-provider-api-key-secret-reference.adoc | 17 ++++---- .../pages/configuring-ai-providers.adoc | 19 ++++---- modules/end-user-guide/nav.adoc | 1 + .../changing-the-ai-tool-on-a-workspace.adoc | 28 ++++++++++++ .../configuring-an-ai-provider-api-key.adoc | 43 ++++++++++--------- .../url-parameter-for-the-ai-provider.adoc | 5 ++- .../using-ai-assistants-in-workspaces.adoc | 24 ++++------- 7 files changed, 82 insertions(+), 55 deletions(-) create mode 100644 modules/end-user-guide/pages/changing-the-ai-tool-on-a-workspace.adoc diff --git a/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc b/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc index d7aba70b03..7c3e09c696 100644 --- a/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc +++ b/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc @@ -1,13 +1,14 @@ :_content-type: REFERENCE -:description: Reference for the Kubernetes Secret schema used by the Eclipse Che AI Selector to store and auto-mount AI provider API keys into workspace containers. +:description: Kubernetes Secret schema, labels, and naming convention for AI provider API keys that are automatically mounted into workspace containers. :keywords: administration, ai, api key, secret, kubernetes, devworkspace controller, environment variable, mount -:navtitle: AI Provider API Key Secret Reference +:navtitle: AI provider API key secret reference :page-aliases: [id="ai-provider-api-key-secret-reference"] -= AI provider API key Secret reference += AI provider API key secret reference -The {prod-short} dashboard stores each user's AI provider API key as a Kubernetes `Opaque` Secret in the user's personal {orch-namespace}. The {devworkspace} Controller automatically mounts matching Secrets as environment variables into all workspace containers. No modification of the `{devworkspace}` spec or devfile is required. +[role="_abstract"] +Each user's AI provider API key is stored as a {kubernetes} `Opaque` Secret in the user's personal {orch-namespace}. The {devworkspace} Controller automatically mounts matching Secrets as environment variables into all workspace containers. Use this reference when manually creating or troubleshooting AI provider key Secrets. == Secret schema @@ -31,7 +32,7 @@ data: <1> Secret name is derived as `ai-provider-` + `envVarName.toLowerCase().replace(/_/g, '-')`. For `GEMINI_API_KEY` the name is `ai-provider-gemini-api-key`. <2> Instructs the DevWorkspace Controller to mount this Secret into all `DevWorkspace` containers in the namespace. <3> Instructs the DevWorkspace Controller to watch for Secret changes and re-mount without a workspace restart. -<4> Sanitized provider ID (slashes replaced with dashes). Identifies which AI provider this Secret belongs to. Used by the {prod-short} dashboard to detect existing keys. +<4> Sanitized provider ID (characters other than letters, digits, dots, underscores, and dashes are replaced with dashes). Identifies which AI provider this Secret belongs to. Used by the {prod-short} dashboard to detect existing keys. <5> Mounts the Secret data keys as environment variables (not as files). <6> The data key is the environment variable name. The value is base64-encoded. The variable is injected directly into all workspace containers. @@ -54,7 +55,7 @@ data: | Each data key in the Secret becomes an environment variable with the key as the variable name and the decoded value as the variable value. | `che.eclipse.org/ai-provider-id` -| Sanitized provider ID (for example, `google-gemini`). Slashes in the provider `id` are replaced with dashes. +| Sanitized provider ID (for example, `google-gemini`). Characters other than letters, digits, dots, underscores, and dashes are replaced with dashes. | Used by the {prod-short} dashboard to identify and list AI provider key Secrets when rendering the AI Selector widget. |=== @@ -109,5 +110,5 @@ EOF .Additional resources * xref:configuring-ai-providers.adoc[] -* xref:end-user-guide:mounting-secrets.adoc[Mounting Secrets (end-user guide)] -* link:https://devfile.io/docs/2.2.0/what-is-a-devfile[DevWorkspace Operator documentation] +* xref:end-user-guide:mounting-secrets.adoc[Mounting secrets (end-user guide)] +* link:https://devfile.io/docs/2.2.0/what-is-a-devfile[Devfile documentation] diff --git a/modules/administration-guide/pages/configuring-ai-providers.adoc b/modules/administration-guide/pages/configuring-ai-providers.adoc index e566dd483b..8d64468985 100644 --- a/modules/administration-guide/pages/configuring-ai-providers.adoc +++ b/modules/administration-guide/pages/configuring-ai-providers.adoc @@ -1,13 +1,17 @@ :_content-type: PROCEDURE -:description: Enable and configure AI provider support in Eclipse Che so that users can select an AI assistant when creating workspaces. +: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, gemini, claude, configmap, ai-tool-registry, api key -:navtitle: Configuring AI Providers +:navtitle: Configuring AI providers :page-aliases: [id="configuring-ai-providers"] -= Configuring AI providers += Configure AI providers -Enable one or more AI providers in {prod-short} so that users can select an AI coding assistant from the *Create Workspace* page and have the tool binary injected into the workspace editor container. +:FeatureName: The AI provider feature +include::examples/snip_che-technology-preview.adoc[] + +[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. @@ -97,12 +101,9 @@ $ {orch-cli} create configmap ai-tool-registry \ [NOTE] ==== -To disable the AI Selector widget, delete the `ai-tool-registry` ConfigMap. Users will no longer see the AI Provider section on the Create Workspace page. Existing API key Secrets in user namespaces are not deleted automatically. -==== +To disable the AI Selector widget, delete the `ai-tool-registry` ConfigMap. Users will no longer see the AI Provider section on the *Create Workspace* page. Existing API key Secrets in user namespaces are not deleted automatically. -[NOTE] -==== -When an administrator updates the registry (for example, removes a tool or changes the injector image tag), existing workspaces are updated automatically before their next start. The dashboard removes stale tool injectors and replaces outdated image tags without user intervention. +When you update the registry (for example, to remove a tool or change the injector image tag), existing workspaces are updated automatically before their next start. The dashboard removes stale tool injectors and replaces outdated image tags without user intervention. ==== .Additional resources diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index 88a4dfa26e..67375c870a 100644 --- a/modules/end-user-guide/nav.adoc +++ b/modules/end-user-guide/nav.adoc @@ -39,6 +39,7 @@ ** xref:defining-a-common-ide.adoc[] * xref:using-ai-assistants-in-workspaces.adoc[] ** xref:configuring-an-ai-provider-api-key.adoc[] +** xref:changing-the-ai-tool-on-a-workspace.adoc[] * xref:using-credentials-and-configurations-in-workspaces.adoc[] ** xref:mounting-secrets.adoc[] *** xref:creating-image-pull-secrets.adoc[] 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 new file mode 100644 index 0000000000..8d6e8c3ebe --- /dev/null +++ b/modules/end-user-guide/pages/changing-the-ai-tool-on-a-workspace.adoc @@ -0,0 +1,28 @@ +:_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 +:navtitle: Changing the AI tool on a workspace +:page-aliases: + +[id="changing-the-ai-tool-on-a-workspace"] += Change the AI tool on a workspace + +[role="_abstract"] +Switch or remove the AI coding assistant on a stopped workspace without recreating it. + +.Prerequisites + +* The workspace is stopped. + +.Procedure + +. 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*. + +NOTE: The AI tool can only be changed while the workspace is stopped. + +.Additional resources + +* xref:using-ai-assistants-in-workspaces.adoc[] +* xref:configuring-an-ai-provider-api-key.adoc[] diff --git a/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc b/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc index feeb2baa78..78d06b7294 100644 --- a/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc +++ b/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc @@ -1,12 +1,13 @@ :_content-type: PROCEDURE -:description: Configuring an AI provider API key in Eclipse Che. +:description: Store your AI provider API key so that it is automatically available as an environment variable in all your workspaces. :keywords: user-guide, ai, api key, gemini, claude, ai provider, environment variable, secret -:navtitle: Configuring an AI Provider API Key +:navtitle: Configuring an AI provider API key :page-aliases: [id="configuring-an-ai-provider-api-key"] -= Configuring an AI provider API key += Configure an AI provider API key +[role="_abstract"] Configure an AI provider API key so that it is automatically injected as an environment variable into all your workspaces. .Prerequisites @@ -16,36 +17,38 @@ Configure an AI provider API key so that it is automatically injected as an envi .Procedure -You can configure an API key from the *Create Workspace* page or from *User Preferences*. +. Configure the API key using one of the following methods: -== From the Create Workspace page - -. Navigate to *Create Workspace*. -. In the *AI Provider* section, expand *Choose an AI Provider*. -. Click the provider card. -. Enter your API key and click *Save key*. +** *From the Create Workspace page:* ++ +... Navigate to *Create Workspace*. +... In the *AI Provider* section, expand *Choose an AI Provider*. +... Click the provider card. +... Enter your API key and click *Save key*. + A *Key configured* badge is displayed on the provider card. -== From User Preferences - -. Navigate to *User Preferences > AI Providers Keys*. -. Click *Add API Key*. -. Select the AI provider and enter the API key. -. Click *Save*. - +** *From User Preferences:* ++ +... Navigate to *User Preferences > AI Providers Keys*. +... Click *Add API Key*. +... Select the AI provider and enter the API key. +... Click *Save*. ++ To update or delete a key, use the edit or delete icons in the table row. .Verification . Start a workspace with the configured AI provider. -. Open a terminal and verify: +. Open a terminal and verify that the tool binary is in `PATH` and the API key variable is set: + [subs="+quotes"] ---- -$ which gemini -$ echo $GEMINI_API_KEY +$ which ____ +$ test -n "$____" && echo "API key is configured" ---- ++ +Replace `____` and `____` with the values for your provider (for example, `gemini` and `GEMINI_API_KEY` for the Gemini provider). NOTE: The API key is available in all workspaces in your {orch-namespace}, including already running ones. diff --git a/modules/end-user-guide/pages/url-parameter-for-the-ai-provider.adoc b/modules/end-user-guide/pages/url-parameter-for-the-ai-provider.adoc index 4eca20a372..2b780e463c 100644 --- a/modules/end-user-guide/pages/url-parameter-for-the-ai-provider.adoc +++ b/modules/end-user-guide/pages/url-parameter-for-the-ai-provider.adoc @@ -1,5 +1,5 @@ :_content-type: CONCEPT -:description: URL parameter for the AI provider +:description: Pre-select AI coding assistants when starting a workspace from a URL by using the ai-provider parameter. :keywords: parameter, URL, ai, ai provider, ai tool :navtitle: URL parameter for the AI provider :page-aliases: @@ -7,7 +7,8 @@ [id="url-parameter-for-the-ai-provider"] = URL parameter for the AI provider -You can use the `ai-provider=` URL parameter to specify one or more AI providers to inject into the workspace. +[role="_abstract"] +Use the `ai-provider=` URL parameter to specify one or more AI providers in a workspace start URL. The workspace launches with the selected AI tool binaries injected and ready to use, without requiring manual selection on the dashboard. The URL parameter accepts a comma-separated list of provider IDs: 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 dd7d133837..dee30039d3 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 @@ -1,15 +1,16 @@ :_content-type: CONCEPT -:description: Using AI coding assistants in Eclipse Che workspaces. +:description: Select and configure AI coding assistants for your workspaces to get AI-powered development help in the terminal. :keywords: user-guide, ai, ai assistant, ai provider, ai selector, gemini, claude -:navtitle: Using AI Assistants in Workspaces +:navtitle: Using AI assistants in workspaces :page-aliases: [id="using-ai-assistants-in-workspaces"] -= Using AI assistants in workspaces += AI assistants in workspaces -When your administrator configures AI providers, an *AI Provider* section is displayed on the *Create Workspace* page. Selecting a provider injects the tool binary into the workspace editor container and adds it to `PATH`. +[role="_abstract"] +{prod-short} supports AI coding assistants that are injected into workspaces and available from the terminal. You can select one or more AI providers when creating a workspace, and your administrator controls which providers are available. -You can select one or more AI providers when creating a workspace. +When your administrator configures AI providers, an *AI Provider* section is displayed on the *Create Workspace* page. Selecting a provider injects the tool binary into the workspace editor container and adds it to `PATH`. If no AI providers are configured, the *AI Provider* section is hidden. @@ -27,18 +28,9 @@ To override, expand *Choose an AI Provider* and select a different provider. The *Workspaces* page displays an *AI Provider(s)* column showing the injected AI tool for each workspace. -== Changing the AI tool on an existing workspace - -On a stopped workspace: - -. 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*. - -NOTE: The AI tool can only be changed while the workspace is stopped. - .Additional resources * xref:configuring-an-ai-provider-api-key.adoc[] * xref:url-parameter-for-the-ai-provider.adoc[] -* xref:mounting-secrets.adoc[] \ No newline at end of file +* xref:changing-the-ai-tool-on-a-workspace.adoc[] +* xref:mounting-secrets.adoc[] From 83a4f6ea09dd7e598321bc1407230669b1c3c18b Mon Sep 17 00:00:00 2001 From: Oleksii Orel Date: Mon, 11 May 2026 17:38:07 +0300 Subject: [PATCH 4/4] fix: use correct Antora family prefix for Tech-Preview snippet include Replace examples/ path with example$ family prefix required by Antora for including files from the examples/ directory. Assisted-by: Claude Sonnet 4.6 Signed-off-by: Oleksii Orel --- .../administration-guide/pages/configuring-ai-providers.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/administration-guide/pages/configuring-ai-providers.adoc b/modules/administration-guide/pages/configuring-ai-providers.adoc index 8d64468985..bacf98d1b2 100644 --- a/modules/administration-guide/pages/configuring-ai-providers.adoc +++ b/modules/administration-guide/pages/configuring-ai-providers.adoc @@ -8,7 +8,7 @@ = Configure AI providers :FeatureName: The AI provider feature -include::examples/snip_che-technology-preview.adoc[] +include::example$snip_che-technology-preview.adoc[] [role="_abstract"] Register one or more AI providers in {prod-short} so that developers can select and use AI coding assistants when creating workspaces.