#Upgrade

#Migrating from the Workbench Cluster Plugin

Starting with v0.2.0, Workbench is delivered as an OLM Helm operator instead of a Cluster Plugin. There is no in-place upgrade between these forms.

1. Back up the existing Workbench resources:

   kubectl get workspacekinds,workspaces -A -o yaml > workbench-backup.yaml

2. In Administrator > Marketplace > Cluster Plugins, uninstall the earlier Workbench cluster plugin. Preserve user PVCs, retained WorkspaceKind resources, and the aml-workbench-config ConfigMap; the operator adopts or reapplies these resources.

3. Install or upgrade the Alauda AI Operator (aml-operator) according to Version Compatibility. For the v0.2.0 migration, use v2.8.1; this version automatically corrects the Workbench-CR namespace issue.

4. Install the Workbench operator version that you uploaded, then create its Workbench custom resource in the kubeflow namespace. Do not create the CR in the aml-operator namespace or in another namespace. For the manifest and normal installation path, see Install Workbench.

5. Verify the existing Workspaces and their PVCs are still present, then create and connect to a test Workbench. Complete the migration steps below before declaring the migration complete.

If the previous installation relied on the Elyra KFP run-URL redirect, set spec.global.istio.enabled: true in the Workbench CR. Istio integration is optional and disabled by default.

#Migrate Existing Workspaces

The current Workbench controller creates each Workspace Service with the ws- prefix. For example, a Workspace named jupyter uses the Service ws-jupyter. The Workbench Skipper routes use that Service name.

Workspaces that were created by an earlier controller keep their existing Service named after the Workspace. Kubernetes Services cannot be renamed. Without the migration supplied by the current controller, the new route can return 502 because ws-<workspace-name> does not exist.

After the Workbench Operator and its workspace-controller have been upgraded to a version that includes this migration, the controller automatically migrates every controller-owned legacy Service:

1. It creates ws-<workspace-name> with the same selector and ports as the existing Service.
2. On the next reconciliation, it deletes the old <workspace-name> Service.

The Service migration does not restart or delete the Workspace Pod or PVC. The temporary overlap ensures that the old Service remains available until the new one exists. Other changes applied by the operator upgrade, such as a new image in a managed WorkspaceKind, can still restart the Pod; the PVC is preserved.

Before verifying the Services, locate the Workbench custom resource and the OLM operator deployment:

kubectl get workbench -A
kubectl get deployment -A | grep workbench-operator-controller-manager

Use the namespace containing the Workbench custom resource as <workbench-namespace>. This namespace is selected when the custom resource is created and is also where the Helm release, hook Jobs, and workspace-controller run. It is not necessarily named workbench-operator. Use the namespace containing workbench-operator-controller-manager as <operator-namespace>.

Ensure that the Workbench operand has completed its reconciliation. A Succeeded OLM CSV only confirms that the operator is running; it does not confirm that the Workbench release was applied successfully:

kubectl -n <workbench-namespace> get workbench <instance-name> \
  -o jsonpath='{range .status.conditions[*]}{.type}={.status}{"\n"}{end}'

Proceed only when Deployed=True and ReleaseFailed is not True. If the release failed, inspect the operator logs, hook Jobs, and both possible controller namespaces before testing Service migration:

kubectl -n <operator-namespace> logs deployment/workbench-operator-controller-manager --tail=200
kubectl -n <workbench-namespace> get jobs --sort-by=.metadata.creationTimestamp
kubectl get deployment -A | grep workspace-controller-controller-manager

After a successful upgrade, workspace-controller-controller-manager runs in <workbench-namespace>. During a failed namespace handoff, the validating webhook can point to <workbench-namespace> while the only ready controller is still in its earlier namespace. Verify that the new webhook Service has an endpoint before retrying the release:

kubectl -n <workbench-namespace> get deployment workspace-controller-controller-manager
kubectl -n <workbench-namespace> get endpointslice \
  -l kubernetes.io/service-name=workspace-controller-webhook-service

#Resolve In-use WorkspaceKind Option Failures

An imageConfig or podConfig option's spec cannot be changed or removed while a Workspace selects its ID. If an upgrade hook reports that an option is in use, fix the managed WorkspaceKind in the operator or chart instead of deleting the Workspace or disabling admission validation.

