自带 Workbench 镜像

当内置的 Workbench 镜像不包含团队所需的框架、系统库或内部工具时,可以使用 BYO(自带)镜像。 该镜像必须对集群可用,并且必须由集群管理员在 WorkspaceKind 中注册,之后才会显示在 Workbench 创建表单中。

本指南介绍两种受支持的方法:

  1. 从 Alauda Workbench 镜像派生镜像。这是推荐的方法,因为基础镜像已经包含与 Workbench 兼容的 Jupyter 或 code-server 启动配置。
  2. 从供应商加速器镜像构建 Jupyter Workbench 镜像。当你需要特定的 CUDA 或 Ascend CANN 版本时,这种方法很有用,但你必须自行提供 IDE 启动契约,并在目标集群上进行验证。

工作流

完整工作流如下:

  1. 选择与目标节点架构和驱动栈匹配的基础镜像。
  2. 构建并测试镜像,然后将其推送到 Workbench 命名空间可访问的镜像仓库。
  3. 创建一个指向该镜像并声明其 Jupyter 端口和资源选项的 WorkspaceKind。
  4. 使用该 WorkspaceKind 创建 Workbench,然后验证 pod、设备和 IDE 日志。

镜像仓库、Kubernetes 命名空间和 Workbench 服务账户因集群而异。请将示例中的占位符替换为环境中的值。

选择基础镜像

从 Alauda Workbench 镜像开始

如果只需要添加 Python 软件包、CLI 工具或组织专用代码,请使用 Alauda 镜像。从可用的 Workbench 镜像中选择一个镜像,然后固定集群使用的确切标签或摘要。

典型起始点包括:

工作负载基础镜像示例架构
轻量级 CPU JupyterLabdocker.io/alaudadockerhub/alauda-workbench-jupyter-minimal-cpu-py312-ubi9:<tag>amd64 或 arm64
CPU 数据科学docker.io/alaudadockerhub/alauda-workbench-jupyter-datascience-cpu-py312-ubi9:<tag>amd64 或 arm64
NVIDIA CUDA JupyterLabdocker.io/alaudadockerhub/odh-workbench-jupyter-minimal-cuda-py312-ubi9:<tag>amd64
NVIDIA PyTorchdocker.io/alaudadockerhub/odh-workbench-jupyter-pytorch-cuda-py312-ubi9:<tag>amd64
Ascend CANN JupyterLabdocker.io/alaudadockerhub/alauda-workbench-jupyter-minimal-cann-py312-ubi9:<tag>arm64
Ascend PyTorchdocker.io/alaudadockerhub/alauda-workbench-jupyter-pytorch-cann-py312-ubi9:<tag>arm64

镜像名称和软件包版本可能会在不同版本之间发生变化。构建前,请在 Workbench 镜像表或对应的 Docker Hub 仓库中确认标签。对于生产构建,请记录解析后的摘要:

nerdctl manifest inspect \
  docker.io/alaudadockerhub/alauda-workbench-jupyter-datascience-cpu-py312-ubi9:<tag>

选择 CUDA 基础镜像

对于从头构建的 NVIDIA 镜像,请从官方的 nvidia/cuda 仓库中选择 CUDA 标签。标签包含 CUDA 版本、是否包含 cuDNN、镜像用途和 Linux 发行版等信息。当镜像构建需要编译 CUDA 或 Python 扩展时,请使用 devel 变体;当所有依赖项都已构建完成时,请使用 runtime 变体。

镜像中的 CUDA 版本必须受到目标节点上 NVIDIA 驱动程序的支持。该镜像不会安装或升级主机驱动程序。选择标签前,请查阅 NVIDIA CUDA/驱动程序兼容性文档,并确认集群已配置 NVIDIA device plugin 和容器运行时。还要检查镜像架构:本指南中的 Workbench CUDA 镜像以 linux/amd64 为目标,除非所选 CUDA 标签明确提供其他平台。

例如,以下内容仅作为构建基础;请将标签替换为已针对节点完成验证的 CUDA 版本:

FROM nvidia/cuda:<cuda-version>-cudnn-devel-ubuntu<ubuntu-version>

选择 Ascend CANN 基础镜像

