Skip to content

Commit 0e049f3

Browse files
olexii4olexii4
committed
docs: add AI provider configuration and usage docs
- Admin guide: configuring AI providers via ConfigMap, API key Secret reference, CheCluster CR fields for AI registry - User guide: using AI assistants, configuring API keys (Create Workspace + User Preferences), AI provider URL parameter, workspace list column, changing AI tool on existing workspaces Assisted-by: Claude Opus 4.6 Signed-off-by: Oleksii Orel <oorel@redhat.com>
1 parent dc3a7e0 commit 0e049f3

12 files changed

Lines changed: 457 additions & 1 deletion

‎modules/administration-guide/nav.adoc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -93,6 +93,8 @@
9393
*** xref:configuring-default-editor.adoc[]
9494
*** xref:concealing-editors.adoc[]
9595
*** xref:configuring-editors-download-urls.adoc[]
96+
*** xref:configuring-ai-providers.adoc[]
97+
**** xref:ai-provider-api-key-secret-reference.adoc[]
9698
*** xref:customizing-openshift-che-consolelink-icon.adoc[]
9799
** xref:managing-identities-and-authorizations.adoc[]
98100
*** xref:configuring-oauth-for-git-providers.adoc[]

‎modules/administration-guide/pages/ai-provider-api-key-secret-reference.adoc‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
:_content-type: REFERENCE
2+
: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.
3+
:keywords: administration, ai, api key, secret, kubernetes, devworkspace controller, environment variable, mount
4+
:navtitle: AI Provider API Key Secret Reference
5+
:page-aliases:
6+
7+
[id="ai-provider-api-key-secret-reference"]
8+
= AI provider API key Secret reference
9+
10+
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.
11+
12+
== Secret schema
13+
14+
[source,yaml,subs="+quotes,+attributes"]
15+
----
16+
apiVersion: v1
17+
kind: Secret
18+
metadata:
19+
name: ai-provider-gemini-api-key <1>
20+
namespace: __<user-namespace>__
21+
labels:
22+
controller.devfile.io/mount-to-devworkspace: 'true' <2>
23+
controller.devfile.io/watch-secret: 'true' <3>
24+
che.eclipse.org/ai-provider-id: google-gemini <4>
25+
annotations:
26+
controller.devfile.io/mount-as: env <5>
27+
type: Opaque
28+
data:
29+
GEMINI_API_KEY: __<base64-encoded-api-key>__ <6>
30+
----
31+
<1> Secret name is derived as `ai-provider-` + `envVarName.toLowerCase().replace(/_/g, '-')`. For `GEMINI_API_KEY` the name is `ai-provider-gemini-api-key`.
32+
<2> Instructs the DevWorkspace Controller to mount this Secret into all `DevWorkspace` containers in the namespace.
33+
<3> Instructs the DevWorkspace Controller to watch for Secret changes and re-mount without a workspace restart.
34+
<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.
35+
<5> Mounts the Secret data keys as environment variables (not as files).
36+
<6> The data key is the environment variable name. The value is base64-encoded. The variable is injected directly into all workspace containers.
37+
38+
== Label and annotation reference
39+
40+
[cols="1,1,2",options="header"]
41+
|===
42+
| Label / Annotation | Value | Purpose
43+
44+
| `controller.devfile.io/mount-to-devworkspace`
45+
| `'true'`
46+
| Causes the DevWorkspace Controller to mount this Secret into every `DevWorkspace` in the namespace.
47+
48+
| `controller.devfile.io/watch-secret`
49+
| `'true'`
50+
| The DevWorkspace Controller re-mounts the Secret when its data changes, without requiring a workspace restart.
51+
52+
| `controller.devfile.io/mount-as`
53+
| `env`
54+
| 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.
55+
56+
| `che.eclipse.org/ai-provider-id`
57+
| Sanitized provider ID (for example, `google-gemini`). Slashes in the provider `id` are replaced with dashes.
58+
| Used by the {prod-short} dashboard to identify and list AI provider key Secrets when rendering the AI Selector widget.
59+
|===
60+
61+
== Secret naming convention
62+
63+
Secret names follow the pattern:
64+
65+
----
66+
ai-provider-<envVarName-lowercased-underscores-as-dashes>
67+
----
68+
69+
Examples:
70+
71+
[cols="1,1",options="header"]
72+
|===
73+
| `envVarName` | Secret name
74+
75+
| `GEMINI_API_KEY`
76+
| `ai-provider-gemini-api-key`
77+
78+
| `ANTHROPIC_API_KEY`
79+
| `ai-provider-anthropic-api-key`
80+
81+
| `OPENAI_API_KEY`
82+
| `ai-provider-openai-api-key`
83+
|===
84+
85+
== Manual Secret creation
86+
87+
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:
88+
89+
[subs="+quotes,+attributes"]
90+
----
91+
$ {orch-cli} apply -f - <<EOF
92+
apiVersion: v1
93+
kind: Secret
94+
metadata:
95+
name: ai-provider-gemini-api-key
96+
namespace: __<user-namespace>__
97+
labels:
98+
controller.devfile.io/mount-to-devworkspace: 'true'
99+
controller.devfile.io/watch-secret: 'true'
100+
che.eclipse.org/ai-provider-id: google-gemini
101+
annotations:
102+
controller.devfile.io/mount-as: env
103+
type: Opaque
104+
data:
105+
GEMINI_API_KEY: __<base64-encoded-api-key>__
106+
EOF
107+
----
108+
109+
.Additional resources
110+
111+
* xref:configuring-ai-providers.adoc[]
112+
* xref:mounting-secrets.adoc[Mounting Secrets (end-user guide)]
113+
* link:https://devfile.io/docs/2.2.0/what-is-a-devfile[DevWorkspace Operator documentation]

