OrionX-Rancher集成指南

Rancher同趋动科技达成战略合作，加速GPU资源池化在Kubernetes中落地

面对Kubernetes使用GPU资源的众多难题，Rancher与趋动科技共同推出了面向Kubernetes的GPU资源池化联合解决方案。Rancher可以同时管理多个Kubernetes集群，用户可以通过其内置的应用市场Catalog开箱即用地将OrionX部署至各个业务集群，OrionX具备专业的GPU池化和虚拟化功能，可以无侵入地整合至Rancher托管的Kubernetes集群当中。最终，用户可以极为方便地在Rancher平台上进行GPU资源调度，从而让工作负载使用OrionX提供的vGPU资源。

1. 使用Rancher中国提供的pandaria-catalog应用商店

OrionX现已集成至Rancher中国的应用市场当中，开源用户可以通过导入pandaria-catalog（https://github.com/cnrancher/pandaria-catalog）获取这一应用，企业用户无需导入即可轻松使用。

Rancher中国企业版使用pandaria-catalog应用商店

Rancher中国企业版已默认集成pandaria-catalog应用商店。请使用v2.3.8-ent以上版本，该版本已经实现了工作负载对OrionX vGPU的支持，运行方式：

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

在全局— 工具— 商店设置中，查看应用商店，企业版已经内置了pandaria-catalog，并在其中 内置了OrionX Chart 。如图所示：

可以看到pandaria-catalog已经处于Active激活状态。

进入应用商店，可以看到virtaitech-orion-vgpu应用。如图所示：

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

Rancher社区版（https://rancher.com/quick-start/）也可以方便的一键部署：

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

但是Rancher社区版并没有默认配置pandaria-catalog应用商店，需要用户手动配置。

1. 进入Global-Apps-Manage Catalogs页面：

   

2. 添加catalog。如图所示，首先点击Add Catalog按钮。填入Catalog URL=https://github.com/cnrancher/pandaria-catalog和Branch=dev/v2.3。名称可以随意设置，范围Scope则最好设置为全局global。

   

3. 此时catalog配置完成，可以去应用商店进行确认。

   

   可以看到virtaitech-orion-vgpu已经出现在应用商店内。

   

2. 环境要求

在部署OrionX之前，客户环境需要满足一定条件：

• 部署OrionX的Kubernetes版本需要>=1.6。OrionX会部署一个专用调度器orion-scheduler，需要Kubernetes v1.6及以上版本支持。具体请参考这里和这里。
• 客户环境需要确保相应硬件的驱动已正确安装，特别是NVidia GPU驱动。如果使用RDMA网卡，还需要确保RDMA驱动已正确安装。
• 容器运行时 containerd 版本号>= 1.3.2。
  • 在GPU节点上安装好了NVidia docker runtime，并且已经设置为默认容器运行时。可以通过kubectl describe node [nodename]来检测节点的容器运行时。
• （关键）OrionX要求所有节点上用于OrionX通信的网卡使用相同名称（例如eth0）。用户务必确保这一前置条件满足，否则Orion Server在没有正确配置网卡名称的节点上无法正确启动。请参考下文常见问题一节。
• （推荐）如果使用Mellanox RDMA网络，需要安装RDMA驱动，以及Mellanox的OFED。

3. 部署OrionX

Rancher中国企业版部署OrionX

1. 选择需要部署的Kubernetes集群和对应Project，点击启动：

   

2. 选择virtaitech-orion-vgpu：

   

3. 在部署表单内对OrionX进行配置。具体配置内容请参考下文配置详情一节。

   

4. Rancher会自动拉取OrionX的所有组件镜像，用户可以在Rancher内查看所有组件的运行状态。

   • 注：新版OrionX只会部署在一个命名空间（namespace）内。

   

   

Rancher社区版部署OrionX

在执行下述步骤之前，请务必参照Rancher社区版使用pandaria-catalog应用商店一节正确配置应用商店。

1. 选择要部署Orion的集群，以及对应的project。选择Apps，点击Launch。

   

2. 选择virtaitech-orion-vgpu。

   

3. 在部署表单内对OrionX进行配置。具体配置内容请参考下文配置详情一节。

   

