概述

boyue vGPU軟件是一個為雲或者資料中心內的AI應用，CUDA應用提供GPU資源池化，提供GPU虛擬化能力的系統軟體。通過高效的通訊機制，使得AI應用，CUDA應用可以運行在雲或者資料中心內任何一個物理機，Container或者VM內而無需掛載物理GPU。同時為這些應用程序提供在GPU資源池中的硬體算力。通過這種boyue GPU池化的能力，可以提供多個優點：

兼容已有的AI應用和CUDA應用，使其仍然具有使用GPU加速的效能
为AI應用和CUDA應用在云和数据中心的部署提供了很大的灵活度。无需受GPU服务器位置、资源数量的约束。
boyue GPU资源随AI應用和CUDA應用启动时分配，随應用程序退出时自动释放。减少GPU空闲时间，提高共享GPU的周转率。
通過對GPU資源池的管理和優化，提高整個雲和資料中心GPU的利用率和吞吐率。
通過統一管理GPU，減輕GPU的管理複雜度和成本。

支持清單

處理器

x86_64

作業系統

64位CentOS 6 /7
64位 Ubuntu 16 / 18 / 20

NVIDIA GPU

NVIDIA Tesla系列：H系列、L系列、A系列、T系列、V系列、P系列、M系列
NVIDIA GeForce系列：RTX 30系列、RTX 20系列、GTX 10系列、GTX 98/97/96/95/75系列
NVIDIA Quadro 系列：RTX系列、GV/GP系列、P系列、M系列

寒武紀 MLU

MLU-370-X4 / X8
MLU-270-X5K

中科海光 DCU

Z100L、Z100

NVIDIA CUDA

CUDA 12.0，12.1
CUDA 11.0, 11.1, 11.2, 11.3, 11.4，11.5，11.6，11.7，11.8
CUDA 10.0, 10.1, 10.2
CUDA 9.0, 9.1, 9.2

寒武紀 Neuware

Neuware-3.4.2
Neuware-3.0.2
Neuware-2.8.5
Neuware-2.7.3
Neuware-2.6.4
Neuware-2.5.2

中科海光 DTK

DTK-22.04

深度學習框架

TensorFlow for CUDA : 1.8 - 2.12
TensorRT : 5.x / 6.x / 7.0 / 7.1 / 7.2 /8.x
Pytorch for CUDA : 1.0 - 2.0
PaddlePaddle: 1.5 / 1.6 / 2.0 / 2.1 / 2.2/ 2.3.2
ONNX : 1.0 / 1.1 / 1.2 / 1.3 / 1.4 / 1.5 / 1.6 / 1.7 / 1.8 / 1.9 / 1.10 / 1.11/1.12
MXNet :1.4.1 / 1.6 / 1.7 / 1.8 / 1.9
XGBoost :0.72、0.8、0.9
NVCaffe :1.0
Cambricon Tensorflow for Neuware:1.15 / 2.4
Cambricon Pytorch for Neuware:1.6 / 1.9
Cambricon Tensorflow Horovod:0.12.1
Cambricon Magicmind:0.6
DTK Tensorflow :1.15/2.7
DTK PyTorch:1.10
DTK PaddlePaddle:2.3.0

網絡

TCP/IP以太網络
RDMA網络（InfiniBand和RoCE）

容器環境

Docker 12.03 及以後版本

虛擬化環境

QEMU-KVM (QEMU 2.8以上)

容器框架

Kubernetes 1.10 及以後版本

更多相容環境未逐一列出，聯繫我們詳細瞭解

已知問題

下麵列出當前版本不支持的CUDA庫、工具以及使用模式

不支持CUDA應用程序使用 Unified Memory
不支持 nvidia-smi 工具
有限支持CUDA IPC，對部分程式可能不支持。

必要組件介紹

boyue Controller

該組件為一個長運行的服務程式，其負責整個GPU資源池的資源管理。其響應boyue Client的vGPU請求，並從GPU資源池中為boyue Client端的CUDA應用程序分配並返回boyue vGPU資源。
該組件可以部署在資料中心任何網絡可到達的系統當中。每個資源池部署一個該組件。資源池的大小取決於IT管理的需求，可以是整個資料中心的所有GPU作為一個資源池，也可以每個GPU服務器作為一個獨立的資源池。

boyue Server

該組件為一個長運行的系統服務，其負責GPU資源化的後端服務程式。 boyue Server部署在每一個CPU以及GPU節點上，接管本機內的所有物理GPU。通過和boyue Controller的互動把本機的GPU加入到由boyue Controller管理維護的GPU資源池當中。
當boyue Client端應用程序運行時，通過boyue Controller的資源調度，建立和boyue Server的連接。 boyue Server為其應用程序的所有CUDA調用提供一個隔離的運行環境以及真實GPU硬體算力。

boyue Client

該組件為一個運行環境，其類比了NVidia CUDA的運行庫環境，為CUDA程式提供了API介面相容的全新實現。通過和boyue其他功能組件的配合，為CUDA應用程序虛擬化了一定數量的虛擬GPU（boyue vGPU）。
使用CUDA動態連結程式庫的CUDA應用程序可以通過作業系統環境設定，使得一個CUDA應用程序在運行時由作業系統負責連結到boyue Client提供的動態連結程式庫上。由於boyue Client類比了NVidia CUDA運行環境，囙此CUDA應用程序可以透明無修改地直接運行在boyue vGPU之上。

典型部署架構

以下介紹兩種常見的boyue GPU資源池化部署方案。一種是All-in-One的本地GPU虛擬化方案，一種是部署到分佈式多臺物理機的GPU資源池化方案。

boyue GPU 資源池化方案

分佈式GPU資源池化方案指的是把一臺或者多臺服務器內的GPU作為資源池，通過boyue向局域網內任一個物理機、Container或者VM內的CUDA應用程序提供虛擬化GPU的部署管道。
選擇局域網內至少一個Linux服務器部署boyue Controller。該Controller必須可以被屬於同一個資源池的其他boyue組件通過網絡訪問。
每一個服務器上部署boyue Server服務，boyue Server自動適配該服務器是否安裝有GPU，從而開啟不同的功能。在每一個需要運行CUDA應用程序的物理機、Container和VM裏部署boyue Client運行庫。各個boyue組件通過boyue Controller的控制功能完成服務發現，資源調度等功能。
從邏輯上，以上各個boyue組件使用了control plane和data plane兩套網絡。其中control plane用於和boyue Controller組件的通訊。該部分通訊流量不大，對網路延遲和頻寬需求不高。 data plane用於boyue Client和boyue Server之間執行CUDA任務之間的通訊。該部分對於網絡的延遲和頻寬有一定需求。建議使用支持RDMA的網絡。在實際環境中，control plane和data plane可以是同一個物理網絡。

安裝部署

以下安裝部署的步驟，說明，均以boyue套裝軟體存放路徑在/root/boyue為例進行說明

GPU Monitor

該組件為可選組件，用於監控物理GPU的利用率。如果生產環境中已有其他替代的功能，該組件可以不用部署。

環境依賴

Docker容器環境
與Docker版本匹配的Nvidia Docker runtime
Nvidia GPU驅動

執行如下命令導入容器鏡像，並運行服務

