# cluster_tools

**Repository Path**: yh_silence/cluster_tools

## Basic Information

- **Project Name**: cluster_tools
- **Description**: AISBench 分布式运行组件
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2024-03-01
- **Last Updated**: 2024-04-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AISBench分布式运行组件cluster_tools使用说明

## 工具介绍

### 名词定义

| 名词     | 定义                                                         |
| -------- | ------------------------------------------------------------ |
| 集群     | 一系列在同一网段的服务器环境。                               |
| 管理节点 | 运行分布式运行组件cluster的Linux服务器环境，可以是物理机，也可以是虚拟环境，集群中唯一。 |
| 节点     | 可以被管理节点访问的其他Linux服务器环境，可以是物理机，也可以是虚拟环境。 |
| 加速卡   | 每个节点挂载的用于处理AI任务的计算芯片，GPU、NPU等。         |

### 工具概述

AISbench分布式运行组件cluster_tools（后简称cluster工具）可以帮助集群中的管理节点给集群其他节点部署AI任务脚本（multi_put）；并且可以帮助集群中的管理节点给集群其他节点或节点上的加速卡并行或串行下发命令，同步拉起集群各节点名称相同的训练脚本（multi_exec）；AI任务结束后可以帮助管理节点汇总集群其他节点产生的文件结果（multi_get）。

cluster工具是一个Python工具，相对于slurm、openmpi等能完成类似功能的业界主流工具，其主要特点是：

- **轻量化**：整个工具安装包占空间大小仅KB量级，安装时间一般小于10s。
  ![](images/install.gif)
- **部署方便**：cluster工具通过**pip install**命令可以直接安装。cluster工具只需要安装在管理节点上，不需要部署在集群所有节点；同时可以帮助建立集群间基于ssh key的免密访问；部署全流程只需在管理节点操作。

### 工具依赖

- OS：Linux

- Python版本：Python 3.7及以上版本

- 安装paramiko、scp依赖，下载并安装本工具的whl软件包时自动安装。

  若依赖未安装成功，可手动执行命令安装，进入cluster_tools目录，执行以下命令安装依赖：

  ```bash
  pip install -r requirements.txt
  ```

### 安全说明

- 管理节点与集群其他节点建立的SSH连接是通过`paramiko`的SSH客户端基于SSH2协议建立的。
- 将管理节点公钥部署到集群其他节点时会提示用户输入密码，密码通过`getpass.getpass`获取，获取后不会保存。
- 将管理节点公钥部署到集群其他节点是基于`paramiko`的sftp客户端进行传输。

## 安装和卸载

### 安装cluster_tools