4. 查看所有OrionX组件的状态。

   

检查节点标签

orion-helper会依据用户配置的Network Interface（例如eth0）自动获取ip地址，并给Kubernetes节点打上标签。可以在集群-Nodes页面查看到节点的标签。所有需要运行orion-server的节点都需要有正确的ORION_BIND_ADDR标签。如下图所示，只有一个节点ip-172-31-43-188正确标识了ORION_BIND_ADDR的值。ORION_BIND_ADDR没有获取到正确的值通常是因为Network Interface（例如eth0）与该节点的网卡名称不匹配导致的。ORION_BIND_ADDR的值未正确设置会在某些情况下影响OrionX的性能。

用户可以通过Rancher上手动修改节点标签，如下图所示：

查看部署相关信息

OrionX部署时使用的相关设置可以在部署后的应用界面查看。相关信息会显示在 Notes（或注释）和Answers（或应答）两栏下，如下图所示：

4. 配置详情

设置	说明	默认值	类型
Name（名称）	Rancher App名称	virtaitech-orion-vgpu	string
Template Version（模板版本）	Chart版本	1.0.0	下拉菜单
Namespace（命名空间）	Kubernetes命名空间，可以新建或者选择现有命名空间	空	string
Use Default Image	使用默认镜像，通常不需要修改。如有必要，请在趋动科技工程师指导下修改这里的设置。	True	bool
License Key	新版license。直接作为字符串粘贴到这里即可。注意旧版的license无法使用。请联系趋动科技获取有效的license。获取license请参考：https://www.virtaitech.com/development/index#-12	空	string
Controller Web Portal Password	登录controller webui的密码（用户为admin）。controller的登录地址在应用部署完成界面的Notes一节可以查看。	空	string
Controller Token	controller的token。调用controller高级api时需要给出这里设置的token。controller的高级api文档请详询趋动科技客户支持团队。	空	string
Orion Resource Name	暴露给Kubernetes的orion资源名称，客户端在申请orion资源时，需要使用这里设置的资源名称。通常不需要修改。特别和Rancher中国企业版整合时，修改这个名称将导致Rancher中国企业版无法正确启动Orion的客户端。	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	（关键设置）Orion bind net的网卡名称。该设置会指定OrionX使用的网卡，特别当计算节点拥有多张网卡时，需要小心设置（例如，RDMA网卡和TCP网卡并存，最好指定RDMA网卡）。由于在Kubernetes环境下难以为每个节点独立配置orion server并指定bind address，需要为所有节点通过统一的网卡名称来配置Orion网络环境。这会引入一个前提：如果有节点配置使用的网卡名称必须相同，否则必须请IT、运维人员做相应修改。	eth0	string
VGPU Numbers	每个物理GPU虚拟出几个VGPU。	4	int
Infiniband Network Name	Infiniband网卡名称。非必填项。	空	string

5. 测试

Rancher中国企业版部署使用OrionX客户端

1. 默认情况下，UI中不会启用Orion的支持参数，需要在启用一个特殊Feature。在“全局—系统设置 —功能选项”中，启用virtaitech-gpu-service-ui，如图所示：

   

2. 选择对应的集群和Project，选择资源-工作负载，部署一个工作负载。配置客户端镜像，使用virtaitech/orion-client-2.2:cuda10.1-tf1.14-py3.6-hvd。

   

3. 设置Orion资源环境变量，具体为（请根据实际需求配置）：

   env:
   - name: ORION_VGPU
     value: "1"
   - name: ORION_GMEM
     value: "4096"
   - name: ORION_RATIO
     value: "100"
   # whether the orion 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: ORION_RESERVED
     value: "0"
   - name: ORION_CROSS_NODE
     value: "0"
   - name : ORION_GROUP_ID
     valueFrom:
       fieldRef:
         fieldPath: metadata.uid
   

   各参数含义请参见下文Orion客户端启动配置说明。

   

4. 配置使用orion-scheduler调度器。

   

5. 使用主机IPC命名空间，并申请OrionX GPU资源。

   

