环境准备

总述

本章节只适用于基于K8s的集群服务部署，不包含其他场景，其部署示意图如下图所示。

图 1 K8s集群整体部署视图

按照Server推理服务实例在集群计算节点（即推理服务器）上的分布和推理模式，可以分为以下两种部署形态。

表 1 部署形态

部署形态	含义
单机服务（非分布式）	单个Server可以独立作为推理服务实例对外提供推理服务，根据集群计算节点资源情况，整个集群可以支持一个或多个计算节点，单个计算节点可部署一个或多个Server，单机部署详情请参见单机（非分布式）服务部署。
PD分离服务	多个Server在一个或多个计算节点上联合部署，分为P实例（Prefill计算实例）和D实例（Decode计算实例），P实例与D实例分离部署，协同推理，整体作为一个Group对外提供推理服务，PD分离部署详情请参见PD分离服务部署。

说明

一体机单实例（单机蒸馏版或双机满血版）场景下，硬件故障会导致业务中断，业务恢复时长不可控，因此，一体机建议部署多实例，在单点硬件故障场景下可通过多实例之间的负载均衡继续提供业务。

软件环境

集群容器化部署依赖Kubernetes和MindCluster，具体部署场景请参考表1 依赖列表，Kubernetes组件详细介绍请参见Kubernetes安装工具；MindCluster组件详细介绍请参见《MindCluster 集群调度用户指南》中的组件介绍章节。

表 1 依赖列表

依赖包	软件说明	管理节点是否安装	计算节点是否安装
Kubernetes	-	-	-
kubectl	Kubernetes的命令行工具。	Y	N
kubeadm	创建和管理Kubernetes集群工具。	Y	Y
kubelet	在集群中的每个节点上用来启动容器。	Y	Y
MindCluster	-	-	-
Ascend Device Plugin	基于Kubernetes设备插件机制，提供昇腾AI处理器的设备发现、分配和健康状态上报功能，使能Kubernetes管理昇腾AI处理器资源。需安装Ascend Docker Runtime后方可使用。	N	Y
Ascend Operator	创建ranktable文件，并按照configmap映射的方式挂载到容器，可以实现多个节点NPU设备之间的数据通信和任务协调，优化集合通信建链性能。	Y	Y
Volcano	基于开源Volcano调度插件机制，增加昇腾AI处理器的亲和性调度、故障重调度等特性，最大化发挥昇腾AI处理器计算性能。	Y	Y
Ascend Docker Runtime	提供docker或containerd的昇腾容器化支持，自动挂载所需文件和设备依赖。	N	Y

Kubernetes安装与配置

安装Kubernetes

安装方式一（推荐）：

参考Kubernetes官网进行安装。

安装Kubernetes的kubectl、kubeadm和kubelet工具。
说明
- 支持Kubernetes的版本为1.18.x~1.25.x，推荐使用1.19.x及以上版本。
- kubeadm和kubelet需要安装在所有节点上，kubectl只需要安装在管理节点上。
使用kubeadm工具创建Kubernetes集群，安装kubeadm和创建Kubernetes集群请参见Kubernetes官网中的使用Kubeadm创建集群章节。

说明
集群初始化过程如遇到问题，请参见《MindCluster 集群调度用户指南》的“参考 > FAQ > 安装时出现的故障 > 初始化kubernetes失败”章节。

安装方式二：

参考阿里镜像源安装Kubernetes，以下操作均在管理节点进行。推荐使用ARM架构，请用户选择架构为ARM的软件版本。

获取Kubernetes的kubectl、kubeadm和kubelet软件包，以v1.25版本为例。
1. 单击阿里Kubernetes镜像官网。
2. 在阿里Kubernetes镜像官网单击“简介”中“新版下载地址”后方的链接，然后进入/core/stable/v1.25/rpm/aarch64目录获取kubectl、kubeadm和kubelet的安装包。
参考阿里Kubernetes镜像官网首页进行安装Kubernetes的kubectl、kubeadm和kubelet工具。
说明
如果出现 “No match for argument: socat” 或者 “nothing provides socat needed by xxx” 等回显信息，表示环境缺少socat库，解决方式如下所示。（其他库缺失也会有同样的回显，比如iptables、conntrack等）使用以下命令自行安装缺失的库。
```
#以CentOS系统为例
yum install -y socat
#以Ubuntu系统为例
apt-get install -y socat
```
执行以下命令查询部署Kubernetes需要的依赖和镜像，如图2 所需依赖及镜像查询结果所示。
```
kubeadm config images list
```
图 2 所需依赖及镜像查询结果