‎modules/administration-guide/pages/checluster-custom-resource-fields-reference.adoc‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,11 @@ This section describes all fields available to customize the `CheCluster` Custom
1111

1212
* xref:a-minimal-checluster-custom-resource-example[]
1313
* xref:checluster-custom-resource-devEnvironments-settings[]
14+
** xref:checluster-custom-resource-devEnvironments-aiProviders-settings[]
1415
** xref:checluster-custom-resource-devEnvironments-allowedSources-settings[]
1516
** xref:checluster-custom-resource-devEnvironments-containerBuildConfiguration-settings[]
1617
** xref:checluster-custom-resource-devEnvironments-containerRunConfiguration-settings[]
18+
** xref:checluster-custom-resource-devEnvironments-defaultAiProvider-settings[]
1719
** xref:checluster-custom-resource-devEnvironments-defaultNamespace-settings[]
1820
** xref:checluster-custom-resource-devEnvironments-defaultPlugins-settings[]
1921
** xref:checluster-custom-resource-devEnvironments-editorsDownloadUrls-settings[]
@@ -100,3 +102,96 @@ spec:
100102
====
101103

102104
include::example$checluster-properties/checluster-properties.adoc[leveloffset=+1]
105+
106+
[id="ai-tool-registry-configmap-reference"]
107+
== AI tool registry ConfigMap
108+
109+
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:
110+
111+
* `app.kubernetes.io/component=ai-tool-registry`
112+
* `app.kubernetes.io/part-of=che.eclipse.org`
113+
114+
The ConfigMap contains a `registry.json` key with three sections: `providers`, `tools`, and `defaultAiProviders`.
115+
116+
=== Provider fields
117+
118+
[cols="1,1,3",options="header"]
119+
|===
120+
| Field | Type | Description
121+
122+
| `id`
123+
| `string`
124+
| Unique identifier for the provider (for example, `google/gemini`).
125+
126+
| `name`
127+
| `string`
128+
| Display name shown in the dashboard (for example, `Gemini`).
129+
130+
| `publisher`
131+
| `string`
132+
| Publisher name (for example, `Google`).
133+
134+
| `description`
135+
| `string` (optional)
136+
| Short description shown in the provider card.
137+
138+
| `docsUrl`
139+
| `string` (optional)
140+
| URL to the provider's API key documentation, shown as a link in the dashboard.
141+
142+
| `icon`
143+
| `string` (optional)
144+
| URL to the provider's SVG icon.
145+
|===
146+
147+
=== Tool fields
148+
149+
[cols="1,1,3",options="header"]
150+
|===
151+
| Field | Type | Description
152+
153+
| `providerId`
154+
| `string`
155+
| Links the tool to a provider by `id` (for example, `google/gemini`).
156+
157+
| `tag`
158+
| `string`
159+
| Version tag (for example, `next`, `latest`, `3.21`). When multiple tools share the same `providerId`, the dashboard selects by priority: `next` > `latest` > highest semver.
160+
161+
| `name`
162+
| `string`
163+
| Display name for the tool (for example, `Gemini CLI`).
164+
165+
| `url`
166+
| `string`
167+
| URL to the tool's homepage.
168+
169+
| `binary`
170+
| `string`
171+
| Binary name available in `PATH` after injection (for example, `gemini`).
172+
173+
| `pattern`
174+
| `string`
175+
| Injection pattern: `init` (single binary copied to `/injected-tools/bin/`) or `bundle` (full runtime directory copied and symlinked).
176+
177+
| `injectorImage`
178+
| `string`
179+
| Container image used as an init container to copy the tool binary into a shared volume.
180+
181+
| `envVarName`
182+
| `string` (optional)
183+
| Name of the environment variable for the API key (for example, `GEMINI_API_KEY`). This is also the data key in the {kubernetes} Secret.
184+
185+
| `setupCommand`
186+
| `string` (optional)
187+
| One-time setup command run in the editor container at postStart.
188+
|===
189+
190+
=== defaultAiProviders
191+
192+
Optional. A JSON array of provider `id` values that are pre-selected in the AI Selector widget for new workspaces.
193+
194+
.Additional resources
195+
196+
* xref:configuring-ai-providers.adoc[]
197+
* xref:ai-provider-api-key-secret-reference.adoc[]