6. 待客户端部署完成，可以在Rancher图形界面上进入客户端内执行命令。

   

   例如可以执行：/root/cuda_samples/deviceQuery/deviceQuery。客户端镜像内``/root/cuda_samples`路径下有大量的测试用例供客户使用。

   

Rancher社区版使用OrionX

Rancher社区版缺少对OrionX客户端的一些整合支持。用户可以通过Kubernetes命令行工具部署OrionX的客户端。一个典型的测试yaml文件如下（各参数含义请参见下文Orion客户端启动配置说明）：

# orion-client.yaml
apiVersion: v1
kind: Pod
metadata:
  name: testgpu
spec:
  schedulerName: orion-scheduler
  hostIPC: true
  containers:
  - name: test
    image: virtaitech/orion-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: ORION_VGPU
      value: "1"
    - name: ORION_GMEM
      value: "4096"
    - name: ORION_RATIO
      value: "100"
    # whether the orion 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: ORION_RESERVED
      value: "0"
    - name: ORION_CROSS_NODE
      value: "0"
    - name : ORION_GROUP_ID
      valueFrom:
        fieldRef:
          fieldPath: metadata.uid
    resources:
      limits:
        # if you have changed Resource Name while deploying Orion services, please change this accordingly
        virtaitech.com/gpu: 1

可以通过kubectl apply -f orion-client.yaml来部署客户端。客户端镜像内``/root/cuda_samples`路径下有大量的测试用例供客户使用。

Orion客户端启动配置说明

设置	说明	类型
spec.schedulerName	使用的Kubernetes调度器的名称，请务必指定为orion-scheduler	string
spec.hostIPC	请务必设置为true	bool
spec.containers[].env[].name="ORION_VGPU"	申请的Orion VGPU个数，注意这里为字符串。该值请务必设置为与spec.containers[].resources.limits.virtaitech.com/gpu相同。字符串内容必须为正整数。	string
spec.containers[].env[].name="ORION_GMEM"	每个VGPU申请的显存，单位为兆（MB）。字符串内容必须为正整数。	string
spec.containers[].env[].name="ORION_RATIO"	每个VGPU占用物理GPU算力的百分比。	string
spec.containers[].env[].name="ORION_GROUP_ID"	必须按照示例设置。	string
spec.containers[].env[].name="ORION_RESERVED"	OrionX的资源分配模式。当设置为1时，OrionX的资源分配与Kubernetes的pod的生命周期绑定。只要pod存在，则资源就会被保留，即使pod内没有在使用资源。这种模式下资源无法超发。当值设置为除1以外的其它值时，OrionX的资源只会（默认）预留30s。如果pod内没有在使用OrionX资源，则闲置30s后资源会被释放。这种该模式下资源可以超发。默认为1。	string
spec.containers[].env[].name="ORION_CROSS_NODE"	使用跨节点GPU，默认为0。	string
spec.containers[].resources.limits.virtaitech.com/gpu	必须为正整数（Kubernetes限制）。请将该值设置与spec.containers[].env[].name="ORION_VGPU"相同。	int

进阶说明

• 当ORION_RESERVED=1时，ORION_VGPU实际不生效（但需要设置），实际申请的VGPU资源数量基于spec.containers[].resources.limits.virtaitech.com/gpu。
• 当ORION_RESERVED!=1时，pod调度时申请的资源基于spec.containers[].resources.limits.virtaitech.com/gpu。但如果资源闲置30s被释放后再次使用VGPU资源，则会依据ORION_VGPU(以及其它环境变量)的值申请资源。
• 当一个pod里面有多个container时，OrionX只会满足第一个设置了spec.containers[].resources.limits.virtaitech.com/gpu的container资源申请要求。建议用户使用时只在一个pod里面让一个container申请OrionX资源。

使用示例

TensorFlow CNN Benchmark

在Orion客户端内执行：

# 注意ORION_RESERVED=1时，客户端内修改环境变量不生效
export ORION_VGPU=2
export ORION_GMEM=15000
export ORION_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 ORION_VGPU=4
export ORION_GMEM=15000
export ORION_RATIO=100
export ORION_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 Orion 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.html
    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/orion/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. 常见问题

