升级

从 Workbench 集群插件迁移

从 v0.2.0 开始,Workbench 以 OLM Helm operator 的形式交付,而不再作为集群插件交付。这两种形式之间无法原位升级。

  1. 备份现有的 Workbench 资源:

    kubectl get workspacekinds,workspaces -A -o yaml > workbench-backup.yaml
  2. 在管理员 > Marketplace > 集群插件中,卸载较早的 Workbench 集群插件。保留用户 PVC、保留的 WorkspaceKind 资源以及 aml-workbench-config ConfigMap;operator 会接管或重新应用这些资源。

  3. 根据版本兼容性安装或升级 Alauda AI Operator(aml-operator)。对于 v0.2.0 迁移,请使用 v2.8.1;此版本会自动修正 Workbench-CR 命名空间问题。

  4. 安装已上传的 Workbench operator 版本,然后在 kubeflow 命名空间中创建其 Workbench 自定义资源。不要在 aml-operator 命名空间或其他命名空间中创建 CR。有关清单和标准安装路径,请参阅安装 Workbench。

  5. 验证现有 Workspace 及其 PVC 仍然存在,然后创建并连接到测试 Workbench。在宣布迁移完成之前,完成以下迁移步骤。

如果先前的安装依赖 Elyra KFP 运行 URL 重定向,请在 Workbench CR 中设置 spec.global.istio.enabled: true。Istio 集成是可选的,默认处于禁用状态。

迁移现有 Workspace

当前的 Workbench 控制器会使用 ws- 前缀创建每个 Workspace Service。例如,名为 jupyter 的 Workspace 使用 Service ws-jupyter。Workbench Skipper 路由使用该 Service 名称。

由较早控制器创建的 Workspace 会保留以 Workspace 命名的现有 Service。Kubernetes Service 无法重命名。如果没有当前控制器提供的迁移,新路由可能会返回 502,因为 ws-<workspace-name> 不存在。

Workbench Operator 及其 workspace-controller 升级到包含此迁移的版本后,控制器会自动迁移每个由控制器管理的旧 Service:

  1. 使用现有 Service 的相同选择器和端口创建 ws-<workspace-name>。
  2. 在下一次协调时,删除旧的 <workspace-name> Service。

Service 迁移不会重启或删除 Workspace Pod 或 PVC。临时重叠可确保旧 Service 在新 Service 创建之前仍然可用。operator 升级所应用的其他更改(例如在受管理的 WorkspaceKind 中使用新镜像)仍可能重启 Pod;PVC 会得到保留。

在验证 Service 之前,找到 Workbench 自定义资源和 OLM operator 部署:

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

将包含 Workbench 自定义资源的命名空间作为 <workbench-namespace>。创建自定义资源时会选择此命名空间,Helm release、hook Job 和 workspace-controller 也会在此命名空间中运行。它不一定命名为 workbench-operator。将包含 workbench-operator-controller-manager 的命名空间作为 <operator-namespace>。

确保 Workbench operand 已完成协调。Succeeded OLM CSV 仅确认 operator 正在运行;它不能确认 Workbench release 已成功应用:

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

仅当 Deployed=True 和 ReleaseFailed 不是 True 时,才继续操作。如果 release 失败,请在测试 Service 迁移之前检查 operator 日志、hook Job 以及两个可能的控制器命名空间:

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

成功升级后,workspace-controller-controller-manager 会在 <workbench-namespace> 中运行。在命名空间切换失败期间,验证 webhook 可能指向 <workbench-namespace>,而唯一就绪的控制器仍位于较早的命名空间中。重试 release 之前,验证新的 webhook Service 是否具有 endpoint:

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

解决正在使用的 WorkspaceKind 选项失败问题

当某个 Workspace 选择了某个 ID 时,imageConfig 或 podConfig 选项的 spec 无法更改或删除。如果升级 hook 报告某个选项正在使用,请在 operator 或 chart 中修复受管理的 WorkspaceKind,而不是删除 Workspace 或禁用准入验证。