‎modules/administration-guide/pages/configuring-ai-providers.adoc‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
:_content-type: PROCEDURE
2+
:description: Enable and configure AI provider support in Eclipse Che so that users can select an AI assistant when creating workspaces.
3+
:keywords: administration, ai, ai provider, gemini, claude, configmap, ai-tool-registry, api key
4+
:navtitle: Configuring AI Providers
5+
:page-aliases:
6+
7+
[id="configuring-ai-providers"]
8+
= Configuring AI providers
9+
10+
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.
11+
12+
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.
13+
14+
.Prerequisites
15+
16+
* An active `{orch-cli}` session with administrative permissions to the destination {orch-name} cluster. See {orch-cli-link}.
17+
* The {prod-operator} is installed and a `{prod-checluster}` custom resource exists in the `{prod-namespace}` namespace.
18+
19+
.Procedure
20+
21+
. Create a `registry.json` file defining providers, tools, and default selections:
22+
+
23+
[source,json,subs="+quotes"]
24+
----
25+
{
26+
"providers": [
27+
{
28+
"id": "google/gemini",
29+
"name": "Gemini",
30+
"publisher": "Google",
31+
"description": "Google Gemini AI assistant for the terminal.",
32+
"docsUrl": "https://ai.google.dev/gemini-api/docs/quickstart",
33+
"icon": "https://example.com/gemini-icon.svg"
34+
},
35+
{
36+
"id": "anthropic/claude",
37+
"name": "Claude",
38+
"publisher": "Anthropic",
39+
"description": "Anthropic Claude AI coding assistant for terminal.",
40+
"docsUrl": "https://docs.anthropic.com/claude/reference/getting-started-with-the-api",
41+
"icon": "https://example.com/claude-icon.svg"
42+
}
43+
],
44+
"tools": [
45+
{
46+
"providerId": "google/gemini", <1>
47+
"tag": "next", <2>
48+
"name": "Gemini CLI",
49+
"url": "https://ai.google.dev/gemini-api/docs",
50+
"binary": "gemini", <3>
51+
"pattern": "bundle", <4>
52+
"injectorImage": "quay.io/example/gemini-cli:next", <5>
53+
"envVarName": "GEMINI_API_KEY" <6>
54+
},
55+
{
56+
"providerId": "anthropic/claude",
57+
"tag": "next",
58+
"name": "Claude Code",
59+
"url": "https://claude.ai/code",
60+
"binary": "claude",
61+
"pattern": "init",
62+
"injectorImage": "quay.io/example/claude-code:next",
63+
"envVarName": "ANTHROPIC_API_KEY"
64+
}
65+
],
66+
"defaultAiProviders": ["google/gemini"] <7>
67+
}
68+
----
69+
<1> Links the tool to a provider by the provider's `id`.
70+
<2> Version tag. When multiple tools share the same `providerId`, the dashboard selects by tag priority: `next` > `latest` > highest semver.
71+
<3> Binary name available in `PATH` after injection.
72+
<4> Injection pattern: `init` copies a single binary; `bundle` copies a full runtime directory and creates a symlink.
73+
<5> Container image used as an init container to copy the tool binary into a shared volume.
74+
<6> Environment variable name for the API key. The dashboard creates a {kubernetes} Secret with this key.
75+
<7> Optional. List of provider IDs pre-selected in the AI Selector widget for new workspaces.
76+
77+
. Create the `ConfigMap` in the `{prod-namespace}` namespace with the required labels:
78+
+
79+
[subs="+quotes,+attributes"]
80+
----
81+
$ {orch-cli} create configmap ai-tool-registry \
82+
--from-file=registry.json=registry.json \
83+
-n {prod-namespace} \
84+
--dry-run=client -o yaml | \
85+
{orch-cli} label --local -f - \
86+
app.kubernetes.io/component=ai-tool-registry \
87+
app.kubernetes.io/part-of=che.eclipse.org \
88+
-o yaml | \
89+
{orch-cli} apply -f -
90+
----
91+
92+
.Verification
93+
94+
. Open the {prod-short} dashboard.
95+
. Navigate to *Create Workspace*.
96+
. Verify that an *AI Provider* section is visible, listing the providers you configured.
97+
98+
[NOTE]
99+
====
100+
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.
101+
====
102+
103+
[NOTE]
104+
====
105+
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.
106+
====
107+
108+
.Additional resources
109+
110+
* xref:ai-provider-api-key-secret-reference.adoc[]
111+
* xref:using-ai-assistants-in-workspaces.adoc[]

‎modules/end-user-guide/nav.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
**** xref:url-parameter-for-memory-limit.adoc[]
1616
**** xref:url-parameter-for-cpu-limit.adoc[]
1717
**** xref:url-parameter-for-the-existing-workspace-name.adoc[]
18+
**** xref:url-parameter-for-the-ai-provider.adoc[]
1819
** xref:starting-a-workspace-from-a-raw-devfile-url.adoc[]
1920
** xref:basic-actions-you-can-perform-on-a-workspace.adoc[]
2021
** xref:restoring-workspaces-from-backups.adoc[]
@@ -35,6 +36,8 @@
3536
** xref:microsoft-visual-studio-code-open-source-ide.adoc[]
3637
** xref:connect-visual-studio-code-to-che-workspace.adoc[]
3738
** xref:defining-a-common-ide.adoc[]
39+
* xref:using-ai-assistants-in-workspaces.adoc[]
40+
** xref:configuring-an-ai-provider-api-key.adoc[]
3841
* xref:using-credentials-and-configurations-in-workspaces.adoc[]
3942
** xref:mounting-secrets.adoc[]
4043
*** xref:creating-image-pull-secrets.adoc[]

0 commit comments

Comments
 (0)