• Orion 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

    • OrionX要求所有节点上用于OrionX通信的网卡使用相同名称（例如eth0）。用户务必确保这一前置条件满足，否则Orion Server在没有正确配置网卡名称的节点上无法正确启动。

  • Cannot reach orion contoller...

    • 错误的 License Key 会导致controller异常退出. 请与controller容器内部检查相应的日志，日志文件路径为 /root/controller.log.

• Orion Server

  • 2020-05-21 07:02:33 [INFO] Waiting for net eth0 becoming ready ...

    • OrionX要求所有节点上用于OrionX通信的网卡使用相同名称（例如eth0）。用户务必确保这一前置条件满足，否则Orion Server在没有正确配置网卡名称的节点上无法正确启动。

  • Device "ens5" does not exist. Network interface ens5 dose not have a valid IPv4 address.

    • 这里ens5为Network Interface的配置。这条log说明Kubernetes集群中有一个节点没有ens5网卡，导致bind net失败。因此我们要求客户环境内节点使用统一的网卡命名，以便Orion使用。

• Orion Controller

  • /root/controller.log内只有一条日志：level=info msg="read license from license file"
    • 通常由于错误的license导致。请检查复制粘贴到rancher表单的license内容是否正确。

• Orion 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上部署的OrionX的GUI页面无法正确显示GPU利用率。

在Rancher k3s上快速开始使用OrionX

k3s是经CNCF一致性认证的Kubernetes发行版，专为物联网及边缘计算设计。OrionX可以非常方便的在k3s上部署使用。

环境准备

我们推荐客户使用Docker+NVidia Docker runtime环境来部署使用OrionX+k3s。用户需要

• 在所有节点上安装Docker。安装方法可以参考Docker官方文档。

• 在所有GPU节点上安装好GPU驱动（无需安装CUDA，OrionX不依赖原生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 https://nvidia.github.io/nvidia-docker/gpgkey | sudo apt-key add -
    curl -s -L https://nvidia.github.io/nvidia-docker/$distribution/nvidia-docker.list | 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上使用OrionX

有多种方式可以让用户在k3s上方便快速地部署使用OrionX。下面一一介绍。

Rancher+k3s+OrionX

k3s作为Rancher旗下一个轻量级的Kubernetes发行版本，与Rancher具有极佳的兼容性，可以方便地使用Rancher进行管理。

• 首先需要在Rancher上导入k3s集群，下图以Rancher企业版为例，Rancher社区版操作类似：

  

• 随后既可以参考文档**OrionX-Rancher集成指南**方便地使用Rancher部署使用OrionX了。

k3s在某些情况下会导致hostNetwork: true的pod无法访问到ClusterIP服务。如果遇到该情况，请参考helm+OrionX一节。

helm+OrionX

OrionX支持使用helm工具在k3s上进行快速部署。请参考文档**使用Helm部署OrionX**。

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+OrionX

k3s默认支持通过helm CRD来部署helm chart（参考：https://rancher.com/docs/k3s/latest/en/helm/）。

用户需要准备k3s helm CRD支持的yaml文件，如下所示。可以看到，所有设置项均与**使用Helm部署OrionX**相同。用户通过下方示例创建yaml文件（例如orion.yaml）并对设置项进行相应修改后，可以将该文件拷贝至k3s server节点/var/lib/rancher/k3s/server/manifests目录下。k3s helm CRD控制器会自动根据设置内容拉起所有Orion组件。

apiVersion: helm.cattle.io/v1
kind: HelmChart
metadata:
  name: virtaitech-orion-vgpu
  namespace: kube-system
spec:
  chart: virtaitech-orion-vgpu
  repo: https://wpfnihao.github.io/pandaria-catalog
  targetNamespace: virtaitech-orion-vgpu
  valuesContent: |-
    image:
      pullPolicy: IfNotPresent
    imagePullSecrets:

    resources:
      # Interesting Config:
      # resource name exposed by Orion
      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: "orion-controller"
      port: "15500"
      portName0: "controller"
      portName1: "port1"
      portName2: "webportal"
      nodeport: 30007
      service: orion-controller
      image:
        prom: virtaitech/prometheus
        repository: virtaitech/orion-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/orion-helper
        version: "2.2"

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

    plugin:
      path: /var/lib/kubelet/device-plugins
      image:
        repository: virtaitech/orion-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

