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..7c3e09c696 --- /dev/null +++ b/modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc @@ -0,0 +1,114 @@ +:_content-type: REFERENCE +: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 +:page-aliases: + +[id="ai-provider-api-key-secret-reference"] += AI provider API key secret reference + +[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 + +[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 (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. + +== 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`). 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. +|=== + +== 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[Devfile 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..bacf98d1b2 --- /dev/null +++ b/modules/administration-guide/pages/configuring-ai-providers.adoc @@ -0,0 +1,112 @@ +:_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, gemini, claude, configmap, ai-tool-registry, api key +:navtitle: Configuring AI providers +:page-aliases: + +[id="configuring-ai-providers"] += Configure AI providers + +:FeatureName: The AI provider feature +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. + +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. + +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 + +* 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 18c9c36cf4..67375c870a 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,9 @@ ** 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: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 new file mode 100644 index 0000000000..78d06b7294 --- /dev/null +++ b/modules/end-user-guide/pages/configuring-an-ai-provider-api-key.adoc @@ -0,0 +1,58 @@ +:_content-type: PROCEDURE +: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 +:page-aliases: + +[id="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 + +* Your administrator has enabled at least one AI provider. +* You have a valid API key from your AI provider. + +.Procedure + +. 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*. ++ +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 that the tool binary is in `PATH` and the API key variable is set: ++ +[subs="+quotes"] +---- +$ 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. + +.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..2b780e463c --- /dev/null +++ b/modules/end-user-guide/pages/url-parameter-for-the-ai-provider.adoc @@ -0,0 +1,26 @@ +:_content-type: CONCEPT +: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: + +[id="url-parameter-for-the-ai-provider"] += URL parameter for the AI provider + +[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: + +[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..dee30039d3 --- /dev/null +++ b/modules/end-user-guide/pages/using-ai-assistants-in-workspaces.adoc @@ -0,0 +1,36 @@ +:_content-type: CONCEPT +: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 +:page-aliases: + +[id="using-ai-assistants-in-workspaces"] += AI assistants in workspaces + +[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. + +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. + +== 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. + +.Additional resources + +* xref:configuring-an-ai-provider-api-key.adoc[] +* xref:url-parameter-for-the-ai-provider.adoc[] +* xref:changing-the-ai-tool-on-a-workspace.adoc[] +* xref:mounting-secrets.adoc[] 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. ====