1. 从[cluster_tools发行版](https://gitee.com/aisbench/cluster_tools/releases)获取whl包，通过`pip install`命令安装：

   ```bash
   pip install ais_bench_cluster-<version>-py3-none-linux_<arch>.whl --force-reinstall
   ```

2. 执行`pip show ais_bench_cluster`确认安装完成，输出结果如下：

   ```bash
   Name: ais-bench-cluster
   Version: 2.0
   Summary: ais_bench cluster tool
   Home-page: ais_bench url
   Author:
   Author-email:
   License:
   Location: /xxxx/site-packages
   Requires: paramiko, scp
   Required-by:
   ```

### 卸载cluster_tools

卸载cluster工具可以使用如下命令：

```bash
pip uninstall ais_bench_cluster
```

## 集群节点信息文件内容格式

集群节点信息文件json文件，需要用户自行创建（如nodeinfo_file.json）并按照如下格式配置节点信息（注意删除注释）：

```json
{
"ssh_key_path": "", // 必填，需要用户传入的ssh key私钥的路径（传入的私钥建议配置有效期限），确保已经在集群其他计算节点的authorized_keys上部署好对应的公钥。
"cluster": [
    {
        "ip": "xx.xx.xx.xx",  // 必填，节点的ip地址
        "user": "xxxxx", // 必填，节点的用户名
        "port": xxx, // 选填, 节点的端口，默认22
        "work_path": "xxx"  // 选填, 进入节点后所处的路径，默认'./'
    },
    {
        ...
    }
]
}
```

ssh key私钥的生成与公钥的部署参考附录的“**集群ssh key生成与部署流程**”章节。

## cluster_tools命令行使用方法

### 命令示例

cluster工具的使用命令示例如下：

```bash
python -m ais_bench.cluster <module> --option1 xxx --option2 xxx ...
```

其中`module`作为**二级命令**表示cluster工具的各项**子功能**，--option*表示**子功能参数**。


### 具体子功能介绍

#### multi_exec（集群批量执行命令）

- 功能介绍

  管理节点控制集群中所有节点以串行/并行执行给定命令。

- 命令格式

  ```bash
  python -m ais_bench.cluster multi_exec --option1 xxx --option2 xxx ...
  ```

   其中`--option*`表示子功能参数。

- 参数说明

  | 参数             | 说明                                                         | 是否必选 |
  | ---------------- | ------------------------------------------------------------ | -------- |
  | --node-file或-nf | 包含ssh key和集群节点信息的json文件的路径，json文件格式参考“**集群节点信息文件内容格式**”章节。 | 是       |
  | --cmd或-c        | 需要各节点执行的命令。（请谨慎使用`rm -rf`等危险命令）       | 是       |
  | --mode或-m       | 以串行或并行操纵节点执行命令，取值对应"serial"或"parallel"，默认取"parallel"。 | 否       |
  | --device-num或-d | 每个节点的加速卡数量。默认值0。当取值为0时，命令直接在每个节点上进行，命令被执行前配置了环境变量`RANK_NUM`（集群节点数）、`NODE_ID`（节点编号）；当取值>0时，节点上将会开启对应取值数量的并发子进程，在这些子进程中执行命令，命令被执行前每个子进程中配置了环境变量`RANK_SIZE`（集群总加速卡数）、`RANK_ID`（当前子进程对应的加速卡在集群中的编号）、`DEVICE_NUM`（当前节点的开启的子进程数）、`DEVICE_ID`（当前子进程对应的加速卡在当前节点的编号）。 </br>**注意：命令必须使用单引号限制，如 --cmd 'echo $RANK_ID' 这些默认环境变量才会生效。** | 否       |

- 命令示例

  ```bash
  python -m ais_bench.cluster -nf nodeinfo.json -c 'echo $RANK_ID;bash run.sh' -d 8
  ```

  ![](images/multi_exec.gif)

#### single_exec（单节点执行命令）

- 功能介绍

  管理节点控制集群中某一节点执行给定命令。

- 命令格式

  ```bash
  python -m ais_bench.cluster single_exec --option1 xxx --option2 xxx ...
  ```

  其中`--option*`表示子功能参数。

- 参数说明

  | 参数             | 说明                                                         | 是否必选 |
  | ---------------- | ------------------------------------------------------------ | -------- |
  | --node-file或-nf | 包含ssh key和集群节点信息的json文件的路径，json文件格式参考“集群节点信息文件内容格式”章节。 | 是       |
  | --cmd或-c        | 需要某一节点执行的命令。（请谨慎使用`rm -rf`等危险命令）     | 是       |
  | --node-id或-n    | 集群中某一节点的编号（节点编号依据node-file中节点的配置顺序从0开始自动分配），默认取值0。 | 否       |
  | --device-num或-d | 某一节点的加速卡数量。默认值0。当取值为0时，命令直接在每个节点上进行，命令被执行前配置了环境变量`RANK_NUM`（集群节点数）、`NODE_ID`（节点编号）；当取值>0时，节点上将会开启对应取值数量的并发子进程，在这些子进程中执行命令，命令被执行前每个子进程中配置了环境变量`RANK_SIZE`（集群总加速卡数）、`RANK_ID`（当前子进程对应的加速卡在集群中的编号）、`DEVICE_NUM`（当前节点的开启的子进程数）、`DEVICE_ID`（当前子进程对应的加速卡在当前节点的编号）。</br>**注意：命令必须使用单引号限制，如 --cmd 'echo $RANK_ID' 这些默认环境变量才会生效。** | 否       |

#### multi_put（集群批量分发资源）

- 功能介绍

  将管理节点的某个文件或文件夹以串行/并行方式传输给集群的所有节点。

- 命令格式

  ```bash
  python -m ais_bench.cluster multi_put --option1 xxx --option2 xxx ...
  ```

  其中`--option*`表示子功能参数。

- 参数说明

  | 参数             | 说明                                                         | 是否必选 |
  | ---------------- | ------------------------------------------------------------ | -------- |
  | --node-file或-nf | 包含ssh key和集群节点信息的json文件的路径，json文件格式参考“**集群节点信息文件内容格式**”章节。 | 是       |
  | --src或-s        | 管理节点上的文件或文件夹路径。                               | 是       |
  | --dst或-d        | 集群其他节点上的传输目标路径，相对路径（相对于每个节点的工作路径） | 是       |
  | --mode或-m       | 以串行或并行操纵节点执行命令，取值对应"serial"或"parallel"，默认取"parallel"。 | 否       |

- 命令示例

  ```bash
  python -m ais_bench.cluster multi_put -nf nodeinfo.json -s run.sh -d ./
  ```

  ![](images/multi_put.gif)

#### single_put（单节点分发资源）

- 功能介绍

  将管理节点的某个文件或文件夹以串行/并行方式传输给集群的某一节点。

- 命令格式

  ```bash
  python -m ais_bench.cluster single_put --option1 xxx --option2 xxx ...
  ```

  其中`--option*`表示子功能参数。

- 参数说明

  | 参数             | 说明                                                         | 是否必选 |
  | ---------------- | ------------------------------------------------------------ | -------- |
  | --node-file或-nf | 包含ssh key和集群节点信息的json文件的路径，json文件格式参考“**集群节点信息文件内容格式**”章节。 | 是       |
  | --src或-s        | 管理节点上的文件或文件夹路径。                               | 是       |
  | --dst或-d        | 集群中某一节点上的传输目标路径，相对路径（相对于目标节点的工作路径）。 | 是       |
  | --node-id或-n    | 集群中某一节点的编号（节点编号依据node-file中节点的配置顺序从0开始自动分配），默认取值0。 | 否       |

#### multi_get（集群归集资源）

- 功能介绍

  将集群的所有节点的某个文件或文件夹以串行/并行方式传输给管理节点。

- 命令格式

  ```bash
  python -m ais_bench.cluster multi_get --option1 xxx --option2 xxx ...
  ```

  其中`--option*`表示子功能参数。

- 参数说明

  | 参数             | 说明                                                         | 是否必选 |
  | ---------------- | ------------------------------------------------------------ | -------- |
  | --node-file或-nf | 包含ssh key和集群节点信息的json文件的路径，json文件格式参考“**集群节点信息文件内容格式**”章节。 | 是       |
  | --src或-s        | 集群其他节点上的文件或文件夹路径，相对路径（相对于每个节点的工作路径）。 | 是       |
  | --dst或-d        | 管理节点上的传输目标路径。                                   | 是       |
  | --mode或-m       | 以串行或并行操纵节点执行命令，取值对应"serial"或"parallel"，默认取"parallel"。 | 否       |

- 命令示例

  ```bash
  python3 -m ais_bench.cluster -nf nodeinfo.json -s result/ -d ./
  ```

  ![](images/multi_get.gif)


#### single_get（单节点归集资源）

- 功能介绍

  将集群中某一节点的某个文件或文件夹以串行/并行方式传输给管理节点。

- 命令格式

  ```bash
  python -m ais_bench.cluster single_get --option1 xxx --option2 xxx ...
  ```

  其中`--option*`表示子功能参数。

- 参数说明

  | 参数             | 说明                                                         | 是否必选 |
  | ---------------- | ------------------------------------------------------------ | -------- |
  | --node-file或-nf | 包含ssh key和集群节点信息的json文件的路径，json文件格式参考“**集群节点信息文件内容格式**”章节。 | 是       |
  | --src或-s        | 集群中某一节点上的文件或文件夹路径，相对路径（相对于节点的工作路径） | 是       |
  | --dst或-d        | 管理节点上的传输目标路径。                                   | 是       |
  | --node-id或-n    | 集群中某一节点的编号（节点编号依据node-file中节点的配置顺序从0开始自动分配），默认取值0。 | 否       |

#### init（工具初始化）
**不推荐使用，使用此初始化方法的节点在ssh_key有效期内能长期进行免密访问，安全风险高，后续此功能会移除！**

- 功能介绍

  初始化cluster工具，使用此命令后，cluster的其他子功能使用时不需要指定`--node-file`, 使用默认保存的node_file文件，同时可以协助自动生成新的ssh_key并部署。

- 命令格式

  ```bash
  python -m ais_bench.cluster init --node-file xxx --auto-set-key
  ```

- 参数说明

  | 参数               | 说明                                                         | 是否必选 |
  | ------------------ | ------------------------------------------------------------ | -------- |
  | --node-file或-nf   | 包含ssh key和集群节点信息的json文件的路径，json文件格式参考“**集群节点信息文件内容格式**”章节。 | 是       |
  | --auto-set-key或-a | 使用此附属命令时cluster会自动部署集群节点的免密访问（会有交互界面依次输入节点的密码）。默认设置key的期限为16周。使用此功能时将不会用到node_file中的"ssh_key_path"配置项 ，"ssh_key_path"的值可以设为空字符串| 否       |


## cluster_tools python API使用方法

### 调用示例

确保ais_bench cluster工具已安装，调用API方法如下：

```python
from ais_bench.cluster.cluster_module import <some module>
```

其中`some module`表示对应的接口函数。

### API使用介绍

接口函数与命令行的二级命令完全对应，使用限制也通用。接口函数与命令行的二级命令的映射如下：

#### cluster_multi_exec（集群批量执行命令）

- 函数原型

  ```bash
  cluster_multi_exec(node_file: str, cmd: str, mode: str = "parallel", device_num: int = 0)
  ```

- 对应命令行二级命令

  `multi_exec`

- 函数入参对应附属可选命令（参数含义详见附属命令的说明）

  - node_file：--node-file
  - cmd：--cmd
  - mode：--mode
  - device_num：--device-num

#### cluster_single_exec（单节点执行命令）

- 函数原型

  ```bash
  cluster_single_exec(node_file: str, cmd: str, node_id: int = 0, device_num: int = 0)
  ```

- 对应命令行二级命令

  `single_exec`

- 函数入参对应附属可选命令（参数含义详见附属命令的说明）

  - node_file：--node-file
  - cmd：--cmd
  - node_id：--node-id
  - device_num：--device-num

#### cluster_multi_put（集群批量分发资源）

- 函数原型

  ```bash
  cluster_multi_put(node_file: str, src_path: str, dst_path: str, mode: str = "parallel")
  ```

- 对应命令行二级命令

  `multi_put`

- 函数入参对应附属可选命令（参数含义详见附属命令的说明）

  - node_file：--node-file
  - src_path：--src
  - dst_path：--dst
  - mode：--mode

#### cluster_single_put（单节点分发资源）

- 函数原型

  ```bash
  cluster_single_put(node_file: str, src_path: str, dst_path: str, node_id: int = 0)
  ```

- 对应命令行二级命令

  `single_put`

- 函数入参对应附属可选命令（参数含义详见附属命令的说明）

  - node_file：--node-file
  - src_path：--src
  - dst_path：--dst
  - node_id：--node-id

#### cluster_multi_get（集群归集资源）

- 函数原型

  ```bash
  cluster_multi_get(node_file: str, src_path: str, dst_path: str, mode: str = "parallel")
  ```

- 对应命令行二级命令

  `multi_get`

- 函数入参对应附属可选命令（参数含义详见附属命令的说明）

  - node_file：--node-file
  - src_path：--src
  - dst_path：--dst
  - mode：--mode

#### cluster_single_get（单节点归集资源）

- 函数原型

  ```bash
  cluster_single_get(node_file: str, src_path: str, dst_path: str, node_id: int = 0)
  ```

- 对应命令行二级命令

  `single_get`

- 函数入参对应附属可选命令（参数含义详见附属命令的说明）

  - node_file：--node-file
  - src_path：--src
  - dst_path：--dst
  - node_id：--node-id

#### cluster_init（工具初始化）

- 函数原型

  ```bash
  cluster_init(node_file: str, ssh_key: str = "", auto_set_key: bool = False)
  ```

- 对应命令行二级命令

  `init`

- 函数入参对应附属可选命令（参数含义详见附属命令的说明）

  - node_file：--node-file
  - auto_set_key：--auto-set-key
    **注意**：如果使用了`cluster_init`接口，后续使用cluster的其他接口时，`node_file`参数可以取为空，使用入参提供的node_file路径的优先级比init保存的node_file路径的优先级更高。

## 附录

### 集群ssh key生成与部署流程

管理节点免密访问集群计算节点的设置参考操作如下：

1. 登录集群管理节点并生成ssh key。

   ```bash
   ssh-keygen -t rsa -b 2048
   ```

   安全起见，建议用户在“Enter passphrase”步骤时输入密钥密码，且符合密码复杂度要求。建议执行该命令前先将umask设置为0077，测试完成后再恢复原来umask值。

2. 将管理节点的公钥拷贝到所有计算节点的机器上。

   ```bash
   ssh-copy-id -i ~/.ssh/id_rsa.pub <user>@<ip>
   ```

   `<user>@<ip>`替换成要拷贝到的对应计算节点的用户名和IP，例如username1@10.175.1.1。

3. 设置SSH代理管理SSH密钥。

   ```bash
   ssh-agent bash   # 开启ssh-agent的bash进程
   ssh-add   # 向ssh-agent添加私钥
   ```

   避免工具批量安装操作过程中输入密钥密码和节点密码。