根据查询结果，用户需自行通过docker pull的方式依次进行安装，示例命令如下所示。
```
docker pull k8s.gcr.io/kube-apiserver:v1.23.0
```
使用以下命令初始化Kubernetes集群，当出现如图3 Kubernetes集群初始化成功所示回显时，表示初始化成功。
```
kubeadm init
```
图 3 Kubernetes集群初始化成功

然后执行图3 Kubernetes集群初始化成功中的内容，如下所示：
```
mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config
```
执行以下命令查看当前默认启动项状态是否正常，如图4 查看状态所示，状态为Running即为正常。
```
kubectl get pods -A
```
图 4 查看状态
（可选）如出现coredns开头的服务出现非running状态，需要在k8s集群中加入网络协议框架服务，推荐使用calico框架（如果pod状态无问题可忽略本步骤）。
1. 执行以下命令获取calico相关镜像（如果出现网络不通的问题，请重新设置网络代理环境变量）
```
docker pull calico/kube-controllers:v3.23.5
docker pull calico/cni:v3.23.5
docker pull calico/node:v3.23.5
```
  说明
  Kubernetes与calico的版本存在配套关系，请自行查询配套版本并下载使用。
2. 执行以下命令下载calico的yaml文件（此步骤执行完毕后需取消网络代理设置）。
```
curl -k -O https://docs.projectcalico.org/v3.23/manifests/calico.yaml
```
3. 执行vim calico.yaml命令修改文件，找到"CALICO_IPV4POOL_IPIP"字段（在约4444行左右），在下方添加如下内容
```
- name: IP_AUTODETECTION_METHOD
value: "interface=enp.*"
```
  说明
  该内容通过正则匹配的方式查找网卡，部分环境网卡名称存在差异，部署calico前推荐通过ifconfig查找所有服务器对应ip所在的网卡名称。如：预加入集群的部分环境存在将ip配置在虚拟网卡的情况，如下例子中网卡名称为virbr0，和其他服务器不一致，calico.yaml文件的配置需要涵盖所有节点的网卡名称，此时可以将该字段配置为"interface=enp.*|virbr0"
```
# ifconfig
virbr0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
        inet 141.61.21.1  netmask 255.255.252.0  broadcast 141.61.23.255
```
  图 5 修改内容展示
4. 启动calico
```
kubectl apply -f calico.yaml
```
5. 重复第5步，可以观察到Pod状态恢复正常。

重置Kubernetes设置

执行以下命令可以重置Kubernetes设置，回显如图5 重置成功所示则表示重置成功。

kubeadm reset

图 5 重置成功

说明

重置成功后，用户需手动删除 {$HOME}/.kube/config文件，确保Kubernetes的配置全部删除。

Kubernetes集群增加计算节点

整个集群仅使用一台服务器的情况下，用户无需新增计算节点，可略过下面步骤。

待新增节点需满足以下要求：

已安装Kubernetes基本软件kubeadm和kubelet。

在管理节点上创建一个新增节点加入集群所需的token和ca-cert码。

token和ca-cert码的有效期为24小时，如果已过期，请使用以下命令创建。
- 创建token
```
kubeadm token create
```
- 创建ca-cert码
```
openssl x509 -pubkey -in /etc/kubernetes/pki/ca.crt | openssl rsa -pubin -outform der 2>/dev/null | openssl dgst -sha256 -hex | sed 's/^.* //'
```
说明
- 由于上述命令包含明文token，执行后可通过历史操作查询方式打印，导致敏感信息暴露，建议用户采用以下方式进行设置。
  - 在执行敏感命令前执行以下命令临时禁用历史操作查询功能。
```
set +o history
```
  - 完成敏感命令操作后执行以下命令恢复历史查询功能。
```
set -o history
```
在新节点上执行以下命令加入集群。
```
kubeadm join ip:port --token {token} \
        --discovery-token-ca-cert-hash sha256:{ca-cert码}
```
参数解释：
- ip:port：管理节点上Kubernetes的IP地址和端口。
- --token：节点加入的令牌。
- --discovery-token-ca-cert-hash：加入集群的证书哈希值。
在新节点上使用以下命令查询当前节点主机名称。
```
hostname
```
如节点主机名和集群中其他节点名称冲突，修改/etc/hostname文件更改节点的主机名。
在管理节点上使用以下命令kubectl get nodes -A查看节点信息，如图6 新增节点所示，localhost.localdomain即为新增节点。

