diff --git a/modules/administration-guide/nav.adoc b/modules/administration-guide/nav.adoc index 645f64c105..7eac4f8ce5 100644 --- a/modules/administration-guide/nav.adoc +++ b/modules/administration-guide/nav.adoc @@ -93,6 +93,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-consolelink-icon.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..d7aba70b03 --- /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: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 a755b3fa02..feccd8d0af 100644 --- a/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc +++ b/modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc @@ -100,3 +100,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..e566dd483b --- /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:end-user-guide:using-ai-assistants-in-workspaces.adoc[] diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index 4d522887c0..f848c05010 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[] @@ -35,6 +36,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..feeb2baa78 --- /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 323de64749..add623dfa1 100644 --- a/modules/end-user-guide/pages/mounting-secrets.adoc +++ b/modules/end-user-guide/pages/mounting-secrets.adoc @@ -86,3 +86,8 @@ $ mvn --settings /home/user/.m2/settings.xml clean install ---- ==== + + +.Additional resources + +* 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. ====