Install the recommended AI assistant configuration in every workspace
Configure Che to install a recommended module in every workspace at startup with Lola, a module manager for AI assistant skills, commands, and agents. Developers can replace the module with their own or disable the installation.
The configuration uses two objects and requires no change to the che-operator or to the DevWorkspace operator:
-
An init container,
lola-init, that every workspace pod runs before the tools container. The container installs the module with Lola into/home/user. -
A
ConfigMapwith the module URL and ref. The che-operator copies theConfigMapto every namespace and mounts it as environment variables.
-
An active
kubectlsession with administrative permissions to the destination Kubernetes cluster. See Overview of kubectl. -
The workspace defines the
persistent-homevolume. Che does not define it when any of the following is true:-
spec.devEnvironments.persistUserHome.enabledisfalse. -
A container in the devfile already mounts a volume at
/home/user/. -
The workspace uses ephemeral storage and
init-persistent-homeis not configured inspec.devEnvironments.initContainers, which is the default.See Persistent user home.
-
-
The module repository is prepared as described in Prepare a Lola module for Che workspaces.
-
The image
quay.io/che-incubator/lola-initis available to every namespace. The image is public and multi-architecture. -
Docker with the
buildxplugin, orskopeo, is installed on the machine where you run thekubectlcommands.
-
Get the digest of the multi-architecture image index:
$ docker buildx imagetools inspect quay.io/che-incubator/lola-init:latest
Alternatively, with Skopeo:
$ skopeo inspect --format '{{.Digest}}' docker://quay.io/che-incubator/lola-init:latestUse the digest of the image index in the
imagefield of the init container. -
Create the
ConfigMapwith the module URL and ref in theeclipse-chenamespace:apiVersion: v1 kind: ConfigMap metadata: name: lola-config-default namespace: eclipse-che labels: app.kubernetes.io/part-of: che.eclipse.org app.kubernetes.io/component: workspaces-config annotations: controller.devfile.io/mount-as: env controller.devfile.io/mount-on-start: "true" data: LOLA_DEFAULT_REPO_URL: https://github.com/<org>/<module-repo>.git LOLA_DEFAULT_REPO_REF: main-
Replace the URL and the ref with the values of your module.
-
Remove
LOLA_DEFAULT_REPO_REFto install the default branch of the repository. -
Keep both labels. They make the che-operator synchronize the
ConfigMapto every namespace. -
Keep the
mount-on-startannotation. It stops the che-operator from adding theConfigMapto a workspace pod that is already running, which would restart the workspace. The configuration applies at the next start instead.
-
-
Add the init container to the
eclipse-checustom resource. A merge patch replaces the whole list, so the patch type depends on whether the list is empty:$ kubectl get checluster eclipse-che -n eclipse-che -o jsonpath='{.spec.devEnvironments.initContainers}'-
If the command prints nothing, add the entry with a merge patch:
$ kubectl patch checluster eclipse-che -n eclipse-che --type merge -p \ '{"spec":{"devEnvironments":{"initContainers":[{"name":"lola-init","image":"quay.io/che-incubator/lola-init@sha256:<digest>","imagePullPolicy":"IfNotPresent","workingDir":"/home/user","volumeMounts":[{"name":"persistent-home","mountPath":"/home/user/"}]}]}}}' -
Otherwise, append the entry with a JSON patch:
$ kubectl patch checluster eclipse-che -n eclipse-che --type json -p \ '[{"op":"add","path":"/spec/devEnvironments/initContainers/-","value":{"name":"lola-init","image":"quay.io/che-incubator/lola-init@sha256:<digest>","imagePullPolicy":"IfNotPresent","workingDir":"/home/user","volumeMounts":[{"name":"persistent-home","mountPath":"/home/user/"}]}}]'
-
-
Start a workspace. Workspaces that were running before the change keep their pod and get the init container at their next start.
-
Confirm that the workspace pod contains the init container:
$ kubectl get pod -n <user-namespace> -l controller.devfile.io/devworkspace_name=<workspace-name> \ -o jsonpath='{.items[0].spec.initContainers[*].name}' -
Read the init container log:
$ kubectl logs -n <user-namespace> -l controller.devfile.io/devworkspace_name=<workspace-name> -c lola-init
A successful installation reports the following line:
[lola-init] ok module=<module-name> origin=default mode=install warnings=0 agents=<assistant-list>
-
In the workspace,
/home/user/.lola/init-statuscontains the same result with a UTC timestamp and the module URL added.The mode is
mode=installon the first start,mode=updatewhen the repository, the ref and the set of assistants are the same as last time, andmode=switchwhen one of them changed.
Managing the recommended configuration
-
Change the module or the ref: edit the
ConfigMap. The che-operator updates the copies in the user namespaces and the change applies at the next workspace start. A changed URL or ref removes the previous module and installs the new one. -
Select the AI assistants: add
LOLA_AGENTSto the environment of the init container. See AI assistant configuration reference. -
Update the image: read the new index digest from the registry and replace it in the
eclipse-checustom resource. Do not use a digest from a build log.
Removing the recommended configuration
-
Roll back: remove your entry from
spec.devEnvironments.initContainersand delete theConfigMap. Workspaces stop receiving the configuration at their next start. Content that is already installed in user homes remains.List the entries and note the position of
lola-init, counting from0:$ kubectl get checluster eclipse-che -n eclipse-che \ -o jsonpath='{.spec.devEnvironments.initContainers[*].name}'Remove that position, then delete the
ConfigMap:$ kubectl patch checluster eclipse-che -n eclipse-che --type json \ -p '[{"op":"remove","path":"/spec/devEnvironments/initContainers/<index>"}]' $ kubectl delete configmap lola-config-default -n eclipse-cheWhen
lola-initis the only entry, removing the wholeinitContainerskey has the same effect. With other init containers in the list, remove only the entry oflola-init: removing0deletes the first entry, which is not necessarilylola-init.
|
The che-operator updates the synced copy in every namespace, but it does not restart the running workspaces. The change applies at the next workspace start. To try the configuration on a few workspaces first, add the |
A failure in the init script does not block the workspace start.
- The workspace starts without the configuration
-
The container records the failure and its reason in
/home/user/.lola/init-status. The most common cause is an unreachable repository. - The container writes no status file
-
It cannot write to the home. Check the
persistent-homevolume and its permissions. - The log reports that no configuration repository is set
-
Neither
LOLA_REPO_URLnorLOLA_DEFAULT_REPO_URLis set. The container exits without installing anything. - A Lola command hangs
-
Each command runs under a 120-second timeout. Set
LOLA_TIMEOUTon the init container to change it, and0disables the timeout. - The workspace fails to start
-
The container cannot start. Check the DevWorkspace message, such as
container 'lola-init' references undefined volume 'persistent-home'when the persistent user home is disabled.