图 6 新增节点
在管理节点上使用以下命令根据实际的NPU设备类型为新增节点打上accelerator=huawei-Ascend910或者accelerator=huawei-Ascend310x标签。
```
#kubectl label nodes {节点名称} accelerator=huawei-Ascend910
kubectl label nodes localhost.localdomain accelerator=huawei-Ascend910
```
在管理节点上使用以下命令查看为新增节点打上的"accelerator=huawei-Ascend910"标签，如图7 accelerator=huawei-Ascend910标签所示，有"accelerator=huawei-Ascend910"则表示成功。
```
kubectl get nodes --show-labels
```
图 7 accelerator=huawei-Ascend910标签

Kubernetes日志打印转储轮转

说明： 以下日志轮转配置需要在Kubernetes集群的所有节点（包括管理节点和工作节点）上进行操作。

在管理节点上执行以下命令，查看当前集群节点所使用的容器运行时（Container Runtime）。
```
kubectl get node -o wide
```
通过观察输出结果中的 CONTAINER-RUNTIME 列，确认节点使用的是 docker 还是 containerd。
根据不同的容器运行时环境，分别修改对应的配置文件以配置日志转储轮转。
- 如果容器运行时为 Docker：
  
  修改 /etc/docker/daemon.json 文件，在其中添加或更新 log-opts 配置项（建议最大日志文件大小设置为20MB，最大文件数量设置为10，用户可按需自行配置）：
```
{
  "log-opts": {
    "max-size": "20m",
    "max-file": "10"
  }
}
```
  修改完成后，执行以下命令重启 Docker 服务使配置生效。
```
systemctl daemon-reload
systemctl restart docker
```
- 如果容器运行时为 Containerd：
  
  修改 Kubelet 配置文件（通常为 /var/lib/kubelet/config.yaml）。在配置文件中与 apiVersion 和 kind 同级的位置添加或修改以下参数（建议最大日志文件大小设置为20MB，最大文件数量设置为10，可按需修改）：
```
apiVersion: kubelet.config.k8s.io/v1beta1 # 仅作位置参考，无需修改
kind: KubeletConfiguration                # 仅作位置参考，无需修改
...
containerLogMaxSize: "20Mi"               # 需要添加或修改的配置项
containerLogMaxFiles: 10                  # 需要添加或修改的配置项
```
  修改完成后，执行以下命令重启 Kubelet 服务使配置生效。
```
systemctl daemon-reload
systemctl restart kubelet
```

MindCluster组件安装

集群管理组件依赖MindCluster中的Ascend Docker Runtime、Ascend Device Plugin、Volcano和Ascend Operator组件。其中Volcano和Ascend Operator组件在管理节点安装，其他组件在计算节点上安装。

请参考《MindCluster 集群调度用户指南》的安装前准备章节完成创建节点标签、创建用户、创建日志目录和创建命名空间。
请参考《MindCluster 集群调度用户指南》的Ascend Docker Runtime章节中的 “Containerd场景下安装Ascend Docker Runtime” 安装Ascend Docker Runtime。
请参考《MindCluster 集群调度用户指南》的Ascend Device Plugin章节安装Ascend Device Plugin，使用device-plugin-xxx-v {version}.yaml文件进行安装。

说明
当Ascend Device Plugin启动时，xxx.yaml配置文件中useAscendDocker参数配置为true且用户已安装Ascend Docker Runtime并生效，会自动挂载在 “/usr/local/Ascend” 下驱动相关目录。
请参考《MindCluster 集群调度用户指南》的Volcano章节安装Volcano。
说明
- 请使用v1.7.0版本的Volcano进行安装。
- 在单机场景下，参考《MindCluster 集群调度用户指南》的Volcano章节安装Volcano时，在执行“Volcano”章节中的步骤9前，需要修改Volcano解压后生成的volcano-v1.7.0目录下的volcano-v1.7.0.yaml文件，搜索"useClusterInfoManager"字段并将该值改为"false"，如下图所示，修改完成后，再执行“Volcano”章节中的步骤9。
请参考《MindCluster 集群调度用户指南》的Ascend Operator章节安装Ascend Operator。