cd /root/boyue/gpu-monitor
gunzip dcgm-exporter.tar.gz | docker load
gunzip node-exporter.tar.gz | docker load
./run-nvidia-exportor.sh

boyue Controller

boyue Controller包括物理GPU管理，vGPU資源分配，GUI監控，管理功能。在典型使用場景下，在一個分佈式環境，僅需要部署一個實例。以下通過容器化部署boyue Controller。

環境依賴

Docker容器環境

啟動文件下載

用戶在部署boyue Controller之前，需確保已經下載啟動檔案。

如何下載啟動檔案：

進入數字中國官网

進入產品頁面

經管理員稽核後，成功申請試用，或者已經付費購買的用戶，可以進入您的個人中心頁面，點擊“下載啟動檔案”按鈕獲取您的啟動檔案。對於聯網環境和非聯網環境的用戶，需要下載啟動檔案的管道有所不同，詳情請參攷“下載啟動檔案”頁面描述。

进入/root/boyue/controller目录

cd /root/boyue/controller

用您下載到的啟動檔案license.txt替換/root/boyue/controller目錄裏的已有的license.txt即可。

啟動 boyue Controller 服務

執行如下命令導入容器鏡像，並運行服務

cd /root/boyue/controller
gunzip boyue-controller-ent-2.2.tar.gz | docker load
gunzip prometheus.tar.gz | docker load

編輯設定檔 /root/boyue/controller/prometheus.yml 修改staticconfigs中的targets 清單，該清單是安裝了GPU Monitor服務的GPU服務器的清單。當GPU Monitor有多個IP網段地址的時候，該地址應該與第3章節部署boyue Server時綁定的數據網段相同，例如檔案中的“boyueBINDADDR=CCCC”地址，或者是boyue Server的設定檔中的bindaddr相同。
執行如下命令運行boyue Controller服务：

cd /root/boyue/controller
./run-controller.sh

服務成功啟動後，根據荧幕輸出提示，在本宿主機的所有網段提供如下服務：

調度服務：部署boyue Server時需要配寘該地址
Web GUI服務：通過瀏覽器訪問該服務進行監控和管理

boyue Controller的日誌檔

boyue Controller的日誌檔存放在boyue Controller容器內的/root/controller.log中

boyue Server

boyue Server為GPU資源池化提供底層的虛擬GPU服務。在所有的CPU節點、GPU節點均需部署該服務。
boyue Server支持的虛擬化/容器平臺有：

Docker ：>= 1.13
Libvirt + QEMU-KVM : QEMU > 2.0.0

CUDA業務運行KVM虛擬的場景，在把boyue Server部署至宿主機時，由於宿主機可能存在SELinux，apparmor的限制，安裝boyue Server之後的配寘，僅對安裝之後新創建的虛擬機器，或者是從Power OFF狀態重新啟動的虛擬機器生效。

環境依賴

對於無物理GPU的CPU節點

g++ 4.8.5 或以上版本
Linux基本庫依賴libcurl3, libibverbs1, numactl-libs（libnuma）, libvirt-devel
如果使用Mellanox RDMA網絡，需要安裝RDMA驅動，以及Mellanox的OFED

GPU節點額外的環境需求

安裝有 Nvidia 物理 GPU 驅動
NVIDIA CUDA SDK 9.0, 9.1, 9.2, 10.0, 10.1
NVIDIA CUDNN 7.4.2 以上版本，推薦 7.6.x
NVIDIA NCCL 和最高CUDA SDK版本匹配

在CPU、GPU 服務器宿主機執行如下命令安裝 boyue Server

cd /root/boyue/server
sudo ./install-server.sh

配寘 boyue Server

通過設定檔 /etc/boyue/server.conf 可以對 boyue Server 進行必要的配寘，其中支持的配置選項有：

[log]
log_with_time = true    ; 记录日志的时候是否添加时间戳
log_to_screen = true    ; 日志是否输出到屏幕的标准输出
log_to_file = true      ; 是否记录日志至磁盘文件中
log_level = INFO        ; 日志级别，支持 INFO， DEBUG
file_log_level = INFO   ; 日志输出到文件中的日志级别

[controller]
controller_addr = 127.0.0.1:9123    ; boyue Controller的调度器IP地址和端口

[server]
vgpu_count = 4          ; 默认一个物理GPU被拆分成多少个vGPU
bind_addr = 127.0.0.1   ; data plane的IP地址
;bind_net =             ; data plane的网络名字，例如eth0, eth1。bind_addr 和 bind_net 仅能配置1个
listen_port = 9960      ; boyue Server的服务端口
enable_kvm = true       ; 是否支持boyue Client运行在KVM的VM中
enable_shm = true       ; 是否使用共享内存加速通讯
enable_rdma = true      ; 是否使用RDMA加速通讯
ibverbs_device = mlx5_0 ; 如果使用RDMA，硬件设备名。仅在boyue Server无法推断硬件时需要配置

[server-nccl]
comm_id = 127.0.0.1:9970; nvidia NCCL通讯的网络和端口

[throttle]
throttle_level = 100                ; 算力控制的隔离程度，取值范围[0, 100]。数字越少隔离越好
enable_computation_throttle = true  ; 是否启动算力控制
computation_throttle_mode2 = true   ; 算力控制的模式，仅支持true

boyue Server任務控制

通過如下命令可以啟動boyue Server

sudo systemctl start boyued

通過如下命令可以執行其他boyue Server操作

sudo systemctl stop boyued      ## 停止boyue Server服务
sudo systemctl restart boyued   ## 重启boyue Server服务
sudo systemctl status boyued    ## 查看boyue Server服务状态
sudo systemctl enable boyued    ## 添加boyue Server服务到开机启动服务
sudo journalctl -u boyued       ## 查看boyue Server的服务日志

boyue Server的日誌檔

boyue Server的日誌存在兩個位置

/var/log/boyue/server.log 該檔案記錄了所有boyue Client的握手過程
/var/log/boyue/session 該目錄以單個檔案的形式，記錄了每次業務運行時的日誌。每運行一個boyue Client應用，該目錄產生一個獨立的日誌檔。如果在握手過程中失敗，則不產生日誌檔。

多版本 CUDA SDK 共存

boyue Server可以同時支持多個CUDA版本，使得依賴不同CUDA版本的上層應用可以同時使用boyue vGPU。為了支持多個CUDA SDK版本，boyue Server要求CUDA安裝在宿主機默認路徑（即/usr/local/cuda-x.y）下麵。例如為了支持 CUDA 10.0 和 CUDA 9.0，/usr/local 目錄下應該有 cuda-9.0 和 cuda-10.0 這兩個目錄。

此外，多CUDA版本共存時，不需要設定 CUDA_HOME，LD_LIBRARY_PATH 等環境變數，也不依賴於部分用戶環境中存在的軟連結 /usr/local/cuda => /usr/local/cuda-x.y，這是因為boyue Server可以根據boyue Client環境中實際安裝的Runtime對應於CUDA的版本號，動態選擇合適的CUDA SDK版本。

查看 boyue 服務狀態

在同一個局域網內，通過瀏覽器（推薦chrome）訪問boyue Controller所在環境的局域網地址： http://IP:Port
其中IP為boyue Controller所在環境的局域網地址，Port為部署boyue Controller時提示的Web GUI的服務埠。通過默認用戶名（密碼）登入進入系統：admin（admin）
在側邊欄裏看到boyue Controller的IP地址，點擊展開之後有如下的內容：

