安装指南
OpenPAI的架构在v1.0.0
时进行了更新和优化。在v1.0.0
之前,OpenPAI基于Yarn和Kubernetes,数据由HDFS管理。从v1.0.0
开始,OpenPAI转变为纯Kubernetes的架构。除此之外,v1.0.0
还包括许多新特性,如AAD 认证
、Hived调度器
、Kube Runtime
、Marketplace
等。如果您仍要安装旧的基于Yarn的OpenPAI,请使用v0.14.0
。
要安装 OpenPAI >= v1.0.0
, 请先检查安装要求。 接下来, 如果您之前没有安装过老版本的OpenPAI,请直接跟随本文档中的步骤进行安装。如果您之前安装过OpenPAI,请先清除已有安装, 再跟随本文档。
安装要求
OpenPAI的部署要求您至少有3台独立的机器:一台dev box机器、一台master机器和一台worker机器。
dev box机器在安装、维护和卸载期间,通过SSH控制master机器和worker机器。您应该指定唯一一台dev box机器。
master机器用于运行核心Kubernetes组件和核心OpenPAI服务。目前,OpenPAI还不支持 HA (high availability), 您只能指定唯一一台master机器。
我们建议您使用纯CPU机器作为dev box机器和master机器。详细的要求请参考下面的表格:
硬件要求 | 软件要求 | |
---|---|---|
dev box 机器 |
|
|
master 机器 |
|
|
worker机器会被用来执行任务,您可以在安装期间指定一台或多台worker机器。
我们支持不同种类的worker:CPU机器、GPU机器、以及拥有其他计算设备(如TPU、NPU)的机器。
同时,我们还有两种调度器:Kubernetes default scheduler和hivedscheduler。
hivedscheduler是OpenPAI的默认调度器,它支持虚拟集群划分,拓扑感知的资源保证、以及性能优化的 Gang Scheduling,这些都是 k8s default scheduler 不支持的。
目前,对 CPU/NVIDIA GPU worker 和其他种类 worker,调度器的支持有所不同:
- 对于CPU worker或NVIDIA GPU worker,可以使用k8s default scheduler或hivedscheduler。
- 对于其他种类的worker,例如TPU、NPU机器,我们目前只支持使用k8s default scheduler。同时,您在集群中只能使用同一种计算设备的机器。例如,您可以在集群中使用TPU worker,但所有worker必须都是TPU worker,不能把TPU worker和其他GPU worker在同一集群中混用。
不同种类worker机器的详细要求请参考以下表格:
worker 种类 | 硬件要求 | 软件要求 |
---|---|---|
CPU Worker |
|
|
NVIDIA GPU Worker | 同上。 |
需要满足和CPU worker 一样的要求,除此之外还有下面的额外要求:
|
Enflame DTU Worker | 同上。 |
需要满足和CPU worker 一样的要求,除此之外还有下面的额外要求:
|
其他计算设备 | 同上。 |
需要满足和CPU worker 一样的要求,除此之外还有下面的额外要求:
|
检查完要求后,请按照下面的3个步骤安装OpenPAI:
- 为Kubernetes和OpenPAI创建设置文件
- 安装Kubernetes
- 安装OpenPAI服务
创建设置文件
在dev box机器上,使用下面的命令来克隆OpenPAI的repo:
git clone https://github.com/microsoft/pai.git
cd pai
checkout到某一个tag,来选择需要安装的OpenPAI版本:
git checkout v1.8.0
接下来,请编辑<pai-code-dir>/contrib/kubespray/config
目录下的layout.yaml
和config.yaml
文件。
这两个文件分别指定了集群的机器组成和自定义设置。下面是示例:
关于中国用户的提示
如果您是中国用户,在编辑这两个文件前,请先阅读这个文档。
layout.yaml
格式示例
layout.yaml
格式示例# GPU cluster example
# This is a cluster with one master node and two worker nodes
machine-sku:
master-machine: # define a machine sku
# the resource requirements for all the machines of this sku
# We use the same memory format as Kubernetes, e.g. Gi, Mi
# Reference: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory
mem: 60Gi
cpu:
# the number of CPU vcores
vcore: 24
gpu-machine:
computing-device:
# For `type`, please follow the same format specified in device plugin.
# For example, `nvidia.com/gpu` is for NVIDIA GPU, `amd.com/gpu` is for AMD GPU,
# and `enflame.com/dtu` is for Enflame DTU.
# Reference: https://kubernetes.io/docs/concepts/extend-kubernetes/compute-storage-net/device-plugins/
type: nvidia.com/gpu
model: K80
count: 4
mem: 220Gi
cpu:
vcore: 24
machine-list:
- hostname: pai-master # name of the machine, **do not** use upper case alphabet letters for hostname
hostip: 10.0.0.1
machine-type: master-machine # only one master-machine supported
pai-master: "true"
- hostname: pai-worker1
hostip: 10.0.0.2
machine-type: gpu-machine
pai-worker: "true"
- hostname: pai-worker2
hostip: 10.0.0.3
machine-type: gpu-machine
pai-worker: "true"
config.yaml
格式示例
config.yaml
格式示例user: forexample
password: forexample
docker_image_tag: v1.8.0
# Optional
#######################################################################
# OpenPAI Customized Settings #
#######################################################################
# enable_hived_scheduler: true
#############################################
# Ansible-playbooks' inventory hosts' vars. #
#############################################
# ssh_key_file_path: /path/to/you/key/file
#####################################
# OpenPAI's service image registry. #
#####################################
# docker_registry_domain: docker.io
# docker_registry_namespace: openpai
# docker_registry_username: exampleuser
# docker_registry_password: examplepasswd
################################################################
# OpenPAI's daemon qos config. #
# By default, the QoS class for PAI daemon is BestEffort. #
# If you want to promote QoS class to Burstable or Guaranteed, #
# you should set the value to true. #
################################################################
# qos-switch: "false"
###########################################################################################
# Pre-check setting #
###########################################################################################
# docker_check: true
# resource_check: true
########################################################################################
# Advanced docker configuration. If you are not familiar with them, don't change them. #
########################################################################################
# docker_data_root: /mnt/docker
# docker_config_file_path: /etc/docker/daemon.json
# docker_iptables_enabled: false
## An obvious use case is allowing insecure-registry access to self hosted registries.
## Can be ipaddress and domain_name.
## example define 172.19.16.11 or mirror.registry.io
# openpai_docker_insecure_registries:
# - mirror.registry.io
# - 172.19.16.11
## Add other registry,example China registry mirror.
# openpai_docker_registry_mirrors:
# - https://registry.docker-cn.com
# - https://mirror.aliyuncs.com
#######################################################################
# kubespray setting #
#######################################################################
# If you couldn't access to gcr.io or docker.io, please configure it.
# gcr_image_repo: "gcr.io"
# kube_image_repo: "gcr.io/google-containers"
# quay_image_repo: "quay.io"
# docker_image_repo: "docker.io"
# etcd_image_repo: "quay.io/coreos/etcd"
# pod_infra_image_repo: "gcr.io/google_containers/pause-{{ image_arch }}"
# kubeadm_download_url: "https://storage.googleapis.com/kubernetes-release/release/{{ kubeadm_version }}/bin/linux/{{ image_arch }}/kubeadm"
# hyperkube_download_url: "https://storage.googleapis.com/kubernetes-release/release/{{ kube_version }}/bin/linux/{{ image_arch }}/hyperkube"
# openpai_kube_network_plugin: calico
# openpai_kubespray_extra_var:
# key: value
# key: value
#######################################################################
# host daemon port setting #
#######################################################################
# host_daemon_port_start: 40000
# host_daemon_port_end: 65535
user
和password
是master机器、worker机器共享的SSH用户名和密码。换句话说,您得确保所有master机器和worker机器有同样的SSH用户名和密码。 其他的配置为可选配置,只有当您清楚地知道它们的含义时,您可以去修改它,否则请不要修改。
Azure用户请注意: 如果您在Azure上部署OpenPAI,请去掉openpai_kube_network_plugin: calico
的注释,并把它修改为openpai_kube_network_plugin: weave
. 这是因为Azure暂时不支持calico。细节部分请参阅这个文档。
如果您使用了除了CPU worker和NVIDIA GPU worker之外的worker结点:对于CPU worker和NVIDIA GPU worker之外的worker种类,目前我们只支持Kubernetes default scheduler (而不是Hivedscheduler)。请去掉# enable_hived_scheduler: true
的注释,并且将它设置为enable_hived_scheduler: false
。
如果您在config中开启了qos-switch: 此时,OpenPAI会在每个worker机器上要求额外的内存。请参考下面的表格,确保您的worker机器上有足够的内存:
Service Name | Memory Request | CPU Request |
---|---|---|
node-exporter | 128Mi | 0 |
job-exporter | 512Mi | 0 |
log-manager | 256Mi | 0 |
安装Kubernetes
转到目录<pai-code-dir>/contrib/kubespray
:
cd <pai-code-dir>/contrib/kubespray
目录<pai-code-dir>/contrib/kubespray
中包含了Kubernetes和OpenPAI服务的代码。
请先运行下面的命令安装Kubernetes。 顾名思义,我们使用kubespray来安装Kubernetes。
/bin/bash quick-start-kubespray.sh
安装过程中默认不显示skip
和ok
类型的ansible log。如需查看更完全的ansible log,请使用verbose
模式:
/bin/bash quick-start-kubespray.sh -v
如果在安装过程中出现任何问题,请再次检查上述环境要求。我们也提供了一个脚本,帮助您进行检查:
/bin/bash requirement.sh -l config/layout.yaml -c config/config.yaml
同时,您也可以参考安装故障排查文档或直接在搜索引擎上查找解决方法。当您解决问题后,请重新运行/bin/bash quick-start-kubespray.sh
。
如果安装成功,quick-start-kubespray.sh
会打印出下面的信息:
You can run the following commands to setup kubectl on you local host:
ansible-playbook -i ${HOME}/pai-deploy/kubespray/inventory/pai/hosts.yml set-kubectl.yml --ask-become-pass
在默认情况下,我们既不会在dev box机器上配置默认的kubeconfig
,也不会安装kubectl
客户端,只会把Kubernetes的config文件放在~/pai-deploy/kube/config
。您可以在任何Kubernetes客户端上使用这个config,来连接到Kubernetes集群。
另外,您也可以在dev box机器上运行命令ansible-playbook -i ${HOME}/pai-deploy/kubespray/inventory/pai/hosts.yml set-kubectl.yml --ask-become-pass
,来安装默认的kubeconfig
环境和kubectl
。该命令会把Kubernetes的config拷贝到~/.kube/config
,并安装kubectl
。成功运行后,您就可以直接在dev box机器上使用kubectl
来控制集群了。
关于网络问题的提示
如果您遇到网络问题,如机器无法下载某些文件,或无法连接到某个docker registry,请将提示的错误日志和kubespray合并为关键字,并搜索解决方案。您也可以参考安装常见问题解答和故障排查和这个issue。
安装OpenPAI服务
Kubernetes安装成功后,请使用下面的代码来安装OpenPAI服务:
/bin/bash quick-start-service.sh
如果一切顺利,您将会看到下面的信息:
Kubernetes cluster config : ~/pai-deploy/kube/config
OpenPAI cluster config : ~/pai-deploy/cluster-cfg
OpenPAI cluster ID : pai
Default username : admin
Default password : admin-password
You can go to http://<your-master-ip>, then use the default username and password to log in.
正如这个提示所说的,您可以用 admin
和 admin-password
来登录Webportal,并提交一个任务来验证安装。另外,我们已在目录~/pai-deploy/cluster-cfg
下生成了OpenPAI的配置文件,如果您之后需要自定义集群的话,这些配置文件有可能会被用到。
如果您使用的worker是CPU worker、NVIDIA GPU worker、AMD GPU worker、Enflame DTU worker之外的worker种类: 请在集群中手动安装设备的device plugin,否则会无法使用Kubernetes default scheduler。 目前可以自动安装的device plugin被列在这个文件中。您可以提交PR来支持您的设备。
保留一个文件夹
我们强烈建议您保留文件夹~/pai-deploy
,以便将来进行升级、维护和卸载操作。此文件夹中最重要的内容包括:
- Kubernetes集群配置(默认在
~/pai deploy/kube/config
):Kubernetes配置文件。kubectl
使用它连接到k8s api服务器。 - OpenPAI服务配置(默认为
~/pai-deploy/cluster-cfg
):一个包含您所有机器信息、OpenPAI服务配置的文件夹。
如果可能,可以备份~/pai-deploy
以防意外删除。
除了文件夹之外,您还应该记住OpenPAI集群ID,它的默认值为pai
。有些集群管理操作需要确认此ID。