1. 版本申明¶
| 版本 | 修改内容 | 修改时间 |
|---|---|---|
| v1.0 | 初始化 | 5/12/2022 |
| v1.1 | 新增二次开发说明 | 5/22/2023 |
| v1.2 | 更新组件文档说明 | 6/25/2023 |
| v1.3 | 更新组件说明 | 7/03/2023 |
| v1.4 | 更新一些词语 | 12/12/2023 |
| v1.5 | 更新一些格式以及内容 | 4/8/2024 |
| v1.6 | 更新异构平台部分 | 5/20/2024 |
| v1.7 | 更新格式部分 | 6/24/2024 |
2. 简介¶
TopsCloud 是基于GCU的云原生解决方案包，其包括enflame-container-toolkit，k8s-device-plugin，gcu-exporter，gcu-operator等重要组件用于支持GCU K8S集群。
3. 专有名词解释¶
| 名词 | 描述 |
|---|---|
| TopsCloud | 燧原基于GCU的K8S集群化解决方案 |
| enflame-container-toolkit | 燧原基于GCU的容器化插件 |
| k8s-device-plugin | 燧原基于GCU的k8s插件，向k8s集群注册GCU资源 |
| gcu-exporter | 燧原GCU的数据采集组件，提供gcu设备运行相关指标的时序数据 |
| gcu-feature-discovery | 用于给GCU设备打上标签 |
| node-feature-discovery | 用于给服务器设备打上标签 |
| gcu-operator | 自定义资源GcuResource用于自动化管理gcu软件 |
| go-eflib | golang 二次开发库 |
4. 文档使用说明¶
4.1. k8s-device-plugin使用说明¶
见《K8S Plugin用户使用手册》。
4.2. enflame-container-toolkit使用说明¶
见《Container Toolkit用户使用手册》。
4.3. gcu-operater使用说明¶
见《GCU Operator用户使用手册》。
4.4. gcu-exporter使用说明¶
见《GCU Exporter用户使用手册》。
4.5. gcu-feature-discovery使用说明¶
见《GCU Feature Discovery用户使用手册》。
4.6. node-feature-discovery使用说明¶
见《Node Feature Discovery用户使用手册》。
4.7. 其他组件¶
其他独立组件见相应的组件文档，确认依赖组件已就绪后，依照用户手册进行安装使用。
5. 二次开发用户使用说明¶
5.1. 一般用户（内网用户）¶
见相应的独立组件用户使用手册。
5.2. 需要二次开发的外网用户¶
除了参考相应的独立组件用户使用手册之外，安装包的Yaml配置文件里涉及容器镜像填写的地方需要用户自我定义以及根据实际使用情况来修改，
可以通过命令:find . -name "*.yaml" | xargs grep "artifact.enflame.cn/enflame_docker_images/enflame" 找到相关文件，例如：
# cd topscloud_<VERSION>
# find . -name "*.yaml" | xargs grep "artifact.enflame.cn/enflame_docker_images/enflame"
./k8s-device-plugin_2.0.0.beta1/yaml/enflame-device-plugin.yaml: \
- image: artifact.enflame.cn/enflame_docker_images/enflame/k8s-device-plugin:v2.0.0 \
./k8s-device-plugin_2.0.0.beta1/yaml/enflame-device-plugin-pcie-switch-affinity.yaml: \
- image: artifact.enflame.cn/enflame_docker_images/enflame/k8s-device-plugin:v2.0.0 \
./k8s-device-plugin_2.0.0.beta1/yaml/enflame-device-plugin-compat-with-cpumanager.yaml: \
- image: artifact.enflame.cn/enflame_docker_images/enflame/k8s-device-plugin:v2.0.0 \
./gcu-feature-discovery_1.2.10/yaml/gcu-feature-discovery-daemonset.yaml: \
- image: artifact.enflame.cn/enflame_docker_images/enflame/gcu-feature-discovery:latest \
./gcu-feature-discovery_1.2.10/all-in-one/yaml/all-in-one.yaml: \
image: artifact.enflame.cn/enflame_docker_images/enflame/enflame-device-plugin:latest \
............................................
./gcu-operator_2.2.22/enflame-resources/k8s-device-plugin/pcie-switch/daemonset.yaml: \
- image: artifact.enflame.cn/enflame_docker_images/enflame/k8s-device-plugin:latest \
./gcu-exporter_1.4.20/yaml/gcu-exporter-non-privileged.yaml: \
image: artifact.enflame.cn/enflame_docker_images/enflame/gcu-exporter:latest \
./gcu-exporter_1.4.20/yaml/gcu-exporter.yaml: \
image: artifact.enflame.cn/enflame_docker_images/enflame/gcu-exporter:latest \
./gcu-exporter_1.4.20/yaml/gcu-exporter-for-arm.yaml: \
image: artifact.enflame.cn/enflame_docker_images/enflame/gcu-exporter:latest
..............................................
注：除了以上文件，也需要二次开发用户根据自己的实际使用情况梳理且修改相应的镜像，避免遗漏。
6. GCU标签自动生成使用说明¶
6.1. 基础组件¶
enflame-container-toolkit
k8s-device-plugin
node-feature-discovery
gcu-feature-discovery
6.2. 基于NFD与GFD的使用方案¶
方案 1 - 同GPU方案¶
该方案部署方式同GPU，基本使用过程示例如下,该方案方便与用户已有的GPU方案保持一致，便于后续升级维护。
1，用户先安装 enflame-container-toolkit以及k8s-device-plugin
2，安装node-feature-discovery，步骤如下：
cd node-feature-discovery_<VERSION>
# 构建node-feature-discovery镜像
./build-image.sh
# apply namespace 为 enflame.com 的nfd yaml，这里也可以修改deploy.sh 执行
kubectl apply -f yaml/nfd.yaml
或
# tke cloud用户 apply namespace 为 tke.cloud.tencent.com 的nfd yaml，这里也可以修改deploy.sh 执行
kubectl apply -f yaml/tke-cloud-nfd.yaml
3，安装gcu-feature-discovery
cd gcu-feature-discovery_<VERSION>
# 构建gcu-feature-discovery镜像
./build-image.sh
# apply gfd daemonset, 这里也可以修改deploy.sh 执行
kubectl apply -f yaml/gcu-feature-discovery-daemonset.yaml
方案 2 - 镜像与DaemonSet合一方案¶
k8s-device-plugin + node-feature-discovery + gcu-feature-discovery 镜像与daemonset合一方案，基本使用过程示例如下：
1，用户先安装 enflame-container-toolkit
2，安装k8s-device-plugin + node-feature-discovery + gcu-feature-discovery
# 构建k8s-device-plugin + node-feature-discovery + gcu-feature-discovery镜像
执行./build-image.sh
# apply k8s-device-plugin + node-feature-discovery +
# gcu-feature-discovery三个文件合一的 yaml文件，这里也可以修改deploy.sh 执行
kubectl apply -f yaml/k8s-device-plugin-with-nfd-gfd.yaml
方案 3 - 自定义或自我开发¶
用户也可以基于api或提供的二进制文件，自我二次开发：
1）topscloud除了提供最基本的container-toolkit + k8s-device-plugin 之外
也提供 node-feature-discovery + gcu-feature-discovery二进制以及基本的编程示例以及使用手册，
由用户根据自己的实际使用场景进行DIY编程，达成内部最佳适用；
2）topscloud也提供go-zxlib api 库，用户可以基于这些API结合自有的k8s plugin manager 进行二次开发从而满足本身原有的使用案例的支持；
方案1结果如下（方案2类似）¶
GCU标签信息查看：
# kubectl get pod -A
NAMESPACE NAME \
READY STATUS RESTARTS AGE
..............................
kube-system etcd-sse-lg-112-32 \
1/1 Running 2 (58d ago) 64d
kube-system gcu-feature-discovery-cnm4h \
1/1 Running 0 19s
kube-system kube-apiserver-sse-lg-112-32 \
1/1 Running 2 (58d ago) 64d
kube-system kube-controller-manager-sse-lg-112-32 \
1/1 Running 2 (58d ago) 64d
kube-system kube-proxy-j2gbj \
1/1 Running 2 (58d ago) 64d
kube-system kube-scheduler-sse-lg-112-32 \
1/1 Running 2 (58d ago) 63d
kube-system nfd-fblrn \
2/2 Running 0 7m13s
..........................
# kubectl get nodes -o yaml
.................
creationTimestamp: "2024-03-13T10:16:16Z"
labels:
beta.kubernetes.io/arch: amd64
beta.kubernetes.io/os: linux
enflame.com/gcu.count: "8"
enflame.com/gcu.driverVer: 1.0.1.2
enflame.com/gcu.family: AAAA
enflame.com/gcu.machine: NF5468M5
enflame.com/gcu.memory: "32768"
enflame.com/gcu.model: TXTX
enflame.com/gcu.product: AAAA
enflame.com/gfd.latestLabeledTimestamp: 2024-05-20-06-40-27
enflame.com/gfd.timestamp: 2024-05-20-06-40-27
........................
标签使用编程示例¶
nodeSelector编程示例
spec:
nodeSelector:
enflame.com/gpu.product: AAAA # 假设我们想要的 GCU 产品型号
nodeAffinity编程示例
spec:
affinity:
nodeAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
- key: "enflame.com/gpu.product"
operator: "In"
values:
- "AAAA" # 假设我们想要的 GCU 产品型号
7. GCU标签手工生成使用说明¶
7.1. 如何给节点打上标签¶
命令行添加Labels示例¶
kubectl label nodes k8s-node1 enflame.com/gcu.product=AAAA # 为node加上标签
kubectl label --overwrite nodes k8s-node1 enflame.com/gcu.product=BBBB # 改写node标签
kubectl label nodes --all enflame.com/gcu.product=AAAA # 为所有node加上标签
kubectl label nodes k8s-node1 enflame.com/gcu.product- # 为node去除标签
yaml文件添加Labels示例¶
kind: Node
apiVersion: v1
metadata:
name: k8s-node1
labels:
enflame.com/gcu.product: AAAA
执行kubectl apply -f node.yaml即可进行标签的添加和覆盖
7.2. 为pod配置节点亲和性示例¶
将pod调度到具有特定标签的节点，有nodeSelector和nodeAffinity两种方式可以做到，这里使用节点亲和性（node affinity）作为示例。 这一过程需要在pod对象下的规约（spec）下添加亲和性描述，下面是一个描述pod对象的yaml文件，可以看到我们我们在pod的spec下增加了亲和性描述。
apiVersion: v1
kind: Pod
metadata:
name: pod-gcu-example
namespace: enflame
spec:
# restartPolicy: OnFailure
affinity:
nodeAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
nodeSelectorTerms:
- matchExpressions:
# 下面四行为匹配表达式的详细内容,支持
# In,Not In,Exist,Not Exist,Gt,Lt六种操作符
- key: enflame.com/gcu.product # GFD生成的标签
operator: In
values:
- AAAA
hostNetwork: true
containers:
- name: pod-gcu-example
image: ubuntu:18.04
imagePullPolicy: IfNotPresent
command: [ "sleep" ]
args: [ "100000" ]
...............................
7.3. 应用示例¶
利用一个两节点单master集群进行实验：
假设AAAA的卡所在node 1，按照以上步骤打上标签enflame.com/gcu.product=AAAA
假设BBBB的卡所在node 2，按照以上步骤打上标签enflame.com/gcu.product=BBBB
当values为BBBB时，通过kubectl get po -A -o wide可以看到，pod准确落在node2。
当values为AAAA时，通过kubectl get po -A -o wide可以看到，pod准确落在node1。
8. 常见问题¶
1）如何获取更多的文档？
可以联系客户支持相关部门获取。