使用以下迁移模式:

  1. 保持旧选项 ID 和 spec 不变。可以隐藏其 spawner 条目,使新 Workspace 无法直接选择它。

  2. 添加包含新镜像或资源配置的新选项 ID。如果旧 ID 是默认值,请将 spawner.default 更改为新 ID。

  3. 添加从旧选项 ID 到新 ID 的重定向。例如,以下经过删节的 imageConfig 展示了所需的迁移模式;保留所有现有的必需 spawner 和 spec 字段:

    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.

    资源设置发生更改时,对 podConfig.values 应用相同的模式。

  4. 发布或安装修正后的 operator 或 chart,并等待 Workbench release 完成协调。正在运行的 Workspace 会继续使用旧选项,并在 status.podTemplateOptions 下使用新 ID 报告 pendingRestart=true。

    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. 从 Workbench 页面重启每个受影响的 Workspace。使用 spec.deferUpdates=false 时,控制器会在 Workspace 暂停期间将所选选项更改为重定向目标,然后启动替换 Pod。PVC 会得到保留。

  6. 验证没有 Workspace 选择旧 ID。仅在其使用量降为零后的后续 operator 或 chart release 中删除旧选项。

修正后的 release 运行正常后,再次验证 Deployed=True 和 ReleaseFailed 不是 True,然后再继续操作。

验证 Service 迁移

列出每个 Workspace 及其由控制器管理的 Service:

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

对于命名空间 <namespace> 中名为 <workspace-name> 的每个 Workspace,验证对应的 Service 是否命名为 ws-<workspace-name>:

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

如果新 Service 尚未出现,请确认 workspace-controller 正在运行并检查其日志。不要手动重命名 Service;Kubernetes 不支持 Service 重命名。

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

恢复旧版 Jupyter Workspace URL 前缀

较早保留的 Jupyter WorkspaceKind 资源可以在不包含 /aml 段的情况下设置 NB_PREFIX 和 NOTEBOOK_BASE_URL。浏览器 URL 包含 /clusters/<cluster>/aml/aml-workbench/...,因此即使这些 Workspace 已完成 Service 迁移,也可能无法正确加载。

检查保留的 WorkspaceKind 中的环境配置:

kubectl get workspacekind <workspacekind-name> -o yaml

对于旧版 Jupyter WorkspaceKind,运行 kubectl edit workspacekind <workspacekind-name>,并仅更新以下值以包含 /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" }}`}}

保存 WorkspaceKind,然后从 Workbench 页面重启每个受影响的 Workspace,使 Pod 接收新的环境变量。其 PVC 会得到保留。最后,使用经过身份验证的浏览器会话进行连接,并确认 Workspace 打开时不会返回 502 响应或错误的资源 URL。未经身份验证的请求可能会返回预期的 OAuth 403 登录响应,因此无法验证 Workspace 访问权限。

从 Kubeflow Notebook 迁移

Workbench 不兼容“Kubeflow Notebook”(Alauda AI <= 1.3)。您需要创建新的“workbench”实例,“Kubeflow Notebook”将移动到左侧导航栏中的“Advanced - Kubeflow”。

WARNING

我们建议迁移到 Workbench,因为“Kubeflow Notebook”将在即将发布的上游 Kubeflow 版本中弃用。

NOTE

您可以在 Alauda AI 1.3 中保留“Kubeflow Notebook”实例使用的 PVC。删除 Notebook 实例,并将 PVC 挂载到新的 Workbench 实例中,这样 Notebook 实例中的数据仍然可用。(注意:容器中的数据将会丢失,就像使用 pip install 将软件包安装到系统而不是虚拟环境中时一样。)

操作步骤

  1. 登录并打开 Alauda AI 页面。
  2. 前往 Workbench 打开列表。
  3. 点击 创建,然后填写必填字段。
  4. 在 主目录 中,选择之前 Notebook 使用的 PVC。