摘要：顯示boyue Controller所管理的整個boyue vGPU資源池的資源數量，節點狀態等
任務：顯示正在運行且使用了boyue vGPU資源的任務，以及每個任務使用的vGPU資源的分布情况
boyue GPU節點清單：通過點擊展開可以看到一組GPU節點的狀態，並且在每個節點的工作面板上看到物理GPU的劃分使用情况

部署 boyue Client

環境依賴

g++ 4.8.5 或以上版本，libcurl，openssl，libuuid, libibverbs1

軟體安裝

在CUDA應用環境執行如下的安裝命令

cd /root/boyue/client
sudo ./install-client-x.y

上述命令的x，y為根據所需CUDA版本選擇對應的installer，例如install-client-10.0 對應於 CUDA 10.0
上述命令把boyue Client環境安裝至默認路徑 /usr/lib/boyue 中，並通過 ldconfig 機制將 /usr/lib/boyue 添加到系統動態庫搜索路徑。
注意：如果boyue Client按照到和GPU同樣的宿主機環境，由於boyue Client安裝的/usr/lib/boyue和物理GPU的CUDA SDK可能存在版本衝突。對於同樣的動態庫在兩個不同磁片位置的加載順序，應該由安裝人員自己維護解决。

配寘 boyue Client

boyue Client 可以通過三類方法配寘運行參數

通過環境變數配寘運行參數
通過當前用戶home目錄中{$HOME}/.boyue/client.conf設定檔配寘運行參數
通過 /etc/boyue/client.conf 設定檔配寘運行參數

上述方法中，通過環境變數配寘的優先順序最高，系統/etc/boyue 目錄中設定檔的優先順序最低

boyue Client 的配寘中分為靜態配寘部分和動態配寘部分。

靜態配寘部分指的是在目標環境中每次運行CUDA應用程序都保持不變的部分。
動態配寘部分指的是根據CUDA應用程序使用的boyue vGPU資源不同而不同的配寘。

設定檔的格式為：

[log]
log_with_time = true    ; 记录日志的时候是否添加时间戳
log_to_screen = true    ; 日志是否输出到屏幕的标准输出
log_to_file = true      ; 是否记录日志至磁盘文件中
log_level = INFO        ; 日志级别，支持 INFO， DEBUG
file_log_level = INFO   ; 日志输出到文件中的日志级别

[controller]
controller_addr = 127.0.0.1:9123    ; boyue Controller的调度器IP地址和端口

[client]
enable_net = false      ; 是否使用TCP网络和boyue Server通讯

其中環境變數 boyueCONTROLLER 設定 boyue Controller 的地址具有比設定檔更高的優先順序例如在當前SHELL通過 export boyueCONTROLLER 環境變數可以忽略設定檔中的controller_addr配寘

動態配寘包括：

環境變數boyue_ VGPU設定當前環境下CUDA應用程序申請使用多少個boyue vGPU
- 例如通過export boyue_ VGPU=2指定了當前CUDA應用程序申請使用2個boyue vGPU
- 該配寘無預設值
環境變數boyue_ GMEM設定當前環境下，CUDA應用程序申請使用的每個boyue vGPU中的顯存大小。以MiB為組織。
- 例如通過export boyue_ GMEM=4096為當前CUDA應用程序指定了每個boyue vGPU的顯存大小為4096 MiB。
- 該配寘的預設值取決於默認一個物理GPU被切分為幾個vGPU
環境變數boyue_ RATIO設定當前環境下，CUDA應用程序申請使用的每個boyue vGPU佔用一個物理GPU算力的百分比。以%為組織
- 例如通過 export boyue_ RATIO=50 為當前CUDA應用程序指定了每個 boyue vGPU 的50%的算力。
- 該配寘的預設值取決於默認一個物理GPU被切分為幾個vGPU
環境變數 boyueCROSSNODE 為可選參數，參數為1且申請多個vGPU時，允許boyue Controller跨越多個物理GPU節點調度資源，使得分配的多個vGPU可能來自於不同的物理GPU節點。
- 該參數為1時，boyue_ RATIO必須為100
- 該配寘默認為0

boyue Client日志

boyue Client日誌位於執行應用程序的用戶home目錄中的 ${HOME}/.boyue/log 目錄中。每次CUDA應用運行均會在該目錄產生一個對應於該次任務的日誌檔。

使用boyue vGPU

本章節介紹在boyue Client環境中，如何為CUDA應用程序配寘使用boyue vGPU

boyue vGPU資源

通過安裝部署boyue vGPU軟件，所有boyue Server所在的GPU服務器內的GPU均加入了一個全域共亯的資源池。每個物理GPU均被劃分為多個邏輯vGPU。劃分vGPU的默認細微性為啟動boyue Server時，設定檔 /etc/boyue/server.conf 中的 vgpu_count 參數指定。若設定 vgpu_count=n，則每個vGPU默認的顯存大小為物理GPU顯存的n分之一。

boyue vGPU的使用

由於boyue vGPU的調用介面相容物理GPU的調用介面，囙此CUDA應用程序可以無感知無修改地像使用物理GPU那樣使用boyue vGPU。僅需要在運行CUDA應用程序時，通過設定檔、環境變數為本CUDA應用程序配寘運行環境即可。

經過boyue GPU資源池化之後，資源池中的vGPU使用模式為CUDA應用程序即時申請即時使用的模式。也即是當CUDA應用程序調用CUDA介面初始化時才向boyue GPU資源池申請一定數量的vGPU，當CUDA應用程序退出時其申請到的vGPU自動釋放至資源池中。多次調用CUDA應用程序分配到的vGPU不一定對應於同樣的物理GPU資源。

當boyue Client的靜態環境配寘完畢後，在運行一個CUDA應用之前，至少需要用boyue_ VGPU環境變數指明該CUDA應用程序希望獲得的vGPU數目。例如一個deviceQuery CUDA程式，如下的命令使得當該CUDA程式做設備發現時，通過CUDA的介面査詢到2個GPU，每個GPU的顯存是4096MiB。

export boyue_VGPU=2
export boyue_GMEM=4096
./deviceQuery

當上述deviceQuery CUDA程式啟動時，會從boyue GPU資源池中獨佔兩個vGPU。該程式結束時，會自動釋放兩個vGPU。可以通過重新設定環境變數，在運行CUDA應用程序之前改變對vGPU資源的使用。一次CUDA應用程序所申請的多個vGPU可能存在於多個物理GPU上。

vGPU的使用對象為CUDA應用程序，而非物理機、Container或者VM虛擬機器。即使在同一個環境下運行的多個CUDA應用程序，每一個應用程序都按照當前的運行環境向boyue GPU資源池申請獨立的vGPU資源。如果並行運行多個CUDA應用程序，則消耗的vGPU數量為應用程序數目乘以boyue_ VGPU所指定的vGPU數目。

常見問題

用戶首先需要確認boyue Server和boyue Client版本的匹配。不同版本之間的boyue Server和boyue Client無法共同使用。