几点说明：

• 特别适合通过本方式将Orion作为k3s的常驻组件进行部署。
• 修改/var/lib/rancher/k3s/server/manifests/orion.yaml文件会更新CRD控制器，但执行逻辑与helm upgrade不同。
• 删除orion.yaml文件不会卸载已部署的Orion组件（与helm uninstall逻辑不同）。
• k3s在某些情况下会导致hostNetwork: true的pod无法访问到ClusterIP服务。如果遇到该情况，请参考helm+OrionX一节。

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

概述

Orion vGPU软件是一个为云或者数据中心内的AI应用，CUDA应用提供GPU资源池化，提供GPU虚拟化能力的系统软件。通过高效的通讯机制，使得AI应用，CUDA应用可以运行在云或者数据中心内任何一个物理机，Container或者VM内而无需挂载物理GPU。同时为这些应用程序提供在GPU资源池中的硬件算力。通过这种Orion GPU池化的能力，可以提供多个优点：

• 兼容已有的AI应用和CUDA应用，使其仍然具有使用GPU加速的性能
• 为AI应用和CUDA应用在云和数据中心的部署提供了很大的灵活度。无需受GPU服务器位置、资源数量的约束。
• Orion 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，对部分程序可能不支持。

必要组件介绍

Orion Controller

该组件为一个长运行的服务程序，其负责整个GPU资源池的资源管理。其响应Orion Client的vGPU请求，并从GPU资源池中为Orion Client端的CUDA应用程序分配并返回Orion vGPU资源。
该组件可以部署在数据中心任何网络可到达的系统当中。每个资源池部署一个该组件。资源池的大小取决于IT管理的需求，可以是整个数据中心的所有GPU作为一个资源池，也可以每个GPU服务器作为一个独立的资源池。

Orion Server

该组件为一个长运行的系统服务，其负责GPU资源化的后端服务程序。Orion Server部署在每一个CPU以及GPU节点上，接管本机内的所有物理GPU。通过和Orion Controller的交互把本机的GPU加入到由Orion Controller管理维护的GPU资源池当中。
当Orion Client端应用程序运行时，通过Orion Controller的资源调度，建立和Orion Server的连接。Orion Server为其应用程序的所有CUDA调用提供一个隔离的运行环境以及真实GPU硬件算力。

Orion Client

该组件为一个运行环境，其模拟了NVidia CUDA的运行库环境，为CUDA程序提供了API接口兼容的全新实现。通过和Orion其他功能组件的配合，为CUDA应用程序虚拟化了一定数量的虚拟GPU（Orion vGPU）。
使用CUDA动态链接库的CUDA应用程序可以通过操作系统环境设置，使得一个CUDA应用程序在运行时由操作系统负责链接到Orion Client提供的动态链接库上。由于Orion Client模拟了NVidia CUDA运行环境，因此CUDA应用程序可以透明无修改地直接运行在Orion vGPU之上。

典型部署架构

以下介绍两种常见的Orion GPU资源池化部署方案。一种是All-in-One的本地GPU虚拟化方案，一种是部署到分布式多台物理机的GPU资源池化方案。

Orion GPU资源池化方案

分布式GPU资源池化方案指的是把一台或者多台服务器内的GPU作为资源池，通过Orion向局域网内任一个物理机、Container或者VM内的CUDA应用程序提供虚拟化GPU的部署方式。
选择局域网内至少一个Linux服务器部署Orion Controller。该Controller必须可以被属于同一个资源池的其他Orion组件通过网络访问。
每一个服务器上部署Orion Server服务，Orion Server自动适配该服务器是否安装有GPU，从而开启不同的功能。 在每一个需要运行CUDA应用程序的物理机、Container和VM里部署Orion Client运行库。 各个Orion组件通过Orion Controller的控制功能完成服务发现，资源调度等功能。
从逻辑上，以上各个Orion组件使用了control plane和data plane两套网络。其中control plane用于和Orion Controller组件的通讯。该部分通讯流量不大，对网络延迟和带宽需求不高。data plane用于Orion Client和Orion Server之间执行CUDA任务之间的通讯。该部分对于网络的延迟和带宽有一定需求。建议使用支持RDMA的网络。在实际环境中，control plane和data plane可以是同一个物理网络。

