昇腾 K8s 环境部署指南

Thu, 08 Jan 2026 00:00:00 +0000

昇腾 K8s 环境部署指南

概述

本文档介绍在 Kubernetes 集群中部署昇腾 NPU 容器化环境的完整流程，适用于以下场景：

容器运行时：Containerd
NPU 设备：Ascend 310P
系统架构：aarch64（ARM64）
Kubernetes 版本：1.28+

部署流程主要包括三个步骤：

环境准备（节点标签、用户、目录）
安装 Ascend Docker Runtime
部署 Ascend Device Plugin

准备工作

创建节点标签

为 Kubernetes 节点添加相应标签，用于后续的 Pod 调度和资源管理。

# 标记主节点
kubectl label nodes ecs-b0tf90001 masterselector=dls-master-node

# 标记 NPU 计算节点
kubectl label nodes ecs-exyqec0002 node-role.kubernetes.io/worker=worker
kubectl label nodes ecs-exyqec0002 workerselector=dls-worker-node
kubectl label nodes ecs-exyqec0002 host-arch=huawei-arm
kubectl label nodes ecs-exyqec0002 accelerator=huawei-Ascend310P

说明：请根据实际节点名称修改 ecs-b0tf90001 和 ecs-exyqec0002。

创建系统用户

在 Ascend 计算节点（如 ecs-exyqec0002）上创建专用用户和用户组。

# 创建 hwMindX 用户（UID 9000）
useradd -d /home/hwMindX -u 9000 -m -s /sbin/nologin hwMindX

# 创建 HwHiAiUser 用户组
groupadd HwHiAiUser

# 将 hwMindX 用户添加到 HwHiAiUser 组
usermod -a -G HwHiAiUser hwMindX

注意：UID 9000 和用户组 HwHiAiUser 是昇腾软件栈的默认配置，请勿随意修改。

创建日志目录

在 Ascend 计算节点上创建 Device Plugin 日志目录。

1
2
3

# 创建日志目录并设置权限
mkdir -m 750 /var/log/mindx-dl/devicePlugin
chown root:root /var/log/mindx-dl/devicePlugin

安装 Ascend Docker Runtime

Ascend Docker Runtime 是容器化环境下使用昇腾 NPU 的核心组件，需要在所有昇腾计算节点上安装。

下载安装包

前往官方 Git 仓库下载对应版本的安装包。

示例：Ascend-docker-runtime_7.2.RC1.SPC2_linux-aarch64.run

安装步骤

步骤 1：进入安装包目录

`1`	`cd <path to run package>`

步骤 2：校验安装包完整性

`1`	`./Ascend-docker-runtime_{version}_linux-{arch}.run --check`

预期输出：

1
2

[WARNING]: --check is meaningless for Ascend-docker-runtime and will be discarded in the future
Verifying archive integrity... All good.

步骤 3：添加可执行权限

`1`	`chmod u+x Ascend-docker-runtime_{version}_linux-{arch}.run`

步骤 4：执行安装

方式一：安装到默认路径（推荐）

`1`	`./Ascend-docker-runtime_{version}_linux-{arch}.run --install`

方式二：安装到自定义路径

`1`	`./Ascend-docker-runtime_{version}_linux-{arch}.run --install --install-path=<path>`

安装成功输出示例：

Uncompressing ascend-docker-runtime  100%
[INFO]: installing ascend docker runtime
...
[INFO] Ascend Docker Runtime install success

默认安装路径：/usr/local/Ascend/Ascend-Docker-Runtime/

配置 Containerd

根据系统使用的 cgroup 版本修改 Containerd 配置文件 /etc/containerd/config.toml。

配置方式一：Cgroup v1

需要修改以下两个关键配置项：

runtime_type = "io.containerd.runtime.v1.linux"
runtime = "/usr/local/Ascend/Ascend-Docker-Runtime/ascend-docker-runtime"

完整配置示例：

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes]
  [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc]
    runtime_type = "io.containerd.runtime.v1.linux"
    runtime_engine = ""
    runtime_root = ""
    privileged_without_host_devices = false
    base_runtime_spec = ""
    [plugins."io.containerd.grpc.v1.cri".containerd.runtimes.runc.options]

[plugins."io.containerd.grpc.v1.cri".cni]
  bin_dir = "/opt/cni/bin"
  conf_dir = "/etc/cni/net.d"
  max_conf_num = 1
  conf_template = ""