boyue Client端應用程序啟動報告無法找到NVidia GPU
- 此故障為應用程序沒有使用boyue Client運行庫導致，可能的原因有幾種：
  - 該應用程序在編譯期間靜態連結了NVidia的庫，導致其運行時並不調用boyue Client的運行庫。該問題應該通過設定動態連結並重新編譯解决。
  - 該應用程序雖然使用CUDA相關的動態連結程式庫，但是編譯器使用rpath選項指明了CUDA庫加載的絕對路徑，而該路徑並非是boyue Client的安裝路徑。 rpath優先順序高導致庫加載的路徑非期望的boyue Client安裝路徑。該問題或者通過去掉rpath設定後重新編譯解决，或者用boyue Client運行庫覆蓋rpath指明的路徑內的庫解决。
  - boyue Client庫的安裝路徑沒有使用ldconfig或者環境變數LDLIBRARYPATH放到動態庫加載路徑。該問題通過使用ldconfig永久把boyue Client的安裝路徑加入到系統蒐索路徑，或者正確使用環境變數LDLIBRARYPATH來設定。
boyue Server服務無法啟動，boyued行程啟動失敗
- 通過運行boyue-check runtime server來檢查環境。可能的原因有
- boyued行程依賴CUDA，CUDNN庫無法蒐索到導致可執行文件無法被作業系統啟動。
  - 修改上述boyue Server服務設定檔
- boyued行程依賴的其他庫沒有安裝，例如libcurl，libopenssl等

boyue-Rancher集成指南

Rancher同數字中國達成戰略合作，加速GPU資源池化在Kubernetes中落地

面對Kubernetes使用GPU資源的眾多難題，Rancher與數字中國共同推出了面向Kubernetes的GPU資源池化聯合解決方案。Rancher可以同時管理多個Kubernetes集羣，用戶可以通過其內寘的應用市場Catalog開箱即用地將boyue部署至各個業務集羣，boyue具備專業的GPU池化和虛擬化功能，可以無侵入地綜合至Rancher託管的Kubernetes集羣當中。最終，用戶可以極為方便地在Rancher平臺上進行GPU資源調度，從而讓工作負載使用boyue提供的vGPU資源。

1. 使用Rancher中國提供的pandaria-catalog應用商店

boyue現已集成至Rancher中國的應用市場當中，開源用戶可以通過導入pandaria-catalog 獲取這一應用，企業用戶無需導入即可輕鬆使用。

Rancher中國企業版使用pandaria-catalog應用商店

Rancher中國企業版已默認集成pandaria-catalog應用商店。請使用v2.3.8-ent以上版本，該版本已經實現了工作負載對boyue vGPU的支持，運行管道：

sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443
cnrancher/rancher:v2.3.8-ent

在全域—工具—商店設定中，查看應用商店，企業版已經內寘了pandaria-catalog，並在其中內寘了boyue Chart。如圖所示：

Rancher企业版catalog

可以看到pandaria-catalog已經處於Active啟動狀態。

進入應用商店，可以看到virtaitech-boyue-vgpu應用。如圖所示：

應用清單

Rancher社区版使用pandaria-catalog應用商店

Rancher社區版也可以方便的一鍵部署：

sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 rancher/rancher

但是Rancher社區版並沒有默認配寘pandaria-catalog應用商店，需要用戶手動配寘。

進入Global-Apps-Manage Catalogs頁面：
添加catalog。如圖所示，首先點擊Add Catalog按鈕。填入Catalog URL和Branch=dev/v2.3。名稱可以隨意設定，範圍Scope則最好設定為全域global。
此時catalog配寘完成，可以去應用商店進行確認。

可以看到virtaitech-boyue-vgpu已經出現在應用商店內。

2. 環境要求

在部署boyue之前，客戶環境需要滿足一定條件：

部署boyue的Kubernetes版本需要>；= 1.6。 boyue會部署一個專用調度器boyue-scheduler，需要Kubernetes v1.6及以上版本支持。
客戶環境需要確保相應硬體的驅動已正確安裝，特別是NVidia GPU驅動。如果使用RDMA網卡，還需要確保RDMA驅動已正確安裝。
容器運行時 containerd 版本號>= 1.3.2。
在GPU節點上安裝好了NVidia docker runtime，並且已經設定為默認容器運行時。可以通過kubectl describe node [nodename]來檢測節點的容器運行時。
（關鍵）boyue要求所有節點上用於boyue通信的網卡使用相同名稱（例如eth0）。用戶務必確保這一前置條件滿足，否則boyue Server在沒有正確配寘網卡名稱的節點上無法正確啟動。請參攷下文常見問題一節。
（推薦）如果使用Mellanox RDMA網絡，需要安裝RDMA驅動，以及Mellanox的OFED。

3. 部署boyue

Rancher中國企業版部署boyue

選擇需要部署的Kubernetes集羣和對應Project，點擊啟動：
選擇virtaitech-boyue-vgpu：
在部署表單內對boyue進行配寘。具體配寘內容請參攷下文配寘詳情一節。
Rancher會自動拉取boyue的所有組件鏡像，用戶可以在Rancher內查看所有組件的運行狀態。

注：新版boyue只會部署在一個命名空間（namespace）內。

Rancher社區版部署boyue

在執行下述步驟之前，請務必參照Rancher社區版使用pandaria-catalog應用商店一節正確配寘應用商店。

選擇要部署boyue的集羣，以及對應的project。選擇Apps，點擊Launch。
選擇virtaitech-boyue-vgpu。
在部署表單內對boyue進行配寘。具體配寘內容請參攷下文配寘詳情一節。
查看所有boyue組件的狀態。

檢查節點標籤

boyue-helper會依據用戶配寘的Network Interface（例如eth0）自動獲取ip地址，並給Kubernetes節點打上標籤。可以在集羣-Nodes頁面查看到節點的標籤。所有需要運行boyue-server的節點都需要有正確的boyue_BIND_ADDR標籤。如下圖所示，只有一個節點ip-172-31-43-188正確標識了boyue_BIND_ADDR的值。boyue_BIND_ADDR沒有獲取到正確的值通常是因為Network Interface（例如eth0）與該節點的網卡名稱不匹配導致的。boyue_BIND_ADDR的值未正確設定會在某些情况下影響boyue的效能。

label

用戶可以通過Rancher上手動修改節點標籤，如下圖所示：

edit-node

edit-node2

查看部署相關資訊

boyue部署時使用的相關設定可以在部署後的應用介面查看。相關資訊會顯示在Notes（或注釋）和Answers（或應答）兩欄下，如下圖所示：

comm-notes

ent-notes

4. 配寘詳情