对于从头构建的 Ascend 镜像,请从官方的 openeuler/cann 仓库中选择 CANN 标签。选择 CANN 版本、openEuler 基础版本和架构与目标节点上安装的 Ascend 驱动程序和固件相匹配的标签。CANN 兼容性属于供应商栈相关问题:不要默认选择最新镜像,也不要在现有镜像中安装不同的 CANN 版本,除非已检查版本兼容性矩阵。

该镜像不会安装或升级主机 Ascend 驱动程序。集群必须已经提供 Ascend device plugin,并公开硬件使用的资源名称,例如 huawei.com/Ascend910B4。构建前,请确认节点架构和驱动程序状态:

kubectl get nodes -L kubernetes.io/arch
kubectl describe node <ascend-node> | grep -E 'huawei.com/|Allocatable'

例如,以下内容仅作为构建基础;请将标签替换为已针对节点完成验证的 CANN 版本:

FROM openeuler/cann:<cann-version>

通过扩展 Alauda 镜像进行构建

这是普通 Jupyter Workbench 的首选方式。它会保留基础镜像的用户、entrypoint、Jupyter 配置和文件系统布局。仅安装工作负载所需的软件包。

Containerfile
ARG BASE_IMAGE=docker.io/alaudadockerhub/alauda-workbench-jupyter-datascience-cpu-py312-ubi9:<tag>
FROM ${BASE_IMAGE}

USER 0
RUN python -m pip install --no-cache-dir \
      "transformers==<version>" \
      "datasets==<version>" \
      "internal-package==<version>"

# Restore the user from the base image. Set BASE_USER to the value reported by:
# nerdctl image inspect ${BASE_IMAGE} --format '{{.Config.User}}'
ARG BASE_USER=1001
USER ${BASE_USER}

# Keep the ENTRYPOINT and CMD from the Alauda base image.

使用支持 OCI 的构建器进行构建和推送。当构建主机与 Workbench 节点使用不同架构时,请显式使用 --platform:

export REGISTRY=registry.example.com
export PROJECT=mlops/workbench-images
export IMAGE=byo-jupyter-datascience
export TAG=2026.09.0

nerdctl build \
  --platform linux/amd64 \
  --build-arg BASE_IMAGE=docker.io/alaudadockerhub/alauda-workbench-jupyter-datascience-cpu-py312-ubi9:<tag> \
  -f Containerfile \
  --output "type=image,name=${REGISTRY}/${PROJECT}/${IMAGE}:${TAG},push=true" \
  .

对于 Ascend 镜像,请将 arm64 Alauda CANN 镜像用作 BASE_IMAGE,并使用 --platform linux/arm64 进行构建。不要将 amd64 基础镜像与 arm64 Workbench 节点混用,即使镜像仓库接受推送也不例外。

从 CUDA 或 CANN 镜像构建

从供应商镜像构建可以让你控制加速器栈,但也意味着你的镜像需要负责 Workbench 运行时。镜像至少必须:

  • 以集群 Pod Security Admission 接受的非 root 用户运行;
  • 包含 Python、JupyterLab 和 Jupyter Server(或你要公开的 IDE);
  • 在 WorkspaceKind 中声明的端口上启动 HTTP 服务器;
  • 在平台提供 Workbench 路由前缀(NB_PREFIX)时遵循该前缀;
  • 将用户的主目录写入挂载的 home PVC;以及
  • 避免在容器中安装主机驱动程序。

以下 launcher 是一个从头构建镜像时使用的最简 Jupyter 示例。生产镜像应添加固定版本的依赖锁定文件、健康检查和经过批准的软件包镜像源。

start-workbench.sh
#!/usr/bin/env bash
set -euo pipefail

args=(
  --ip=0.0.0.0
  --port=8888
  --no-browser
  --ServerApp.allow_remote_access=True
  --ServerApp.token=
  --ServerApp.password=
)

if [[ -n "${NB_PREFIX:-}" ]]; then
  args+=("--ServerApp.base_url=${NB_PREFIX}")
fi

exec jupyter lab "${args[@]}"

CUDA 示例

当软件包需要编译时,请使用 CUDA devel 标签。如果所有软件包都已预构建,则较小的 runtime 标签可能就足够了。下面的 ubuntu 版本和 Python 版本仅为示例;请固定为所选 CUDA 标签支持的版本。

