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 ConfigMap with the module URL and ref. The che-operator copies the ConfigMap to every namespace and mounts it as environment variables.

Prerequisites
  • An active kubectl session with administrative permissions to the destination Kubernetes cluster. See Overview of kubectl.

  • The workspace defines the persistent-home volume. Che does not define it when any of the following is true:

    • spec.devEnvironments.persistUserHome.enabled is false.

    • A container in the devfile already mounts a volume at /home/user/.

    • The workspace uses ephemeral storage and init-persistent-home is not configured in spec.devEnvironments.initContainers, which is the default.

  • The module repository is prepared as described in Prepare a Lola module for Che workspaces.

  • The image quay.io/che-incubator/lola-init is available to every namespace. The image is public and multi-architecture.

  • Docker with the buildx plugin, or skopeo, is installed on the machine where you run the kubectl commands.

Procedure
  1. 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:latest

    Use the digest of the image index in the image field of the init container.

  2. Create the ConfigMap with the module URL and ref in the eclipse-che namespace:

    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_REF to install the default branch of the repository.

    • Keep both labels. They make the che-operator synchronize the ConfigMap to every namespace.

    • Keep the mount-on-start annotation. It stops the che-operator from adding the ConfigMap to a workspace pod that is already running, which would restart the workspace. The configuration applies at the next start instead.

  3. Add the init container to the eclipse-che custom 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/"}]}}]'
  4. Start a workspace. Workspaces that were running before the change keep their pod and get the init container at their next start.

Verification
  • 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-status contains the same result with a UTC timestamp and the module URL added.

    The mode is mode=install on the first start, mode=update when the repository, the ref and the set of assistants are the same as last time, and mode=switch when one of them changed.

  • 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_AGENTS to 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-che custom resource. Do not use a digest from a build log.

  • Roll back: remove your entry from spec.devEnvironments.initContainers and delete the ConfigMap. 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 from 0:

    $ 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-che

    When lola-init is the only entry, removing the whole initContainers key has the same effect. With other init containers in the list, remove only the entry of lola-init: removing 0 deletes the first entry, which is not necessarily lola-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 controller.devfile.io/mount-to-devworkspace-include annotation to the ConfigMap with a comma-separated list of workspace name patterns, such as lola-test*.

Troubleshooting

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-home volume and its permissions.

The log reports that no configuration repository is set

Neither LOLA_REPO_URL nor LOLA_DEFAULT_REPO_URL is set. The container exits without installing anything.

A Lola command hangs

Each command runs under a 120-second timeout. Set LOLA_TIMEOUT on the init container to change it, and 0 disables 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.