設定	說明	預設值	類型
Name（名稱）	Rancher App名稱	virtaitech-boyue-vgpu	string
Template Version（模板版本）	Chart版本	1.0.0	下拉式功能表
Namespace（命名空間）	Kubernetes命名空間，可以新建或者選擇現有命名空間	空	string
Use Default Image	使用默認鏡像，通常不需要修改。如有必要，請在數字中國工程師指導下修改這裡的設定。	True	bool
License Key	新版license。直接作為字串粘貼到這裡即可。注意舊版的license無法使用。請聯系數字中國獲取有效的license。	空	string
Controller Web Portal Password	登入controller webui的密碼（用戶為admin）。 controller的登入地址在應用部署完成介面的`Notes`一節可以查看。	空	string
Controller Token	controller的token。調用controller高級api時需要給出這裡設定的token。 controller的高級api檔案請詳詢數字中國客戶支援團隊。	空	string
boyue Resource Name	暴露給Kubernetes的boyue資源名稱，用戶端在申請boyue資源時，需要使用這裡設定的資源名稱。通常不需要修改。特別和Rancher中國企業版綜合時，修改這個名稱將導致Rancher中國企業版無法正確啟動boyue的用戶端。	virtaitech.com/gpu	string
Controller Quota	controller是否啟用quota。	false	bool
Server Cuda	server鏡像內使用的cuda版本，可選值為"9.0","9.1","9.2","10.0","10.1"。	10.1	string
Network Interface	（關鍵設定）boyue bind net的網卡名稱。該設定會指定boyue使用的網卡，特別當計算節點擁有多張網卡時，需要小心設定（例如，RDMA網卡和TCP網卡並存，最好指定RDMA網卡）。由於在Kubernetes環境下難以為每個節點獨立配寘boyue server並指定bind address，需要為所有節點通過統一的網卡名稱來配寘boyue網路環境。這會引入一個前提：如果有節點配寘使用的網卡名稱必須相同，否則必須請IT、運維人員做相應修改。	eth0	string
VGPU Numbers	每個物理GPU虛擬出幾個VGPU。	4	int
Infiniband Network Name	Infiniband網卡名稱。非必填項。	空	string

5. 測試

Rancher中國企業版部署使用boyue用戶端

默認情况下，UI中不會啟用boyue的支持參數，需要在啟用一個特殊Feature。在“全域—系統設置—功能選項”中，啟用virtaitech-gpu-service-ui，如圖所示：
選擇對應的集羣和Project，選擇資源-工作負載，部署一個工作負載。配寘用戶端鏡像，使用virtaitech/boyue-client-2.2:cuda10.1-tf1.14-py3.6-hvd。
設定boyue資源環境變數，具體為（請根據實際需求配寘）：

env:
- name: boyue_VGPU
 value: "1"
- name: boyue_GMEM
 value: "4096"
- name: boyue_RATIO
 value: "100"
# whether the boyue resources are revered or will be released after 30s idle.
# If the value is not set, the resources are reserved by default.
# Any value other than "1" will NOT reserve the resource.
- name: boyue_RESERVED
 value: "0"
- name: boyue_CROSS_NODE
 value: "0"
- name : boyue_GROUP_ID
valueFrom:
fieldRef:
 fieldPath: metadata.uid

各參數含義請參見下文boyue用戶端啟動配置說明。

client2

配寘使用boyue-scheduler調度器。
使用主機IPC命名空間，並申請boyue GPU資源。
待用戶端部署完成，可以在Rancher圖形介面上進入用戶端內執行命令。

例如可以執行：/root/cuda_samples/deviceQuery/deviceQuery。用戶端鏡像內`/root/cuda_samples路徑下有大量的測試用例供客戶使用。

Rancher社區版使用boyue

Rancher社區版缺少對boyue用戶端的一些綜合支持。用戶可以通過Kubernetes命令列工具部署boyue的用戶端。一個典型的測試yaml檔案如下（各參數含義請參見下文boyue用戶端啟動配置說明）：

# boyue-client.yaml
apiVersion: v1
kind: Pod
metadata:
name: testgpu
spec:
schedulerName: boyue-scheduler
hostIPC: true
containers:
- name: test
  image: virtaitech/boyue-client-2.2:cuda10.1-tf1.14-py3.6-hvd
  command: ["sh", "-c", "sleep infinity"]
  # Please make sure these values are properly set
  env:
  - name: boyue_VGPU
    value: "1"
  - name: boyue_GMEM
    value: "4096"
  - name: boyue_RATIO
    value: "100"
  # whether the boyue resources are revered or will be released after 30s idle.
  # If the value is not set, the resources are reserved by default.
  # Any value other than "1" will NOT reserve the resource.
  - name: boyue_RESERVED
    value: "0"
  - name: boyue_CROSS_NODE
    value: "0"
  - name : boyue_GROUP_ID
    valueFrom:
      fieldRef:
        fieldPath: metadata.uid
  resources:
    limits:
      # if you have changed Resource Name while deploying boyue services, please change this accordingly
      virtaitech.com/gpu: 1

可以通過kubectl apply -f boyue-client.yaml來部署用戶端。用戶端鏡像內`/root/cuda_samples路徑下有大量的測試用例供客戶使用。

boyue用戶端啟動配置說明

設定	說明	類型
`spec.schedulerName`	使用的Kubernetes調度器的名稱，請務必指定為`boyue-scheduler`	string
`spec.hostIPC`	請務必設定為`true`	bool
`spec.containers[].env[].name="boyue_VGPU"`	申請的boyue VGPU個數，注意這裡為字串。該值請務必設定為與`spec.containers[].resources.limits.virtaitech.com/gpu`相同。字串內容必須為正整數。	string
`spec.containers[].env[].name="boyue_GMEM"`	每個VGPU申請的顯存，組織為兆（MB）。字串內容必須為正整數。	string
`spec.containers[].env[].name="boyue_RATIO"`	每個VGPU佔用物理GPU算力的百分比。	string
`spec.containers[].env[].name="boyue_GROUP_ID"`	必須按照示例設定。	string
`spec.containers[].env[].name="boyue_RESERVED"`	boyue的資源分配模式。當設定為`1`時，boyue的資源分配與Kubernetes的pod的生命週期綁定。只要pod存在，則資源就會被保留，即使pod內沒有在使用資源。這種模式下資源無法超發。當值設定為除`1`以外的其它值時，boyue的資源只會（默認）預留`30s`。如果pod內沒有在使用boyue資源，則閒置`30s`後資源會被釋放。這種該模式下資源可以超發。默認為`1`。	string
`spec.containers[].env[].name="boyue_CROSS_NODE"`	使用跨節點GPU，默認為`0`。	string
`spec.containers[].resources.limits.virtaitech.com/gpu`	必須為正整數（Kubernetes限制）。請將該值設定與`spec.containers[].env[].name="boyue_VGPU"`相同。	int

進階說明

當boyue_RESERVED=1時，boyue_VGPU實際不生效（但需要設定），實際申請的VGPU資源數量基於spec.containers[].resources.limits.virtaitech.com/gpu。
當boyue_RESERVED!=1時，pod調度時申請的資源基於spec.containers[].resources.limits.virtaitech.com/gpu。但如果資源閒置30s被釋放後再次使用VGPU資源，則會依據boyue_VGPU（以及其它環境變數）的值申請資源。
當一個pod裡面有多個container時，boyue只會滿足第一個設定了spec.containers[].resources.limits.virtaitech.com/gpu的container資源申請要求。建議用戶使用時只在一個pod裡面讓一個container申請boyue資源。

使用示例

TensorFlow CNN Benchmark

在boyue用戶端內執行：

# 注意boyue_RESERVED=1时，用戶端內修改環境變數不生效
export boyue_VGPU=2
export boyue_GMEM=15000
export boyue_RATIO=100
python3 benchmarks/scripts/tf_cnn_benchmarks/tf_cnn_benchmarks.py \
  --model resnet50 \
  --batch_size 64 \
  --num_batches 40\
  --num_gpus=2

使用跨節點GPU時可以使用horovod