Use this migration pattern:

1. Keep the old option ID and spec unchanged. You can hide its spawner entry so new Workspaces cannot select it directly.

2. Add a new option ID containing the new image or resource configuration. If the old ID was the default, change spawner.default to the new ID.

3. Add a redirect from the old option ID to the new ID. For example, this abridged imageConfig shows the required migration pattern; retain all existing required spawner and spec fields:

   imageConfig:
     spawner:
       default: <new-id>
     values:
       - id: <old-id>
         spawner:
           # Keep the existing fields, but optionally hide this entry.
           hidden: true
         # Keep the existing spec unchanged.
         redirect:
           to: <new-id>
           message:
             level: Info
             text: Restart this Workspace to apply the updated image.
       - id: <new-id>
         # Copy the old spawner and spec, then apply the new settings only here.

   Apply the same pattern to podConfig.values when resource settings change.

4. Publish or install the corrected operator or chart and wait for the Workbench release to reconcile. Running Workspaces continue using the old option and report pendingRestart=true with the new ID under status.podTemplateOptions.

   kubectl get workspace -A \
     -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,KIND:.spec.kind,IMAGE_CONFIG:.spec.podTemplate.options.imageConfig,POD_CONFIG:.spec.podTemplate.options.podConfig,PENDING_RESTART:.status.pendingRestart'

5. Restart each affected Workspace from the Workbench page. With spec.deferUpdates=false, the controller changes the selected option to the redirect target while the Workspace is paused, then starts the replacement Pod. The PVC is preserved.

6. Verify that no Workspace selects the old ID. Remove the old option only in a later operator or chart release after its usage reaches zero.

After the corrected release is healthy, verify again that Deployed=True and ReleaseFailed is not True before continuing.

#Verify the Service Migration

List every Workspace and its controller-owned Service:

kubectl get workspace -A
kubectl get service -A -l notebooks.kubeflow.org/workspace-name

For each Workspace named <workspace-name> in namespace <namespace>, verify that the matching Service is named ws-<workspace-name>:

kubectl -n <namespace> get service ws-<workspace-name>

If the new Service has not appeared, confirm that workspace-controller is running and inspect its logs. Do not manually rename a Service; Kubernetes does not support Service renames.

kubectl -n <workbench-namespace> get deployment workspace-controller-controller-manager
kubectl -n <workbench-namespace> logs deployment/workspace-controller-controller-manager --tail=200

#Restore a Legacy Jupyter Workspace URL Prefix

Older retained Jupyter WorkspaceKind resources can set NB_PREFIX and NOTEBOOK_BASE_URL without the /aml segment. The browser URL contains /clusters/<cluster>/aml/aml-workbench/..., so those Workspaces can load incorrectly even after their Service migration is complete.

Inspect the environment configuration in the retained WorkspaceKind:

kubectl get workspacekind <workspacekind-name> -o yaml

For a legacy Jupyter WorkspaceKind, run kubectl edit workspacekind <workspacekind-name> and update only these values to include /aml:

spec:
  podTemplate:
    extraEnv:
      - name: NB_PREFIX
        value: /clusters/<cluster>/aml/aml-workbench{{`{{ httpPathPrefix "jupyterlab" }}`}}
      - name: NOTEBOOK_BASE_URL
        value: /clusters/<cluster>/aml/aml-workbench{{`{{ httpPathPrefix "jupyterlab" }}`}}

Save the WorkspaceKind, then restart each affected Workspace from the Workbench page so the Pod receives the new environment variables. Its PVC is preserved. Finally, connect with an authenticated browser session and confirm that the Workspace opens without a 502 response or incorrect asset URLs. An unauthenticated request can return the expected OAuth 403 sign-in response and does not verify Workspace access.

#Migrating from Kubeflow Notebook

Workbench is NOT compatible with "Kubeflow Notebook" (Alauda AI <= 1.3). You need to create new "workbench" instances, the "Kubeflow Notebook" will be moved to "Advanced - Kubeflow" in the left navigation bar.

#Procedure

1. Log in and open the Alauda AI page.
2. Go to Workbench to open the list.
3. Click Create and fill in the required fields.
4. In Home Directory, select the PVC used by the previous Notebook.