[plugins."io.containerd.grpc.v1.cri".registry]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors]
    [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
      endpoint = ["https://registry-1.docker.io"]

[plugins."io.containerd.grpc.v1.cri".image_decryption]
  key_model = ""

# ... 其他配置 ...

[plugins."io.containerd.monitor.v1.cgroups"]
  no_prometheus = false

[plugins."io.containerd.runtime.v1.linux"]
  shim = "containerd-shim"
  runtime = "/usr/local/Ascend/Ascend-Docker-Runtime/ascend-docker-runtime"
  runtime_root = ""
  no_shim = false
  shim_debug = false

[plugins."io.containerd.runtime.v2.task"]
  platforms = ["linux/amd64"]

配置方式二：Cgroup v2

需要修改以下关键配置项：

BinaryName = "/usr/local/Ascend/Ascend-Docker-Runtime/ascend-docker-runtime"

完整配置示例：

[plugins."io.containerd.grpc.v1.cri".containerd.default_runtime.options]

[plugins."io.containerd.grpc.v1.cri".containerd.runtimes]
  [plugins."io.containerd.grpc.v2.cri".containerd.runtimes.runc]
    base_runtime_spec = ""
    cni_conf_dir = ""
    cni_max_conf_num = 0
    container_annotations = []
    pod_annotations = []
    privileged_without_host_devices = false
    runtime_engine = ""
    runtime_path = ""
    runtime_root = ""
    runtime_type = "io.containerd.runc.v2"
    
    [plugins."io.containerd.grpc.v2.cri".containerd.runtimes.runc.options]
      BinaryName = "/usr/local/Ascend/Ascend-Docker-Runtime/ascend-docker-runtime"
      CriuImagePath = ""
      CriuPath = ""
      CriuWorkPath = ""
      IoGid = 0
      IoUid = 0
      NoNewKeyring = false
      NoPivotRoot = false
      Root = ""
      ShimCgroup = ""
      SystemdCgroup = true

提示：查看 cgroup 版本可执行 stat -fc %T /sys/fs/cgroup/，输出 cgroup2fs 表示 v2，输出 tmpfs 表示 v1。

重启服务

1
2

systemctl daemon-reload
systemctl restart containerd kubelet

验证安装

在 Kubernetes 主节点执行以下命令，确认昇腾计算节点状态正常：

`1`	`kubectl get nodes`

预期输出示例：

1
2
3

NAME              STATUS   ROLES           AGE   VERSION
k8s-master        Ready    master,worker   3d    v1.28.12
k8s-worker        Ready    worker          3d    v1.28.12

所有节点状态应显示为 Ready。

部署 Ascend Device Plugin

Ascend Device Plugin 负责在 Kubernetes 中管理和分配 NPU 资源。

准备镜像

1. 拉取镜像

在昇腾计算节点上执行以下命令拉取所需镜像：

# 拉取所有必需镜像
docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/resilience-controller:v7.1.RC1
docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/ascend-operator:v7.2.RC1
docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/npu-exporter:v7.2.RC1
docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/ascend-k8sdeviceplugin:v7.2.RC1
docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/vc-controller-manager:v1.7.0-v7.2.RC1
docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/vc-scheduler:v1.7.0-v7.2.RC1
docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/noded:v7.2.RC1
docker pull --platform=arm64 swr.cn-south-1.myhuaweicloud.com/ascendhub/clusterd:v7.2.RC1

2. 导出镜像

docker save -o ascend.tar \
  swr.cn-south-1.myhuaweicloud.com/ascendhub/resilience-controller:v7.1.RC1 \
  swr.cn-south-1.myhuaweicloud.com/ascendhub/ascend-operator:v7.2.RC1 \
  swr.cn-south-1.myhuaweicloud.com/ascendhub/npu-exporter:v7.2.RC1 \
  swr.cn-south-1.myhuaweicloud.com/ascendhub/ascend-k8sdeviceplugin:v7.2.RC1 \
  swr.cn-south-1.myhuaweicloud.com/ascendhub/vc-controller-manager:v1.7.0-v7.2.RC1 \
  swr.cn-south-1.myhuaweicloud.com/ascendhub/vc-scheduler:v1.7.0-v7.2.RC1 \
  swr.cn-south-1.myhuaweicloud.com/ascendhub/noded:v7.2.RC1 \
  swr.cn-south-1.myhuaweicloud.com/ascendhub/clusterd:v7.2.RC1

3. 导入到 Containerd

`1`	`ctr -n k8s.io images import ascend.tar`

下载部署配置文件

前往官方 Git 仓库下载 Ascend Device Plugin 安装包。

示例：Ascend-mindxdl-device-plugin_7.2.RC1.SPC2_linux-aarch64.zip

解压后将对应的 YAML 文件拷贝到 Kubernetes 管理节点。

选择合适的 YAML 文件

根据实际设备类型和是否使用 Volcano 调度器选择对应的 YAML 文件：

YAML 文件名称	适用场景
`device-plugin-310-v{version}.yaml`	Atlas 300I 推理卡，不使用 Volcano
`device-plugin-310-volcano-v{version}.yaml`	Atlas 300I 推理卡，使用 Volcano
`device-plugin-310P-1usoc-v{version}.yaml`	Atlas 200I SoC A1 核心板，不使用 Volcano
`device-plugin-310P-1usoc-volcano-v{version}.yaml`	Atlas 200I SoC A1 核心板，使用 Volcano
`device-plugin-310P-v{version}.yaml`	Atlas 推理系列产品（如 310P），不使用 Volcano
`device-plugin-310P-volcano-v{version}.yaml`	Atlas 推理系列产品，使用 Volcano
`device-plugin-910-v{version}.yaml`	Atlas 训练系列产品/A2/A3/800I A2，不使用 Volcano
`device-plugin-volcano-v{version}.yaml`	Atlas 训练系列产品/A2/A3/800I A2，使用 Volcano

注意：

对于 Ascend 310P 设备，通常选择 device-plugin-310P-v{version}.yaml

请勿修改 YAML 文件中的 DaemonSet.metadata.name 字段，以免自动识别功能异常

部署 Device Plugin

1
2

# 请修改镜像名称为：swr.cn-south-1.myhuaweicloud.com/ascendhub/ascend-k8sdeviceplugin:v7.2.RC1
kubectl apply -f device-plugin-310P-v7.2.RC1.SPC2.yaml

预期输出：

serviceaccount/ascend-device-plugin-sa created
clusterrole.rbac.authorization.k8s.io/pods-node-ascend-device-plugin-role created
clusterrolebinding.rbac.authorization.k8s.io/pods-node-ascend-device-plugin-rolebinding created
daemonset.apps/ascend-device-plugin-daemonset created

验证部署

查看 Device Plugin 是否启动成功：

`1`	`kubectl get pod -n kube-system \| grep ascend`

预期输出（状态应为 Running）：

1
2

NAME                                   READY   STATUS    RESTARTS   AGE
ascend-device-plugin-daemonset-d5ctz   1/1     Running   0          11s

查看节点 NPU 资源：

`1`	`kubectl describe node <node-name> \| grep -A 5 "Capacity:"`

应能看到 huawei.com/Ascend310P 资源。

使用 NPU 计算卡

Pod 配置示例

在 Pod 定义中通过 resources 字段申请 NPU 资源：

apiVersion: v1
kind: Pod
metadata:
  name: npu-test-pod
spec:
  containers:
    - name: alg-container
      image: ubuntu:22.04
      resources:
        limits:
          memory: 24Gi
          huawei.com/Ascend310P: 1  # 申请 1 张 NPU 卡
        requests:
          memory: 2Gi
          huawei.com/Ascend310P: 1  # 申请 1 张 NPU 卡
      command: ["/bin/bash", "-c", "sleep infinity"]

说明：

huawei.com/Ascend310P 的值表示申请的 NPU 卡数量

limits 和 requests 中的值应保持一致

根据实际 NPU 型号调整资源名称（如 310、910 等）

昇腾 NPU on Kang's Blog

昇腾 K8s 环境部署指南

昇腾 K8s 环境部署指南

概述

准备工作

创建节点标签

创建系统用户

创建日志目录

安装 Ascend Docker Runtime

下载安装包

安装步骤

步骤 1：进入安装包目录

步骤 2：校验安装包完整性

步骤 3：添加可执行权限

步骤 4：执行安装

配置 Containerd

配置方式一：Cgroup v1

配置方式二：Cgroup v2

重启服务

验证安装

部署 Ascend Device Plugin

准备镜像

下载部署配置文件

选择合适的 YAML 文件

部署 Device Plugin

验证部署

使用 NPU 计算卡

Pod 配置示例