从 Kale Workbench 运行 Kubeflow Pipelines

Kale 是一个 JupyterLab 扩展,可将带注释的 notebook 单元格转换为 Kubeflow Pipelines (KFP) v2 pipeline。请使用通过 Kale 扩展构建的 JupyterLab WorkspaceKind;不要在正在运行的 workbench 中交互式安装 Kale,因为扩展及其 server 组件必须使用匹配的版本。

前提条件

  • KFP v2 backend 已就绪:可以是 kubeflow 命名空间中的共享 ml-pipeline service,或者是 workbench 命名空间中已就绪的 DSPO DataSciencePipelinesApplication。
  • workbench 命名空间由 Kubeflow Profile 管理。这会为该命名空间添加 Pipeline API NetworkPolicy 所需的 kubeflow-profile 标签。
  • 对于共享 KFP token 认证,WorkspaceKind service account 可以为 pipelines.kubeflow.org audience 请求 projected token。下面的 DSPO 集群内示例改用 auth_type: none。
  • Kale JupyterLab CI image 可在 Docker Hub 上的 docker.io/alaudadockerhub/kale-jupyterlab:v2.2.1a2 获取。集群节点必须能够拉取该 image。对于私有或 air-gapped 集群,请将此 image 镜像到平台 registry,并改用镜像后的地址。

准备 Kubeflow Profile 命名空间

KFP network policies 通过以下标签识别用户命名空间:

app.kubernetes.io/part-of: kubeflow-profile
pipelines.kubeflow.org/enabled: "true"

准备命名空间的推荐方式是创建 Kubeflow Profile。 Profile controller 会创建命名空间(如有需要)、应用这些标签,并为所有者设置 Kubeflow 命名空间资源:

kale-profile.yaml
apiVersion: kubeflow.org/v1beta1
kind: Profile
metadata:
  name: <your-namespace>
spec:
  owner:
    kind: User
    name: <your-user>
kubectl apply -f kale-profile.yaml

如果命名空间已存在且未由 Profile 管理,请手动添加这些标签:

kubectl label namespace <your-namespace> \
  app.kubernetes.io/part-of=kubeflow-profile \
  pipelines.kubeflow.org/enabled=true \
  --overwrite

手动添加标签会使该命名空间具备符合 KFP network policies 的资格,但不会创建 Profile、绑定用户,也不会创建 Workbench 所需的 service-account RBAC。对于现有命名空间,请按照 安装 Kubeflow Plugins 中的说明创建 Profile 和用户绑定。在创建 workbench 之前,请验证标签和 Profile 都已存在:

kubectl get namespace <your-namespace> \
  -o jsonpath='{.metadata.labels.app\.kubernetes\.io/part-of}{"\n"}{.metadata.labels.pipelines\.kubeflow\.org/enabled}{"\n"}'
kubectl get profile <your-namespace>

为共享 KFP service 配置 Kale

Kale 从 kfp_server_config.json 读取 KFP 认证信息。请仅在 ConfigMap 中存储 token 路径:token 本身保留在 projected service-account volume 中,并由 Kubernetes 刷新。

当集群使用共享 Kubeflow Pipelines 安装(kfp-operator)时,请使用此配置。对于 Data Science Pipelines Operator (DSPO) 安装,请改用 下面的 DSPO 设置。

在每个将使用 Kale WorkspaceKind 的命名空间中创建此 ConfigMap。将 <your-namespace> 替换为 workbench 的命名空间。

kale-kfp-server-config.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: kale-kfp-server-config
  namespace: <your-namespace>
data:
  kfp_server_config.json: |
    {
      "host": "http://ml-pipeline.kubeflow.svc.cluster.local:8888",
      "auth_type": "kubernetes_service_account_token",
      "auth_config": {
        "token_path": "/var/run/secrets/kubeflow/pipelines/token"
      },
      "namespace": "<your-namespace>"
    }

使用以下命令应用:

kubectl apply -f kale-kfp-server-config.yaml

将 Kale 与 DSPO 一起使用

Data Science Pipelines Operator (DSPO) 会为每个命名空间部署一套独立的 KFP v2 stack。在与 Kale workbench 相同的 Profile 命名空间中安装 DSPO 并创建 DataSciencePipelinesApplication (DSPA);请参见 安装 Data Science Pipelines 和 创建 Data Science Pipelines Application。DSPO 与共享 Kubeflow Pipelines kfp-operator 在集群中互斥,因此请二选一部署 pipeline service 模型。

对于使用 operator 管理的 MariaDB 和 MinIO 的开发型 DSPA,请应用:

kale-dspa.yaml
apiVersion: datasciencepipelinesapplications.opendatahub.io/v1
kind: DataSciencePipelinesApplication
metadata:
  name: kale
  namespace: <your-namespace>
spec:
  dspVersion: v2
  apiServer:
    enableOauth: false
    enableSamplePipeline: false
  objectStorage:
    minio:
      deploy: true
kubectl apply -f kale-dspa.yaml
kubectl wait --for=condition=Ready dspa/kale \
  -n <your-namespace> --timeout=15m
kubectl get pods -n <your-namespace> -l component=data-science-pipelines

DSPA API service 名称为 ds-pipeline-<dspa-name>,监听端口 8888。请将共享 KFP ConfigMap 替换为此命名空间本地的 DSPO endpoint:

kale-kfp-server-config-dspo.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: kale-kfp-server-config
  namespace: <your-namespace>
data:
  kfp_server_config.json: |
    {
      "host": "http://ds-pipeline-kale.<your-namespace>.svc:8888",
      "auth_type": "none",
      "namespace": "<your-namespace>"
    }
kubectl apply -f kale-kfp-server-config-dspo.yaml