安装部署

以下安装部署的步骤，说明，均以Orion软件包存放路径在 /root/orion 为例进行说明

GPU Monitor

该组件为可选组件，用于监控物理GPU的利用率。如果生产环境中已有其他替代的功能，该组件可以不用部署。

环境依赖

• Docker容器环境
• 与Docker版本匹配的Nvidia Docker runtime
• Nvidia GPU驱动

执行如下命令导入容器镜像，并运行服务

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

Orion Controller

Orion Controller包括物理GPU管理，vGPU资源分配，GUI监控，管理功能。在典型使用场景下，在一个分布式环境，仅需要部署一个实例。以下通过容器化部署Orion Controller。

环境依赖

• Docker容器环境

激活文件下载

用户在部署Orion Controller之前，需确保已经下载激活文件。

如何下载激活文件：

进入趋动科技官网, 注册并登录

进入产品页面点击“申请试用”按钮成为试用用户，或者点击“申请购买”按钮付费购买产品，并等待管理员审核。

经管理员审核后，成功申请试用，或者已经付费购买的用户，可以进入您的个人中心页面，点击“下载激活文件”按钮获取您的激活文件。对于联网环境和非联网环境的用户，需要下载激活文件的方式有所不同，详情请参考“下载激活文件”页面描述。

进入/root/orion/controller目录

cd /root/orion/controller

用您下载到的激活文件license.txt替换/root/orion/controller目录里的已有的license.txt即可。

启动Orion Controller服务

执行如下命令导入容器镜像，并运行服务

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

编辑配置文件 /root/orion/controller/prometheus.yml 修改static_configs中的targets 列表，该列表是安装了GPU Monitor服务的GPU服务器的列表。当GPU Monitor有多个IP网段地址的时候，该地址应该与 第3章节部署Orion Server时绑定的数据网段相同，例如文档中的“ORION_BIND_ADDR=CCCC”地址，或者是Orion Server的配置文件中的bind_addr相同。
执行如下命令运行Orion Controller服务：

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

服务成功启动后，根据屏幕输出提示，在本宿主机的所有网段提供如下服务：

• 调度服务：部署Orion Server时需要配置该地址
• Web GUI服务：通过浏览器访问该服务进行监控和管理

Orion Controller的日志文件

Orion Controller的日志文件存放在Orion Controller 容器内的 /root/controller.log 中

Orion Server

Orion Server为GPU资源池化提供底层的虚拟GPU服务。在所有的CPU节点、GPU节点均需部署该服务。
Orion Server支持的虚拟化/容器平台有：

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

CUDA业务运行KVM虚拟的场景，在把Orion Server部署至宿主机时，由于宿主机可能存在SELinux，apparmor的限制，安装Orion 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服务器宿主机执行如下命令安装Orion Server

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

配置Orion Server

通过配置文件 /etc/orion/server.conf 可以对Orion 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    ; Orion 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      ; Orion Server的服务端口
    enable_kvm = true       ; 是否支持Orion Client运行在KVM的VM中
    enable_shm = true       ; 是否使用共享内存加速通讯
    enable_rdma = true      ; 是否使用RDMA加速通讯
    ibverbs_device = mlx5_0 ; 如果使用RDMA，硬件设备名。仅在Orion 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

Orion Server任务控制

通过如下命令可以启动Orion Server

sudo systemctl start oriond

通过如下命令可以执行其他Orion Server操作

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

Orion Server的日志文件

Orion Server的日志存在两个位置

• /var/log/orion/server.log 该文件记录了所有Orion Client的握手过程
• /var/log/orion/session 该目录以单个文件的形式，记录了每次业务运行时的日志。每运行一个Orion Client应用，该目录产生一个独立的日志文件。如果在握手过程中失败，则不产生日志文件。

多版本 CUDA SDK 共存