export boyue_VGPU=4
export boyue_GMEM=15000
export boyue_RATIO=100
export boyue_CROSS_NODE=1
horovodrun -np 4 -H localhost:4 python3 benchmarks/scripts/tf_cnn_benchmarks/tf_cnn_benchmarks.py \
  --model resnet50 \
  --batch_size 128 \
  --num_batches 400 \
  --variable_update horovod

Jupyter Notebook

# From inside boyue Client container
cd /root
pip3 install notebook
jupyter notebook --ip=0.0.0.0 --no-browser --allow-root

會看到類似於下麵的輸出：

# Omit output
To access the notebook, open this file in a browser:
  file:///root/.local/share/jupyter/runtime/nbserver-38-open
Or copy and paste one of these URLs:
  http://lab-0:8888/?token=4507dbe5c542dd570370c2425f14f83f06793da178978558
or http://127.0.0.1:8888/?token=4507dbe5c542dd570370c2425f14f83f06793da178978558

如果用戶可以使用這臺機器的圖形介面，那麼可以打開瀏覽器，輸入所提示地址 127.0.0.1:8888/?token=<token>。

否則，用戶可以在安裝了瀏覽器的節點（例如筆記型電腦）上進行SSH埠轉發：

# On laptop
ssh -Nf -L 8888:localhost:8888 <username@client-machine>

然後在本地瀏覽器裡面輸入 127.0.0.1:8888/?token=<token> 地址（將<token>替換成Jupyter Notebook所輸出的實際token）訪問Jupyter Notebook。

關於缺乏RDMA網路環境的說明

如果客戶環境缺乏RDMA網絡，需要手動開啟TCP網絡的支持（默認為關閉，以避免客戶在具有RDMA網路環境下錯誤的使用TCP網絡）。

kubectl exec -it pod/testgpu /bin/bash
vi /etc/boyue/client.conf

[log]
log_with_time = true
log_to_screen = false
log_to_file = true
log_level = INFO
file_log_level = INFO
# add the following lines
[client]
enable_net = true

6. 常見問題

boyue Device Plugin
2020/05/21 06:58:33 Fail to get device list. Retry in 2 seconds …
- 該問題通常是由 License Key 設定錯誤導致。
2020/05/21 06:58:03 Waiting for network interface eth0
- boyue要求所有節點上用於boyue通信的網卡使用相同名稱（例如eth0）。用戶務必確保這一前置條件滿足，否則boyue Server在沒有正確配寘網卡名稱的節點上無法正確啟動。
Cannot reach boyue contoller…
- 錯誤的 License Key 會導致controller异常退出. 請與controller容器內部檢查相應的日誌，日誌檔路徑為 /root/controller.log.
boyue Server
2020-05-21 07:02:33 [INFO] Waiting for net eth0 becoming ready …
- boyue要求所有節點上用於boyue通信的網卡使用相同名稱（例如eth0）。用戶務必確保這一前置條件滿足，否則boyue Server在沒有正確配寘網卡名稱的節點上無法正確啟動。
Device "ens5" does not exist. Network interface ens5 dose not have a valid IPv4 address.
- 這裡ens5为Network Interface的配寘。這條log說明Kubernetes集羣中有一個節點沒有ens5網卡，導致bind net失敗。囙此我們要求客戶環境內節點使用統一的網卡命名，以便boyue使用。
boyue Controller
/root/controller.log內只有一條日誌：level=info msg="read license from license file"
- 通常由於錯誤的license導致。請檢查複製粘貼到rancher表單的license內容是否正確。
boyue Monitor
time="2020-05-21T06:58:03Z" level=info msg="Starting dcgm-exporter"
Error: Failed to initialize NVML
time="2020-05-21T06:58:03Z" level=fatal msg="Error starting nv-hostengine: DCGM initialization error"
- 在非GPU節點上該錯誤為正常現象，可以忽略。
（已知問題）Rancher上部署的boyue的GUI頁面無法正確顯示GPU利用率。

使用Helm部署boyue

本文介紹使用Helm命令列工具將boyue所有組件部署到Kubernetes環境。

boyue已經與企業級Kubernetes管理平臺Rancher深度綜合，你可以通過Rancher中國應用商店直接部署boyue。

獲取官方boyue Helm Chart

使用如下指令獲取官方boyue Helm Chart：

git clone https://github.com/cnrancher/pandaria-catalog.git -b dev/v2.3

安裝部署

在可以通過kubectl訪問Kubernetes的節點上安裝Helm工具。

# 1.1 測試kubectl可以正常工作
kubectl get nodes
# 示例輸出
#NAME               STATUS   ROLES               AGE   VERSION
#ip-172-31-28-1     Ready    worker              24d   v1.17.5
#ip-172-31-43-188   Ready    worker              24d   v1.17.5
#ip-172-31-43-87    Ready    controlplane,etcd   24d   v1.17.5

# 1.2 安裝helm
# Ubuntu上可以直接通過snap安裝
# 其它包管理器下安裝helm请参考
# https://helm.sh/docs/intro/install/
# 或者
# https://github.com/helm/helm/releases
sudo snap install helm --classic

# 測試helm可以正常與Kubernetes通信
helm list
# 示例输出
#NAME    NAMESPACE       REVISION        UPDATED STATUS  CHART   APP VERSION

修改安裝配置

所有配寘資訊都通過修改pandaria-catalog/charts/virtaitech-boyue-vgpu/v1.0.0/values.yaml實現（其它chart配寘管道請參攷Helm官方檔案）

大部分配寘均不需要修改，少數需要修改的配寘均通過注釋# Interesting Config: 標出。關鍵配寘的說明如下：

設定	說明	預設值	類型
resources.name	暴露給Kubernetes的boyue資源名稱，用戶端在申請boyue資源時，需要使用這裡設定的資源名稱。通常不需要修改。特別和Rancher綜合時，修改這個名稱將導致Rancher無法正確啟動boyue的用戶端（Rancher固定使用virtaitech.com/gpu作為boyue資源名）	virtaitech.com/gpu	string
controller.password	登入controller webui的密碼（用戶為admin）。 controller的登入地址在使用`helm install`部署時將通過`stdout`輸出，請注意查看。	空	string
controller.enableQuota	controller是否啟用quota。	false	bool
controller.token	controller的token。調用controller高級api時需要給出這裡設定的token才能調用成功。	空	string
server.cudaVersion	server鏡像內使用的cuda版本，可選值為"9.0","9.1","9.2","10.0","10.1"。	10.1	string
server.net	（關鍵設定）boyue bind net的網卡名稱。該設定會指定boyue使用的網卡，特別當計算節點擁有多張網卡時，需要小心設定（例如，RDMA網卡和TCP網卡並存，最好指定RDMA網卡）。由於在Kubernetes環境下難以為每個節點獨立配寘boyue server並指定bind address，需要為所有節點通過統一的網卡名稱來配寘boyue網路環境。這會引入一個前提：如果有節點配寘使用的網卡名稱必須相同，否則必須請IT、運維人員做相應修改。	eth0	string
server.vgpus	每個PGPU虛擬出幾個VGPU	4	int
server.ibName	Infiniband網卡名稱。非必填項。	空	string
license.key	新版license。直接作為字串粘貼到這裡即可。注意舊版的license無法使用。請聯系數字中國獲取有效的license。	空	string
scheduler.apiVersion	controller使用的api版本。 scheduler與controller通信時會使用。通常與controller的版本相同。	2.2	string
scheduler.dataVersion	同上。	2.2	string

