使用 Elyra 在 JupyterLab 中运行 Kubeflow Pipelines
Elyra 允许你通过在画布上连接 notebook,在 JupyterLab 中构建可视化 pipeline,然后将该 pipeline 提交到 Kubeflow Pipelines(KFP)。本指南通过一个由两个 notebook 组成的 “hello world” pipeline 演示整个过程,并展示如何在 KFP UI 中验证运行结果。
此工作流使用 KFP v2。每个 notebook 节点都作为容器化的 pipeline 步骤执行,KFP 会将运行产物存储到与 S3 兼容的对象存储中,例如 Ceph Object Storage。
目录
前提条件验证 Namespace KFP Runtime 配置配置 Elyra 元数据挂载挂载到/opt/app-root/runtimes 的 KFP Runtime 配置挂载到 /opt/app-root/pipeline-runtimes 的 Pipeline Runtime 镜像元数据可用的 Elyra Pipeline Runtime 镜像打开 JupyterLab创建两个演示 Notebook在 Elyra 中创建 Pipeline打开 Pipeline Editor添加 Notebook 节点配置节点属性将 Pipeline 提交到 KFP在 Kubeflow Pipelines 中验证运行结果故障排查namespace 在 Kubeflow 中不可见Elyra 未显示 KFP runtime 配置Elyra 中不可用该 runtime imagerun 在 notebook 代码开始前失败Elyra 成功对话框已关闭前提条件
在开始之前,请确保以下平台前提条件已准备就绪:
- 已安装 Alauda AI Workbench,并且你可以创建或打开一个 JupyterLab workbench。有关 workbench 创建步骤,请参见 创建 Workbench。
- 已部署 Kubeflow Base(
kfbase)和 Kubeflow Pipelines(kfp)。有关部署步骤,请参见 安装 Kubeflow 插件。 - 你的 namespace 在 Kubeflow 中可见。如果登录 Kubeflow 后 namespace 仍未出现,请按照 安装 Kubeflow 插件 中的 namespace 绑定说明进行操作。
- 已配置 KFP 对象存储。有关 namespace 侧
kfp-launcher配置,请参见 使用 Kubeflow Pipelines。 - 你使用的 JupyterLab workbench 镜像包含 Elyra 和 KFP SDK 2.x,例如 创建 Workbench 中列出的 Standard Data Science Jupyter 镜像。
- 已将 Elyra runtime 元数据挂载到 workbench 中。runtime 配置会告诉 Elyra 如何提交到 KFP,而 runtime 镜像元数据会告诉 Elyra 每个 pipeline 节点可以使用哪个镜像运行。
code-server workbench 镜像不提供 Elyra 可视化 pipeline 编辑器。若要创建 Elyra pipeline,请使用 JupyterLab 镜像。
验证 Namespace KFP Runtime 配置
在使用 Elyra 之前,请让平台管理员确认 workbench 所在的 namespace 已准备好用于 KFP v2 运行:
- 该 namespace 在 Kubeflow 中可见,并且已与用户绑定。请参见 安装 Kubeflow 插件。
- KFP 已配置为将产物存储到对象存储中。请参见 使用 Kubeflow Pipelines。
本指南不会重复介绍 KFP 安装和对象存储的 manifest。它重点介绍 JupyterLab 中的 Elyra 配置。
配置 Elyra 元数据挂载
这一部分通常由平台管理员完成。JupyterLab workbench 启动时,Elyra 会读取两个不同的元数据目录:
需要预期存在 ..data 路径。Kubernetes 会自动为 ConfigMap 和 Secret 卷创建这种符号链接布局,而 JupyterLab 镜像也按设计遵循该布局。当前针对 /opt/app-root/runtimes 的 PVC 变通方案也需要相同布局,因此在准备 PVC 时需要手动创建 ..data 目录。
在未来的 Workbench 版本中,Workspace 级别的 Secret 挂载将允许直接从 Secret 挂载 /opt/app-root/runtimes。在该支持可用后,你就可以停止使用 PVC 变通方案来存放敏感的 Elyra runtime 配置。
挂载到 /opt/app-root/runtimes 的 KFP Runtime 配置
当前 Workbench 版本不支持在 Workspace 中直接挂载 Secret。由于 Elyra 的 KFP runtime 配置可能包含对象存储凭据,因此请使用专用 PVC 作为临时方案,并将该 PVC 视为敏感数据。
PVC 中必须包含如下文件:
请使用以下 mlops-kfp.json 作为模板。将 namespace、endpoint、bucket 和凭据替换为你自己的值:
如果该 PVC 已挂载到 workbench 中,你可以在 JupyterLab 终端中创建该文件:
将 PVC 挂载到 Workspace 中:
在创建或更新文件后,请重启 workbench,以便 Elyra 可以加载 runtime 配置。
挂载到 /opt/app-root/pipeline-runtimes 的 Pipeline Runtime 镜像元数据
Pipeline runtime 镜像元数据不依赖于具体用户。namespace 级别的 ConfigMap 更适合这一用途,并且可以通过 WorkspaceKind 挂载,这样该类型下所有 JupyterLab workspace 都会使用相同的 runtime 镜像列表。
在每个运行 Elyra pipeline 的 namespace 中创建一个名为 pipeline-runtime-images 的 ConfigMap:
如果你的集群从私有镜像仓库镜像拉取镜像,请将 docker.io/alaudadockerhub/...:<tag> 替换为镜像仓库中的地址。
通过 JupyterLab WorkspaceKind 挂载该 ConfigMap:
ConfigMap 挂载会自动创建 Kubernetes atomic volume 布局。在 pod 内部,Elyra 会看到如下文件:
可用的 Elyra Pipeline Runtime 镜像
Elyra pipeline runtime 镜像发布在 Docker Hub 上的 alaudadockerhub 下。它们与 JupyterLab workbench 镜像不同:workbench 镜像运行的是编写界面,而这些 runtime 镜像运行的是单个 KFP pipeline 节点。
与 创建 Workbench 中描述的附加 workbench 镜像一样,这些 Docker Hub 地址都是公开的源镜像。在私有环境或离线环境中,请先将所需的 pipeline runtime 镜像同步到你的内部镜像仓库,然后更新 pipeline-runtime-images ConfigMap 中的 metadata.image_name 字段,使其指向内部仓库地址。
下表描述了五种常用的 runtime 镜像。包列表仅供参考,基于镜像构建仓库中 runtimes/ 下对应的源目录。
打开 JupyterLab
- 登录 Alauda AI。
- 进入 Workbench。
- 打开现有的 JupyterLab workbench,或者创建一个包含 Elyra 的新 workbench。
- 等待 workbench 状态变为
Running。 - 点击 Connect 打开 JupyterLab。
JupyterLab 打开后,你可以选择在 JupyterLab 终端中验证 KFP SDK 版本:
版本应为 2.x。
创建两个演示 Notebook
这个 hello world pipeline 使用你在 JupyterLab 中直接创建的三个文件:
在 JupyterLab 文件浏览器中,创建一个名为 hello-two-nodes 的文件夹。
在该文件夹内,创建名为 01-hello.ipynb 的第一个 notebook,并添加如下 cell:
创建名为 02-world.ipynb 的第二个 notebook,并添加如下 cell:
先在 JupyterLab 中分别运行这两个 notebook 一次,以确认它们可以在本地执行且没有语法错误。
在 Elyra 中创建 Pipeline
JupyterLab 打开后,请等待主 launcher 页面和 Elyra 面板加载完成。在基于浏览器的验证中,JupyterLab 有时需要几秒钟时间,Pipeline Editor 和 Runtime Images 面板才可用。
打开 Pipeline Editor
- 在 JupyterLab 文件浏览器中打开
hello-two-nodes文件夹。 - 打开 Launcher 选项卡。如果 launcher 不可见,请点击 File > New Launcher。
- 点击 Pipeline Editor。JupyterLab 会打开一个新的未命名 Elyra pipeline 画布。
- 将空白 pipeline 保存为
hello-two-nodes.pipeline,保存在hello-two-nodes文件夹中。
添加 Notebook 节点
- 将
01-hello.ipynb从 JupyterLab 文件浏览器拖到 pipeline 画布上。 - 将
02-world.ipynb从文件浏览器拖到同一画布上。 - 将节点从左到右排列,便于阅读执行顺序。
- 将
01-hello.ipynb的输出端口连接到02-world.ipynb的输入端口。该边表示依赖关系,使第二个 notebook 仅在第一个 notebook 成功后才开始。
配置节点属性
-
单击
01-hello.ipynb节点。 -
打开节点属性面板。根据你的 JupyterLab 布局,属性面板可能显示在画布右侧,或通过节点上下文菜单打开。
-
确认节点文件指向
01-hello.ipynb。 -
将 Runtime Image 设置为你平台上已准备好的某个 Elyra pipeline runtime 镜像,例如:
-
如果该节点包含 CPU、memory、GPU、environment variable、input file 或 output file 字段,对于这个 hello world 示例,请保持默认值不变。
-
单击
02-world.ipynb节点,并重复相同的 Runtime Image 设置。 -
再次保存 pipeline 文件。
对于这个 hello world 示例,该连接仅表示执行依赖关系。如果你的第二个 notebook 必须消费第一个 notebook 创建的文件,请在 Elyra 中配置节点文件依赖和输出,以便文件通过 pipeline artifact 存储进行传递。
将 Pipeline 提交到 KFP
- 在 Elyra pipeline editor 中,点击 Run Pipeline。
- 在运行对话框中,将 Runtime Platform 设置为 Kubeflow Pipelines。
- 选择管理员提供的 KFP v2 runtime 配置,例如
MLOps KFP。 - 输入 pipeline 名称,例如
hello-two-nodes。 - 输入运行名称,或者保留自动生成的运行名称。
- 选择一个已有 experiment,或者创建一个新的 experiment,例如
elyra-demo。 - 检查两个 notebook 节点的 runtime image 值。
- 点击 OK 或 Submit。
提交成功后,Elyra 会显示类似 Job submission to Pipelines succeeded 的对话框。
Elyra 是一个 pipeline 编写和提交界面。提交后,它不会在 JupyterLab 画布内提供持久化的运行历史视图。请使用 Kubeflow Pipelines 查看执行状态。
在 Kubeflow Pipelines 中验证运行结果
-
打开 Kubeflow UI。
-
选择与你的 workbench 相同的 namespace。
-
进入 Pipelines > Runs。
-
打开
hello-two-nodes的最新 run。 -
在 Graph 选项卡中,确认两个 notebook 节点按顺序出现。
-
单击每个节点并查看日志。你应该会看到:
-
等待 run 状态变为
Succeeded。
根据你的 Kubeflow 路由,run 详情 URL 可能如下所示:
你也可以查看该 namespace 中的 Kubernetes 资源:
对于 KFP v2,看到一个 run 对应 driver 和 implementation pod 是正常的。用户的 notebook 代码会在 implementation 容器中运行。
故障排查
namespace 在 Kubeflow 中不可见
该 namespace 必须关联到 Kubeflow Profile,并且用户必须绑定到该 namespace。请按照 安装 Kubeflow 插件 中的 namespace 绑定步骤进行操作。
Elyra 未显示 KFP runtime 配置
请使用包含 Elyra 的 JupyterLab workbench 镜像。然后请管理员确认 Elyra runtime 元数据已挂载到 workbench 中,并且 runtime 已指向你的 KFP 端点和对象存储。
Elyra 中不可用该 runtime image
请管理员创建或更新 pipeline-runtime-images ConfigMap,并通过 WorkspaceKind 将其挂载到 /opt/app-root/pipeline-runtimes。修改 ConfigMap 后请重启 workbench。
run 在 notebook 代码开始前失败
检查 namespace 侧的 KFP 对象:
同时检查该 namespace 中失败的 pod 日志。与存储相关的故障通常指向对象存储端点、bucket、凭据或 kfp-launcher 配置。元数据上报失败通常指向 metadata-grpc-configmap 或 metadata gRPC service。
Elyra 成功对话框已关闭
直接打开 Kubeflow Pipelines,并在相同 namespace 中查看 Runs。Elyra 在成功对话框关闭后不会保留持久的 run 链接。