Orion Server 可以同时支持多个CUDA版本，使得依赖不同CUDA版本的上层应用可以同时使用Orion vGPU。为了支持多个CUDA SDK版本，Orion 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，这是因为 Orion Server 可以根据 Orion Client 环境中实际安装的 Runtime 对应于 CUDA 的版本号，动态选择合适的 CUDA SDK 版本。

查看Orion 服务状态

在同一个局域网内，通过浏览器（推荐chrome）访问Orion Controller所在环境的局域网地址： http://IP:Port
其中IP为Orion Controller所在环境的局域网地址，Port为部署Orion Controller时提示的Web GUI的服务端口。通过默认用户名（密码 ）登录进入系统 : admin(admin)
在侧边栏里看到Orion Controller的IP地址，点击展开之后有如下的内容：

• 摘要：显示Orion Controller所管理的整个Orion vGPU资源池的资源数量，节点状态等
• 任务：显示正在运行且使用了Orion vGPU资源的任务，以及每个任务使用的vGPU资源的分布情况
• Orion GPU节点列表：通过点击展开可以看到一组GPU节点的状态，并且在每个节点的工作面板上看到物理GPU的划分使用情况

部署 Orion Client

环境依赖

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

软件安装

在CUDA应用环境执行如下的安装命令

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

上述命令的x，y为根据所需 CUDA 版本选择对应的 installer，例如install-client-10.0 对应于 CUDA 10.0
上述命令把 Orion Client 环境安装至默认路径 /usr/lib/orion 中，并通过 ldconfig 机制将 /usr/lib/orion 添加到系统动态库搜索路径。
注意：如果Orion Client按照到和GPU同样的宿主机环境，由于Orion Client安装的 /usr/lib/orion 和物理GPU的 CUDA SDK可能存在版本冲突。对于同样的动态库在两个不同磁盘位置的加载顺序，应该由安装人员自己维护解决。

配置Orion Client

Orion Client可以通过三类方法配置运行参数

• 通过环境变量配置运行参数
• 通过当前用户home目录中 {$HOME}/.orion/client.conf 配置文件配置运行参数
• 通过 /etc/orion/client.conf 配置文件配置运行参数

上述方法中，通过环境变量配置的优先级最高，系统 /etc/orion 目录中配置文件的优先级最低

Orion Client的配置中分为静态配置部分和动态配置部分。

• 静态配置部分指的是在目标环境中每次运行CUDA应用程序都保持不变的部分。
• 动态配置部分指的是根据CUDA应用程序使用的Orion 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    ; Orion Controller的调度器IP地址和端口

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

其中环境变量 ORION_CONTROLLER 设置 Orion Controller 的地址具有比配置文件更高的优先级
例如在当前SHELL通过 export ORION_CONTROLLER 环境变量可以忽略配置文件中的controller_addr配置

动态配置包括：

• 环境变量 ORION_VGPU 设置当前环境下 CUDA 应用程序申请使用多少个 Orion vGPU
  • 例如通过 export ORION_VGPU=2 指定了当前 CUDA 应用程序申请使用 2 个Orion vGPU
  • 该配置无默认值
• 环境变量 ORION_GMEM 设置当前环境下，CUDA 应用程序申请使用的每个 Orion vGPU 中的显存大小。以MiB为单位。
  • 例如通过 export ORION_GMEM=4096 为当前 CUDA 应用程序指定了每个 Orion vGPU的显存大小为 4096 MiB。
  • 该配置的默认值取决于默认一个物理GPU被切分为几个vGPU
• 环境变量 ORION_RATIO 设置当前环境下，CUDA 应用程序申请使用的每个 Orion vGPU 占用一个物理GPU算力的百分比。以%为单位
  • 例如通过 export ORION_RATIO=50 为当前 CUDA 应用程序指定了每个 Orion vGPU的50%的算力。
  • 该配置的默认值取决于默认一个物理GPU被切分为几个vGPU
• 环境变量 ORION_CROSS_NODE 为可选参数，参数为1且申请多个vGPU时，允许Orion Controller跨越多个物理GPU节点调度资源，使得分配的多个vGPU可能来自于不同的物理GPU节点。
  • 该参数为1时，ORION_RATIO必须为100
  • 该配置默认为0

Orion Client日志