相關說明

自定義鏡像

通常每個組件使用的image可以通過組件下的image.repository和image.version來設定。例如：
```
helper:
image:
  repository: virtaitech/boyue-helper
  version: "2.2"
```
則最終boyue helper使用的image為：virtaitech/boyue-helper:2.2

但是boyue server的情况比較特殊，請參攷下文說明。
boyue helper說明

boyue部署完成後請通過kubectl describe node <nodeName>查看每個node的label，確保boyue_BIND_ADDR=<ip_address>已經通過boyue helper正確設定。如果沒有的話，需要手動添加label:kubectl label nodes <nodeName> boyue_BIND_ADDR=<ip_address>。這裡<ip_address>需要和server.net處設定的網卡的ip地址相同。如果boyue server在對應節點上啟動失敗，則boyue helper也無法正確打label。
boyue server鏡像說明

boyue server具體使用的鏡像通過server.image.version和server.cudaVersion的組合指定。如果使用其它鏡像，請將image tag成表格中的格式，並設定這兩個值。請注意現在DockerHub上只有2.2+10.1的鏡像（virtaitech/boyue-server-2.2:cuda10.1），如果需要使用其它版本，請使用趨動工程師提供的鏡像包，並通過docker load導入鏡像到每一個節點的docker daemon並打好相應tag，例如virtaitech/boyue-server-2.2:cuda9.1。或者把鏡像push到私有registry上。如果私有registry有存取控制，需要設定values.yaml 中imagePullSecrets的值。

安裝部署

配寘好values.yaml檔案後，就可以通過helm安裝所有boyue組件

# helm可以一鍵部署boyue
helm install pandaria-catalog/charts/virtaitech-boyue-vgpu/v1.0.0/ --generate-name

# 如果想要看到helm生成的所有yaml檔案，可以使用debug參數
helm install pandaria-catalog/charts/virtaitech-boyue-vgpu/v1.0.0/ --generate-name --debug

部署完成後可以使用helm list查看部署狀態。示例輸出為：


NAME                    NAMESPACE       REVISION        UPDATED                                 STATUS   CHART                           APP VERSION
boyue-gpu-1591596688    default         1               2020-06-08 06:11:28.953306413 +0000 UTC deployed virtaitech-boyue-vgpu-1.0.0     2.2

部署完成後可以通過kubectl get all 查看部署的boyue組件狀態，示例輸出為：

NAME                                    READY   STATUS             RESTARTS   AGE
pod/boyue-controller-5bd9578d87-4dm5n   2/2     Running            0          5m49s
pod/boyue-monitor-qxftd                 2/2     Running            0          5m49s
pod/boyue-monitor-s2rjl                 2/2     Running            0          5m49s
pod/boyue-plugin-lwbfk                  1/1     Running            0          5m49s
pod/boyue-plugin-n2jvc                  1/1     Running            0          5m49s
pod/boyue-server-4c6tx                  1/1     Running            0          5m49s
pod/boyue-server-dtltp                  0/1     CrashLoopBackOff   5          5m49s
pod/boyue-helper-49xzz                  1/1     Running            0          12m
pod/boyue-helper-vk2z9                  1/1     Running            0          12m
pod/boyue-scheduler-5c7f495cf-92bpp     2/2     Running            0          12m

NAME                                TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)                         AGE
service/kubernetes                  ClusterIP   10.43.0.1       <none>        443/TCP                         26d
service/boyue-controller            ClusterIP   10.43.173.242   <none>        15500/TCP,15501/TCP,15502/TCP   5m49s
service/boyue-controller-nodeport   NodePort    10.43.44.103    <none>        15502:30009/TCP                 5m49s

NAME                           DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR   AGE
daemonset.apps/boyue-monitor   2         2         2       2            2           <none>          5m49s
daemonset.apps/boyue-plugin    2         2         2       2            2           <none>          5m49s
daemonset.apps/boyue-server    2         2         1       2            1           <none>          5m49s

NAME                               READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/boyue-controller   1/1     1            1           5m49s

NAME                                          DESIRED   CURRENT   READY   AGE
replicaset.apps/boyue-controller-5bd9578d87   1         1         1       5m49s

注意這裡有一個boyue-server沒有能正常啟動。通過kubectl logs pod/boyue-server-dtltp查看日誌，示例輸出為：
```
Device "ens5" does not exist.
Network interface ens5 dose not have a valid IPv4 address.
```
這裡ens5为server.net的配寘。這條log說明Kubernetes集羣中有一個節點沒有ens5網卡，導致bind net失敗。囙此我們要求客戶環境內節點使用統一的網卡命名，以便boyue使用。

使用

boyue用戶端的使用管道可以參考boyue-Rancher集成指南中測試一節。
如果想要清理所有boyue的組件，可以使用helm list輸出的NAME進行卸載：

helm uninstall boyue-gpu-1591596688

在Rancher k3s上快速開始使用boyue

k3s是經CNCF一致性認證的Kubernetes發行版本，專為物聯網及邊緣計算設計。 boyue可以非常方便的在k3s上部署使用。

環境準備

我們推薦客戶使用Docker+NVidia Docker runtime環境來部署使用boyue+k3s。用戶需要

在所有節點上安裝Docker。安裝方法可以參考Docker官方檔案。
在所有GPU節點上安裝好GPU驅動（無需安裝CUDA，boyue不依賴原生CUDA）。
在所有GPU節點上安裝NVidia Docker runtime，並設定為default runtime。可以參考下麵的示例

安裝nvidia-docker2：

# https://github.com/NVIDIA/k8s-device-plugin#preparing-your-gpu-nodes
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L # | sudo apt-key add -
curl -s -L # | sudo tee /etc/apt/sources.list.d/nvidia-docker.list
sudo apt-get update && sudo apt-get install -y nvidia-docker2
sudo systemctl enable docker

安裝完nvidia-docker2後，我們要確保設定default runtime設定到nvidia：

# /etc/docker/daemon.json
{
  "default-runtime": "nvidia",
  "runtimes": {
    "nvidia": {
      "path": "/usr/bin/nvidia-container-runtime",
      "runtimeArgs": []
    }
  }
}
sudo systemctl restart docker

如果使用公有雲，可以在申請GPU實例時使用配寘好GPU驅動+CUDA+Docker+NVidia Docker runtime的鏡像。

具體可以參考k3s中文社區檔案：如何在k3s環境中安裝GPU相關程式。

快速安裝Rancher k3s

準備好節點環境，即可方便快速的部署k3s。

# 在控制面（server）節點執行如下指令：
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--docker" sh -s -
# 國內用戶，可以使用以下方法加速安裝：
curl -sfL https://docs.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn INSTALL_K3S_EXEC="--docker" sh -s -

# 在worker（agent）節點執行如下命令，其中：
# K3S_ URL是可以訪問的控制台節點地址
# K3S_ TOKEN保存在控制面（server）節點的/var/lib/rancher/k3s/server/node-token路徑下。
curl -sfL https://get.k3s.io | INSTALL_K3S_EXEC="--docker" K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken sh -
# 國內用戶，可以使用以下方法加速安裝：
curl -sfL https://docs.rancher.cn/k3s/k3s-install.sh | INSTALL_K3S_MIRROR=cn INSTALL_K3S_EXEC="--docker" K3S_URL=https://myserver:6443 K3S_TOKEN=mynodetoken sh -