Containerfile.cuda
FROM nvidia/cuda:<cuda-version>-cudnn-devel-ubuntu<ubuntu-version>

ENV DEBIAN_FRONTEND=noninteractive \
    HOME=/home/jovyan \
    JUPYTER_ENABLE_LAB=yes \
    PATH=/opt/venv/bin:$PATH

RUN apt-get update && apt-get install -y --no-install-recommends \
      python3 python3-pip python3-venv git ca-certificates \
    && rm -rf /var/lib/apt/lists/*

RUN python3 -m venv /opt/venv \
    && /opt/venv/bin/pip install --no-cache-dir \
      "jupyterlab==<version>" \
      "jupyter-server==<version>" \
      "ipykernel==<version>" \
      "torch==<version>" \
      "transformers==<version>"

COPY start-workbench.sh /usr/local/bin/start-workbench
RUN chmod 0755 /usr/local/bin/start-workbench \
    && useradd --create-home --uid 1001 jovyan \
    && mkdir -p /home/jovyan \
    && chown -R 1001:0 /home/jovyan \
    && chmod -R g=u /home/jovyan

USER 1001
WORKDIR /home/jovyan
EXPOSE 8888
ENTRYPOINT ["/usr/local/bin/start-workbench"]

为 NVIDIA 节点构建,并在注册之前验证 CUDA 运行时:

nerdctl build --platform linux/amd64 \
  -f Containerfile.cuda \
  --output "type=image,name=registry.example.com/mlops/workbench-images/byo-jupyter-cuda:2026.09.0,push=true" \
  .

nerdctl run --rm --gpus all --entrypoint python3 \
  registry.example.com/mlops/workbench-images/byo-jupyter-cuda:2026.09.0 \
  -c 'import torch; print(torch.cuda.is_available())'

Ascend CANN 示例

使用与节点的 CANN/驱动程序/固件组合相匹配的 openeuler/cann 标签。CANN 镜像通常会提供 set_env.sh;启动 Jupyter 之前先加载它,以便 CANN 库和编译器路径可见。请从匹配的 CANN 版本指定的 wheel 源安装 torch 和 torch-npu;通用 PyPI 版本可能与设备栈不兼容。

Containerfile.cann
FROM openeuler/cann:<cann-version>

ENV HOME=/home/jovyan \
    JUPYTER_ENABLE_LAB=yes \
    PATH=/opt/venv/bin:$PATH

RUN dnf install -y python3 python3-pip git ca-certificates \
    && dnf clean all

# Use the CANN release's compatible wheel index or local wheelhouse.
RUN python3 -m venv /opt/venv \
    && /opt/venv/bin/pip install --no-cache-dir \
      "jupyterlab==<version>" \
      "jupyter-server==<version>" \
      "ipykernel==<version>" \
      "torch==<version>" \
      "torch-npu==<version>"

COPY start-workbench-cann.sh /usr/local/bin/start-workbench
RUN chmod 0755 /usr/local/bin/start-workbench \
    && useradd --create-home --uid 1001 jovyan \
    && mkdir -p /home/jovyan \
    && chown -R 1001:0 /home/jovyan \
    && chmod -R g=u /home/jovyan

USER 1001
WORKDIR /home/jovyan
EXPOSE 8888
ENTRYPOINT ["/usr/local/bin/start-workbench"]

使用与 CUDA 示例相同的 launcher,但先加载 CANN:

start-workbench-cann.sh
#!/usr/bin/env bash
set -euo pipefail

if [[ -f /usr/local/Ascend/ascend-toolkit/set_env.sh ]]; then
  # shellcheck disable=SC1091
  source /usr/local/Ascend/ascend-toolkit/set_env.sh
fi

args=(
  --ip=0.0.0.0
  --port=8888
  --no-browser
  --ServerApp.allow_remote_access=True
  --ServerApp.token=
  --ServerApp.password=
)

if [[ -n "${NB_PREFIX:-}" ]]; then
  args+=("--ServerApp.base_url=${NB_PREFIX}")
fi

exec jupyter lab "${args[@]}"

针对 Ascend 节点公开的架构进行构建:

nerdctl build --platform linux/arm64 \
  -f Containerfile.cann \
  --output "type=image,name=registry.example.com/mlops/workbench-images/byo-jupyter-cann:2026.09.0,push=true" \
  .

请在 Ascend 节点上测试此镜像,而不仅仅是在构建主机上测试。例如,在资源请求与 Workbench 相同的 pod 中,验证 npu-smi info、导入 torch_npu,并运行一个简单的设备操作:

python3 -c 'import torch, torch_npu; print(torch.npu.is_available())'
npu-smi info

创建 WorkspaceKind

WorkspaceKind 是集群范围的。imageConfig 选项用于选择镜像, podConfig 选项用于选择资源和节点放置位置。服务账户必须已存在于用户创建 Workspace 的每个命名空间中。 对于私有 registry,请为该服务账户附加一个 imagePullSecret,或根据集群的镜像拉取策略进行配置。

以下示例有意使用单独的 WorkspaceKind 资源。这样可以确保 CUDA 镜像运行在 NVIDIA 节点上,而 CANN 镜像运行在 Ascend 节点上。 应用这些资源前,请替换 <workbench-service-account>、<cluster>、资源名称和镜像标签。

CUDA WorkspaceKind

workspacekind-byo-cuda.yaml
apiVersion: kubeflow.org/v1beta1
kind: WorkspaceKind
metadata:
  name: jupyterlab-byo-cuda
spec:
  spawner:
    displayName: JupyterLab | BYO CUDA
    description: JupyterLab Workbench using a customer-built NVIDIA CUDA image.
    icon:
      url: https://jupyter.org/assets/favicons/apple-touch-icon-152x152.png
    logo:
      url: https://jupyter.org/assets/favicons/apple-touch-icon-152x152.png
  podTemplate:
    containerSecurityContext:
      runAsNonRoot: true
      allowPrivilegeEscalation: false
      capabilities:
        drop:
          - ALL
      seccompProfile:
        type: RuntimeDefault
    extraEnv:
      - name: NB_PREFIX
        value: /clusters/<cluster>/aml/aml-workbench{{ httpPathPrefix "jupyterlab" }}
      - name: NOTEBOOK_BASE_URL
        value: /clusters/<cluster>/aml/aml-workbench{{ httpPathPrefix "jupyterlab" }}
    securityContext:
      runAsNonRoot: true
      fsGroup: 1001
    options:
      imageConfig:
        spawner:
          default: byo-cuda
        values:
          - id: byo-cuda
            spawner:
              displayName: BYO CUDA JupyterLab
              description: Customer-built CUDA Workbench image.
            spec:
              image: registry.example.com/mlops/workbench-images/byo-jupyter-cuda:2026.09.0
              imagePullPolicy: IfNotPresent
              ports:
                - id: jupyterlab
                  displayName: JupyterLab
                  port: 8888
                  protocol: HTTP
      podConfig:
        spawner:
          default: nvidia-gpu
        values:
          - id: nvidia-gpu
            spawner:
              displayName: NVIDIA GPU
              description: Schedule the Workbench on an NVIDIA node.
            spec:
              nodeSelector:
                kubernetes.io/arch: amd64
              resources:
                requests:
                  cpu: "2"
                  memory: 8Gi
                  nvidia.com/gpu: "1"
                limits:
                  cpu: "2"
                  memory: 8Gi
                  nvidia.com/gpu: "1"
    serviceAccount:
      name: <workbench-service-account>
    volumeMounts:
      home: /home/jovyan

Ascend NPU WorkspaceKind

workspacekind-byo-cann.yaml
apiVersion: kubeflow.org/v1beta1
kind: WorkspaceKind
metadata:
  name: jupyterlab-byo-cann
spec:
  spawner:
    displayName: JupyterLab | BYO Ascend CANN
    description: JupyterLab Workbench using a customer-built Ascend CANN image.
    icon:
      url: https://jupyter.org/assets/favicons/apple-touch-icon-152x152.png
    logo:
      url: https://jupyter.org/assets/favicons/apple-touch-icon-152x152.png
  podTemplate:
    containerSecurityContext:
      runAsNonRoot: true
      allowPrivilegeEscalation: false
      capabilities:
        drop:
          - ALL
      seccompProfile:
        type: RuntimeDefault
    extraEnv:
      - name: NB_PREFIX
        value: /clusters/<cluster>/aml/aml-workbench{{ httpPathPrefix "jupyterlab" }}
      - name: NOTEBOOK_BASE_URL
        value: /clusters/<cluster>/aml/aml-workbench{{ httpPathPrefix "jupyterlab" }}
    securityContext:
      runAsNonRoot: true
      fsGroup: 1001
      supplementalGroups:
        # Replace 1000 with the group owning /dev/davinci* on your nodes.
        - 1000
    options:
      imageConfig:
        spawner:
          default: byo-cann
        values:
          - id: byo-cann
            spawner:
              displayName: BYO Ascend CANN JupyterLab
              description: Customer-built CANN Workbench image.
            spec:
              image: registry.example.com/mlops/workbench-images/byo-jupyter-cann:2026.09.0
              imagePullPolicy: IfNotPresent
              ports:
                - id: jupyterlab
                  displayName: JupyterLab
                  port: 8888
                  protocol: HTTP
      podConfig:
        spawner:
          default: ascend-npu
        values:
          - id: ascend-npu
            spawner:
              displayName: Ascend NPU
              description: Schedule the Workbench on an Ascend node.
            spec:
              nodeSelector:
                kubernetes.io/arch: arm64
              resources:
                requests:
                  cpu: "2"
                  memory: 8Gi
                  huawei.com/Ascend910B4: "1"
                limits:
                  cpu: "2"
                  memory: 8Gi
                  huawei.com/Ascend910B4: "1"
    serviceAccount:
      name: <workbench-service-account>
    volumeMounts:
      home: /home/jovyan

以集群管理员身份应用这些资源:

kubectl apply -f workspacekind-byo-cuda.yaml
kubectl apply -f workspacekind-byo-cann.yaml
kubectl get workspacekind jupyterlab-byo-cuda jupyterlab-byo-cann

如果现有的托管 Jupyter WorkspaceKind 已经具有正确的路由、 安全上下文、服务账户和资源选项,则可以注册其他镜像,而无需创建新的 WorkspaceKind。向 spec.podTemplate.options.imageConfig.values[] 添加一项, 并保留现有条目。创建 Workbench 页面包含此迁移路径的 JSON 补丁示例。

创建并验证 Workbench

  1. 打开 Alauda AI Platform,然后转到 Workbench。

  2. 单击 创建,并选择 JupyterLab | BYO CUDA 或 JupyterLab | BYO Ascend CANN。

  3. 选择与镜像和节点硬件匹配的资源选项。

  4. 等待 Workbench 状态变为 Running,然后单击 连接。

  5. 在终端中验证架构、框架和加速器:

    uname -m
    python3 -c 'import sys; print(sys.version)'

    对于 CUDA,还要运行 nvidia-smi 并检查框架的 CUDA 可用性。对于 CANN,运行 npu-smi info 并导入 torch_npu。

如果 Workspace 未启动,请先检查镜像拉取、调度和容器日志:

kubectl get workspace -A
kubectl get pod -n <workbench-namespace> -o wide
kubectl describe pod -n <workbench-namespace> <pod-name>
kubectl logs -n <workbench-namespace> <pod-name>

常见原因包括:registry 中不存在相应的镜像标签、缺少镜像拉取密钥、架构不匹配、不受支持的主机驱动程序、 缺少加速器设备插件,或目标节点上不存在 WorkspaceKind 资源名称。在 Ascend vNPU 集群上, 请将设备文件组添加到 supplementalGroups;仅使用 fsGroup 可能无法授予对 /dev/davinci* 的访问权限。

构建和安全建议

  • 在 CI 中通过标签和摘要固定基础镜像、Python 软件包和最终镜像。
  • 在 CI 中构建并扫描镜像;不要在 Workbench 启动时安装大型或特权软件包。
  • 以非 root 用户运行,并确保运行时 UID/GID 对挂载的主目录具有写入权限。不要添加 privileged: true 来让加速器显示出来。
  • 对于 air-gapped 集群,将所有基础镜像和软件包镜像到经批准的内部 registry 中,然后在 WorkspaceKind 中使用镜像后的镜像。
  • 将 CUDA 和 CANN 镜像分开。CUDA 镜像应运行在 NVIDIA 节点上,Ascend 镜像应运行在 Ascend 节点上;主机驱动程序和设备插件由集群提供,而不是由容器镜像提供。