Orion Client日志位于执行应用程序的用户home目录中的 ${HOME}/.orion/log 目录中。每次CUDA应用运行均会在该目录产生一个对应于该次任务的日志文件。

使用Orion vGPU

本章节介绍在Orion Client环境中，如何为CUDA应用程序配置使用Orion vGPU

Orion vGPU资源

通过安装部署Orion vGPU软件，所有Orion Server所在的GPU服务器内的GPU均加入了一个全局共享的资源池。每个物理GPU均被划分为多个逻辑vGPU。划分vGPU的默认粒度为启动 Orion Server 时，配置文件 /etc/orion/server.conf 中的 vgpu_count 参数指定。若设置 vgpu_count=n，则每个vGPU默认的显存大小为物理GPU显存的 n 分之一。

Orion vGPU的使用

由于Orion vGPU的调用接口兼容物理GPU的调用接口，因此CUDA应用程序可以无感知无修改地像使用物理GPU那样使用Orion vGPU。仅需要在运行CUDA应用程序时，通过配置文件、环境变量为本CUDA应用程序配置运行环境即可。

经过Orion GPU资源池化之后，资源池中的vGPU使用模式为CUDA应用程序即时申请即时使用的模式。也即是当CUDA应用程序调用CUDA接口初始化时才向Orion GPU资源池申请一定数量的vGPU，当CUDA应用程序退出时其申请到的vGPU自动释放至资源池中。多次调用CUDA应用程序分配到的vGPU不一定对应于同样的物理GPU资源。

当Orion Client的静态环境配置完毕后，在运行一个CUDA应用之前，至少需要用 ORION_VGPU 环境变量指明该CUDA应用程序希望获得的vGPU数目。例如一个deviceQuery CUDA程序，如下的命令使得当该CUDA程序做设备发现时，通过CUDA的接口查询到2个GPU，每个GPU的显存是4096MiB。

export ORION_VGPU=2
export ORION_GMEM=4096
./deviceQuery

当上述deviceQuery CUDA程序启动时，会从Orion GPU资源池中独占两个vGPU。该程序结束时，会自动释放两个vGPU。可以通过重新设定环境变量，在运行CUDA应用程序之前改变对vGPU资源的使用。一次CUDA应用程序所申请的多个vGPU可能存在于多个物理GPU上。

vGPU的使用对象为CUDA应用程序，而非物理机、Container或者VM虚拟机。即使在同一个环境下运行的多个CUDA应用程序，每一个应用程序都按照当前的运行环境向Orion GPU资源池申请独立的vGPU资源。如果并行运行多个CUDA应用程序，则消耗的vGPU数量为应用程序数目乘以 ORION_VGPU 所指定的vGPU数目。

常见问题

用户首先需要确认Orion Server和Orion Client版本的匹配。不同版本之间的Orion Server和Orion Client无法共同使用。

• Orion Client端应用程序启动报告无法找到NVidia GPU

  • 此故障为应用程序没有使用Orion Client运行库导致，可能的原因有几种：
    • 该应用程序在编译期间静态链接了NVidia的库，导致其运行时并不调用Orion Client的运行库。该问题应该通过设置动态链接并重新编译解决。
    • 该应用程序虽然使用CUDA相关的动态链接库，但是编译器使用rpath选项指明了CUDA库加载的绝对路径，而该路径并非是Orion Client的安装路径。rpath优先级高导致库加载的路径非期望的Orion Client安装路径。该问题或者通过去掉rpath设置后重新编译解决，或者用Orion Client运行库覆盖rpath指明的路径内的库解决。
    • Orion Client库的安装路径没有使用ldconfig或者环境变量LD_LIBRARY_PATH放到动态库加载路径。该问题通过使用ldconfig永久把Orion Client的安装路径加入到系统搜索路径，或者正确使用环境变量LD_LIBRARY_PATH来设置。

• Orion Server服务无法启动，oriond进程启动失败

  • 通过运行 orion-check runtime server 来检查环境。可能的原因有
  • oriond进程依赖CUDA，CUDNN库无法搜索到导致可执行文件无法被操作系统启动。
    • 修改上述Orion Server服务配置文件
  • oriond进程依赖的其他库没有安装，例如libcurl，libopenssl等