具體可以參考k3s官方檔案

如果需要使用kubectl存取控制k3s集羣，需要進行一些簡單的配寘：

方法一：設定KUBECONFIG環境變數：

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml
kubectl get pods --all-namespaces

方法二：指定--kubeconfig參數：

kubectl --kubeconfig /etc/rancher/k3s/k3s.yaml get pods --all-namespaces

方法三：將/etc/rancher/k3s/k3s.yaml拷貝到~/.kube/config。

具體可以參考k3s官方檔案。

k3s上使用boyue

有多種方式可以讓用戶在k3s上方便快速地部署使用boyue。下麵一一介紹。

Rancher+k3s+boyue

k3s作為Rancher旗下一個羽量級的Kubernetes發行版本，與Rancher具有極佳的相容性，可以方便地使用Rancher進行管理。

首先需要在Rancher上導入k3s集羣，下圖以Rancher企業版為例，Rancher社區版操作類似：
隨後既可以參考檔案boyue-Rancher集成指南方便地使用Rancher部署使用boyue了。

k3s在某些情况下會導致hostNetwork: true的pod無法訪問到ClusterIP服務。如果遇到該情况，請參攷helm+boyue一節。

helm+boyue

boyue支持使用helm工具在k3s上進行快速部署。請參攷檔案使用Helm部署boyue。

k3s在某些情况下會導致hostNetwork: true的pod無法訪問到ClusterIP服務。如果遇到該情况，請使用特殊的chart分支：

git clone https://github.com/wpfnihao/pandaria-catalog.git -b dev/k3s

並在values.yaml檔案中正確設定k3s相關內容。例子：

k3s:
enabled: true
# Interesting Config:
# Please make sure this value is set to any accessible k3s node ip
hostIP: "127.0.0.1"

k3s helm CRD+boyue

k3s默認支持通過helm CRD來部署helm chart。

用戶需要準備k3s helm CRD支持的yaml檔案，如下所示。可以看到，所有設定項均與使用Helm部署boyue相同。用戶通過下方示例創建yaml檔案（例如boyue.yaml）並對設定項進行相應修改後，可以將該檔案拷貝至k3s server節點/var/lib/rancher/k3s/server/manifests目錄下。 k3s helm CRD控制器會自動根據設定內容拉起所有boyue組件。

apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: virtaitech-boyue-vgpu
  namespace: kube-system
spec:
  chart: virtaitech-boyue-vgpu
  repo: #
  targetNamespace: virtaitech-boyue-vgpu
  valuesContent: |-
    image:
      pullPolicy: IfNotPresent
    imagePullSecrets:

    resources:
      # Interesting Config:
      # resource name exposed by boyue
      name: "virtaitech.com/gpu"

    monitor:
      collectorPath: /run/prometheus
      image:
        exporter:
          # nvidia/dcgm-exporter
          repository: virtaitech/dcgm-export
          version: "2.2"
        prometheus:
          # quay.io/prometheus/node-exporter
          repository: virtaitech/node-exporter
          version: "2.2"
      # this port is also used by controller to scrap info.
      # should not change this value
      port: 9100

    controller:
      version: "2.2"
      name: "boyue-controller"
      port: "15500"
      portName0: "controller"
      portName1: "port1"
      portName2: "webportal"
      nodeport: 30007
      service: boyue-controller
      image:
        prom: virtaitech/prometheus
        repository: virtaitech/boyue-controller
        version: "2.2"
      # Interesting Config:
      password: ""
      # Interesting Config:
      # or true
      enableQuota: false
      # Interesting Config:
      token: ""
      # changing this value not tested
      replicas: 1

    helper:
      image:
        repository: virtaitech/boyue-helper
        version: "2.2"

    server:
      port: "9960"
      # Interesting Config:
      # TODO: requires additional images
      cudaVersion: "10.1"
      image:
        version: "2.2"
      path:
        comm: /var/tmp/boyue/comm
      # Interesting Config:
      net: ens5
      # Interesting Config:
      vgpus: 4
      # Interesting Config:
      ibName: ""

    plugin:
      path: /var/lib/kubelet/device-plugins
      image:
        repository: virtaitech/boyue-plugin
        version: "2.2"

    scheduler:
      replicas: 1
      apiVersion: "2.2"
      dataVersion: "2.2"
      image:
        scheduler:
          # gcr.io/google_containers/hyperkube:v1.16.3
          repository: virtaitech/hyperkube
          version: "2.2"
        extender:
          repository: virtaitech/k8s-scheduler-extender
          version: "2.2"
      port: 8888
      verbose: 4

    license:
      # Interesting Config:
      key: ""

    volumes:
      shm: /dev/shm

幾點說明：

特別適合通過本管道將boyue作為k3s的常駐組件進行部署。
修改/var/lib/rancher/k3s/server/manifests/boyue.yaml檔案會更新CRD控制器，但執行邏輯與helm upgrade不同。
删除boyue.yaml檔案不會卸載已部署的boyue組件（与helm uninstall邏輯不同）。
k3s在某些情况下會導致hostNetwork: true的pod無法訪問到ClusterIP服務。如果遇到該情况，請參攷helm+boyue一節。

技術文檔

TECHNICAL DOCUMENTATION

概述

支持清單

處理器

作業系統

NVIDIA GPU

寒武紀 MLU

中科海光 DCU

NVIDIA CUDA

寒武紀 Neuware

中科海光 DTK

深度學習框架

網絡

容器環境

虛擬化環境

容器框架

已知問題

必要組件介紹

boyue Controller

boyue Server

boyue Client

典型部署架構

boyue GPU 資源池化方案

安裝部署

GPU Monitor

環境依賴

boyue Controller

環境依賴

啟動文件下載

啟動 boyue Controller 服務

boyue Controller的日誌檔

boyue Server

環境依賴

配寘 boyue Server

boyue Server任務控制

boyue Server的日誌檔

多版本 CUDA SDK 共存

查看 boyue 服務狀態

部署 boyue Client

環境依賴

軟體安裝

配寘 boyue Client

boyue Client日志

使用boyue vGPU

boyue vGPU資源

boyue vGPU的使用

常見問題

boyue-Rancher集成指南

1. 使用Rancher中國提供的pandaria-catalog應用商店

Rancher中國企業版使用pandaria-catalog應用商店

Rancher社区版使用pandaria-catalog應用商店

2. 環境要求

3. 部署boyue

Rancher中國企業版部署boyue

Rancher社區版部署boyue

檢查節點標籤

查看部署相關資訊

4. 配寘詳情

5. 測試

Rancher中國企業版部署使用boyue用戶端

Rancher社區版使用boyue

boyue用戶端啟動配置說明

進階說明

使用示例

TensorFlow CNN Benchmark

Jupyter Notebook

關於缺乏RDMA網路環境的說明

6. 常見問題

使用Helm部署boyue

獲取官方boyue Helm Chart

安裝部署

在Rancher k3s上快速開始使用boyue

環境準備

快速安裝Rancher k3s

k3s上使用boyue

Rancher+k3s+boyue

helm+boyue

k3s helm CRD+boyue