AI provider API key Secret reference

The Che dashboard stores each user’s AI provider API key as a Kubernetes Opaque Secret in the user’s personal 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

apiVersion: v1
kind: Secret
metadata:
  name: ai-provider-gemini-api-key  (1)
  namespace: <user-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: <base64-encoded-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 Che 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

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 Che 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-<envVarName-lowercased-underscores-as-dashes>

Examples:

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 kubectl instead of the dashboard UI. Use the same labels and annotations as shown in the schema above:

$ kubectl apply -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
  name: ai-provider-gemini-api-key
  namespace: <user-namespace>
  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: <base64-encoded-api-key>
EOF
Additional resources