保留下面 WorkspaceKind 中的 KALE_CONFIG_PATH、projected volumes 和 ConfigMap mount。如果 Workbench 版本使用 KF_PIPELINES_ENDPOINT 环境变量,请将其值设置为相同的 DSPO URL。修改 ConfigMap 后重启 workbench,以便 Kale 重新加载 endpoint。此时,Compile and Run 会提交到 workbench 命名空间中的 DSPA;请使用以下命令验证运行情况:

kubectl get workflows -n <your-namespace>
kubectl get pods -n <your-namespace> -l workflows.argoproj.io/workflow

创建 Kale WorkspaceKind

下面的摘录展示了 JupyterLab WorkspaceKind 中 Kale 相关的部分。请添加平台通常使用的资源选项、探针和 workbench 标签。NB_PREFIX 和 NOTEBOOK_BASE_URL 的值必须与目标集群的 Skipper route 匹配。

kale-jupyterlab-workspacekind.yaml
apiVersion: kubeflow.org/v1beta1
kind: WorkspaceKind
metadata:
  name: kale-jupyterlab
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" }}
      - name: NOTEBOOK_ARGS
        value: --ServerApp.token='' --ServerApp.password=''
      - name: KF_PIPELINES_ENDPOINT
        value: http://ml-pipeline.kubeflow.svc.cluster.local:8888
      - name: KALE_CONFIG_PATH
        value: /etc/kale/kfp_server_config.json
      # Default image for every generated KFP step without an image override.
      - name: KALE_DEFAULT_BASE_IMAGE
        value: docker.io/alaudadockerhub/kale-jupyterlab:v2.2.1a2
    extraVolumes:
      - name: kfp-api-token
        projected:
          sources:
            - serviceAccountToken:
                audience: pipelines.kubeflow.org
                expirationSeconds: 3607
                path: token
      - name: kale-kfp-server-config
        configMap:
          name: kale-kfp-server-config
    extraVolumeMounts:
      - name: kfp-api-token
        mountPath: /var/run/secrets/kubeflow/pipelines
        readOnly: true
      - name: kale-kfp-server-config
        mountPath: /etc/kale
        readOnly: true
    options:
      imageConfig:
        spawner:
          default: kale-jupyterlab
        values:
          - id: kale-jupyterlab
            spawner:
              displayName: JupyterLab | Kale | CPU
              description: JupyterLab with the Kubeflow Kale extension.
            spec:
              image: docker.io/alaudadockerhub/kale-jupyterlab:v2.2.1a2
              imagePullPolicy: IfNotPresent
              ports:
                - id: jupyterlab
                  displayName: JupyterLab
                  port: 8888
                  protocol: HTTP
    serviceAccount:
      name: aml-editor

ConfigMap 采用命名空间级作用域。WorkspaceKind 可以是 cluster-scoped,但使用它的每个命名空间都必须包含自己的 kale-kfp-server-config ConfigMap,且其 KFP 命名空间值必须匹配。

应用 WorkspaceKind 并基于它创建 workbench:

kubectl apply -f kale-jupyterlab-workspacekind.yaml

配置 pipeline step runtime images

用于打开 Kale Workbench 的 image 与生成的 KFP steps 所使用的 image 是两个独立设置。options.imageConfig.values[].spec.image 用于启动 JupyterLab Workbench;下面的设置控制 pipeline steps 使用的 container image。

方法 1:在 WorkspaceKind 中设置一个默认 image

只在 podTemplate.extraEnv 中设置 KALE_DEFAULT_BASE_IMAGE,即可为每个未指定自身 image 的生成 KFP step 应用一个默认 runtime image:

podTemplate:
  extraEnv:
    - name: KALE_DEFAULT_BASE_IMAGE
      value: docker.io/alaudadockerhub/kale-jupyterlab:v2.2.1a2

当 pipeline 需要 Workbench image 中不包含的包或 system libraries 时,请将其设置为专用 runtime image。该 image 必须能被 KFP worker nodes 拉取(如果集群是 multi-arch,则两个架构都必须能够拉取),而不仅仅是 JupyterLab pod 可以拉取。

方法 2:为单个 step 覆盖 image

若要为某个 step 使用不同的 image,请在该 step 的 cell 中添加 image:<image> 标签。在 Kale UI 中,在 step 配置里设置 Base Image;UI 会写入相同的 cell metadata:

{
  "cell_type": "code",
  "metadata": {
    "tags": [
      "step:train",
      "image:docker.io/alaudadockerhub/my-training-runtime:v1.0.0"
    ]
  },
  "source": [
    "model.fit(x_train, y_train)\n"
  ]
}

每个 step 的 image: 标签优先级高于 KALE_DEFAULT_BASE_IMAGE。如果两者都未设置,Kale 将回退到 python:3.12。请使用不可变标签或 digest,并确保每个 runtime 都包含该 step 导入的 Python packages。在 Compile and Save 之后,在提交 pipeline 前检查生成的 .kale/*.kale.py 文件中的 base_image= 值。

在 JupyterLab 中使用 Kale

  1. 打开正在运行的 Kale workbench 并上传 notebook。
  2. 从左侧边栏打开 Kale panel。
  3. 将单元格标记为 pipeline steps,并设置 pipeline 和 experiment 名称。
  4. 选择 Compile and Run。Kale 会编译 notebook,将其上传到 KFP,并在 kfp_server_config.json 中配置的命名空间里启动一次运行。

如果 Kale 报告空 identity 或 401 Unauthorized,请验证 KALE_CONFIG_PATH 是否指向已挂载的 ConfigMap,以及 Pipeline token 是否挂载在 /var/run/secrets/kubeflow/pipelines/token。仅能访问 Pipeline health endpoint 还不够:Kale 必须使用该 projected token 进行认证。

示例

这些示例复制自上游 Kubeflow Kale repository。