自带 Workbench 镜像
当内置的 Workbench 镜像不包含团队所需的框架、系统库或内部工具时,可以使用 BYO(自带)镜像。
该镜像必须对集群可用,并且必须由集群管理员在 WorkspaceKind 中注册,之后才会显示在 Workbench 创建表单中。
本指南介绍两种受支持的方法:
- 从 Alauda Workbench 镜像派生镜像。这是推荐的方法,因为基础镜像已经包含与 Workbench 兼容的 Jupyter 或 code-server 启动配置。
- 从供应商加速器镜像构建 Jupyter Workbench 镜像。当你需要特定的 CUDA 或 Ascend CANN 版本时,这种方法很有用,但你必须自行提供 IDE 启动契约,并在目标集群上进行验证。
工作流
完整工作流如下:
- 选择与目标节点架构和驱动栈匹配的基础镜像。
- 构建并测试镜像,然后将其推送到 Workbench 命名空间可访问的镜像仓库。
- 创建一个指向该镜像并声明其 Jupyter 端口和资源选项的
WorkspaceKind。
- 使用该
WorkspaceKind 创建 Workbench,然后验证 pod、设备和 IDE 日志。
镜像仓库、Kubernetes 命名空间和 Workbench 服务账户因集群而异。请将示例中的占位符替换为环境中的值。
选择基础镜像
从 Alauda Workbench 镜像开始
如果只需要添加 Python 软件包、CLI 工具或组织专用代码,请使用 Alauda 镜像。从可用的 Workbench 镜像中选择一个镜像,然后固定集群使用的确切标签或摘要。
典型起始点包括:
镜像名称和软件包版本可能会在不同版本之间发生变化。构建前,请在 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
-
打开 Alauda AI Platform,然后转到 Workbench。
-
单击 创建,并选择 JupyterLab | BYO CUDA 或
JupyterLab | BYO Ascend CANN。
-
选择与镜像和节点硬件匹配的资源选项。
-
等待 Workbench 状态变为 Running,然后单击 连接。
-
在终端中验证架构、框架和加速器:
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 节点上;主机驱动程序和设备插件由集群提供,而不是由容器镜像提供。