技术文档

Technical documentation
目录

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 。如图所示：

Rancher企业版catalog

可以看到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页面：

    catalogs

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

    add-catalog

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

    launch

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

    check-catalog

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，点击启动：

    choose-cluster

  2. 选择virtaitech-orion-vgpu：

    choose-app

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

    config-app

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

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

    status-a

    status-b

Rancher社区版部署OrionX

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

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

    catalogs-comm

  2. 选择virtaitech-orion-vgpu。

    launch-comm

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

    config-app-comm

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

    status-comm

检查节点标签

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的性能。

label

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

edit-node

edit-node2

查看部署相关信息

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

comm-notes

ent-notes

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，如图所示：

    client0

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

    client1

  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客户端启动配置说明。

    client2

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

    client3

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

    client4

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

    client5

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

    client6

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利用率。