diff --git a/docs/en/_toc.yaml b/docs/en/_toc.yaml index 47f509caad32e8ee2088dcc91c7d7c5ca524adab..e3949493117cd0148e40e278cd818cb92d0943f1 100644 --- a/docs/en/_toc.yaml +++ b/docs/en/_toc.yaml @@ -1,14 +1,12 @@ label: oeDeploy User Guide isManual: true -description: 'oeDeploy is a lightweight deployment tool designed for simplicity.' +description: oeDeploy is a lightweight deployment tool designed for simplicity. sections: - label: oeDeploy Introduction href: ./introduction.md - - label: oedp Command Guide + - label: Using the oedp Command-Line Tool href: ./command.md - - label: oeDeploy Features - href: ./feature.md - label: oeDeploy Use Cases - href: ./usecase.md - - label: oeDeploy Plugin Development Guide - href: ./develop_guide.md + href: ./use_case.md + - label: oeDeploy Plugin Development + href: ./develop_instruction.md diff --git a/docs/en/develop_guide.md b/docs/en/develop_instruction.md similarity index 99% rename from docs/en/develop_guide.md rename to docs/en/develop_instruction.md index c721a243fdd3126003256dc6e617df057d8665aa..68faef0c718e43e0384919f804d621422a965d31 100644 --- a/docs/en/develop_guide.md +++ b/docs/en/develop_instruction.md @@ -1,4 +1,4 @@ -# oeDeploy Plugin Development Guide +# oeDeploy Plugin Development ## 1. Introduction to oeDeploy Plugins diff --git a/docs/en/feature.md b/docs/en/feature.md deleted file mode 100644 index 7076f7566818d2ef0cc0b4734f62dcde82327bf4..0000000000000000000000000000000000000000 --- a/docs/en/feature.md +++ /dev/null @@ -1,19 +0,0 @@ -# Features in Development - -- Debug mode for executing specified tasks -- Plugin initialization functionality for deployment -- Plugin validation module for deployment -- Plugin source management module with automatic download/extraction by plugin name (configurable sources) -- oeDeploy web interface supporting custom deployment task creation, node information management, and visualized deployment workflows - -# Planned Features - -- Plugin marketplace with plugin lists and web-based task creation -- Helm deployment project compatibility - -# Released Features - -## v1.0.1 - -- Ansible integration as the distributed node command orchestration platform -- Playbook-level workflow orchestration support diff --git a/docs/en/introduction.md b/docs/en/introduction.md index eada8bbed11e59c2013351f2513e7a2497c22e79..540e087d7cb8873c2faa62677535ef4b6a00fd3e 100644 --- a/docs/en/introduction.md +++ b/docs/en/introduction.md @@ -16,6 +16,5 @@ oeDeploy is a lightweight software deployment tool designed to help developers q # Docs - [oedp Command Guide](./command.md) -- [oeDeploy Features](./feature.md) -- [oeDeploy Use Cases](./usecase.md) -- [oeDeploy Plugin Development Guide](./develop_guide.md) +- [oeDeploy Use Cases](./use_case.md) +- [oeDeploy Plugin Development Guide](./develop_instruction.md) diff --git a/docs/en/usecase.md b/docs/en/use_case.md similarity index 100% rename from docs/en/usecase.md rename to docs/en/use_case.md diff --git a/docs/zh/Command.md b/docs/zh/Command.md deleted file mode 100644 index 47c919023f31099f14ef4879d15ffa9ecc7998b5..0000000000000000000000000000000000000000 --- a/docs/zh/Command.md +++ /dev/null @@ -1,57 +0,0 @@ -# oedp 命令行参数说明 - -## `oedp` - -| 选项 | 选项简写 | 功能说明 | -| ------------- | -------- | ---------- | -| `--version` | `-v` | 查询版本号 | - -## `oedp info` - -查看项目的详细信息，默认为当前路径 - -| 选项 | 简写 | 是否必需 | 功能说明 | -| -------------------- | ------ | -------- | ---------------------- | -| `--project [path]` | `-p` | N | 指定一个路径为项目路径 | - -## `oedp run [action]` - -执行项目的方法，默认为当前路径；`[action]`为插件可使用的方法，可通过 `oedp info`命令查询 - -| 选项 | 简写 | 是否必需 | 功能说明 | -| --------------------- | ------ | -------- | ---------------------- | -| `--project [path]` | `-p` | N | 指定一个路径为项目路径 | -| `--debug`（开发中） | `-d` | N | 以debug模式运行 | - -## `oedp list` - -列举源中可用的插件 - -| 选项 | 简写 | 是否必需 | 功能说明 | -| ------------------ | ------ | -------- | -------------------- | -| `--local [path]` | `-l` | N | 指定一个路径为本地源 | - -## `oedp check [action]`（开发中） - -检查项目中指定方法的检查项，默认为当前路径 - -| 选项 | 简写 | 是否必需 | 功能说明 | -| -------------------- | ------ | -------- | ---------------------- | -| `--project [path]` | `-p` | N | 指定一个路径为项目路径 | - -## `oedp init [plugin]`（开发中） - -插件初始化， `[plugin]`为插件名，可通过 `oedp list`命令查询 - -| 选项 | 简写 | 是否必需 | 功能说明 | -| -------------------- | ------ | -------- | ---------------------------------------------------------------- | -| `--project [path]` | `-p` | Y | 指定初始化路径 | -| `--local [path]` | `-l` | N | 指定一个路径为本地源 | -| `--force` | `-f` | N | 强制覆盖路径；如果路径存在，会先删除该路径中的所有文件，再初始化 | - -# oedp 工具相关路径 - -+ `/var/oedp/log/`：日志文件路径 -+ `/var/oedp/plugin/`：插件缓存路径 -+ `/usr/lib/oedp/src/`：源码路径 -+ `/etc/oedp/config/`：配置文件路径 diff --git a/docs/zh/UseCase.md b/docs/zh/UseCase.md deleted file mode 100644 index 9fd8827302ad6c723af7b45448e730c0530cae1b..0000000000000000000000000000000000000000 --- a/docs/zh/UseCase.md +++ /dev/null @@ -1,84 +0,0 @@ -# oeDeploy 应用案例 - -## 应用案例 1：kubernetes 一键部署 - -准备 3 个 2U4G 的虚拟机环境（三层网络互通），使用的 OS 版本为 openEuler 24.03-LTS-SP1，目标是部署由 1 个 master、2 个 worker 构成的 k8s 集群。 - -在任意节点上，下载并安装 oeDeploy 的命令行工具 oedp。 - -````bash -wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/x86_64/Packages/oedp-1.0.1-1.oe2503.x86_64.rpm -yum install -y oedp-1.0.1-1.oe2503.x86_64.rpm -```` - -执行以下命令，获取并解压插件包，确保当前目录下出现了目录`kubernetes-1.31.1`。 - -```shell -wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/plugins/kubernetes-1.31.1.tar.gz -tar -zxvf kubernetes-1.31.1.tar.gz -``` - -执行`info`命令以查看插件详细信息： - -```shell -oedp info -p kubernetes-1.31.1 -``` - -修改项目配置文件，根据实际情况配置节点信息： - -```shell -vim kubernetes-1.31.1/config.yaml -``` - -````yaml -all: - children: - masters: - hosts: - 172.27.76.114: # master node IP - ansible_host: 172.27.76.114 # master node IP - ansible_port: 22 - ansible_user: root - ansible_password: - architecture: amd64 # amd64 or arm64 - oeversion: 24.03-LTS # 22.03-LTS or 24.03-LTS - workers: - hosts: - 172.27.70.60: # worker node IP - ansible_host: 172.27.70.60 # worker node IP - ansible_port: 22 - ansible_user: root - ansible_password: - architecture: amd64 - oeversion: 24.03-LTS - 172.27.72.90: - ansible_host: 172.27.72.90 - ansible_port: 22 - ansible_user: root - ansible_password: - architecture: amd64 - oeversion: 24.03-LTS - vars: - init_cluster_force: "true" - service_cidr: 10.96.0.0/16 - pod_cidr: 10.244.0.0/16 - certs_expired: 3650 - has_deployed_containerd: "false" - ansible_ssh_common_args: "-o StrictHostKeyChecking=no" -```` - -> 注意：须确保节点间 ssh 可联通，支持密码登录和密钥登录，如果使用密钥登录，则不需要配置密码。 - -执行以下命令以开始自动化部署： - -```shell -oedp run install -p kubernetes-1.31.1 -``` - -执行以下命令以卸载kubernetes： - -```shell -oedp run delete -p kubernetes-1.31.1 -``` - -> -p 参数表示解压后的文件目录。如果进入 kubernetes-1.31.1 插件根目录，执行 oedp 命令时无需 -p 参数。 diff --git a/docs/zh/_toc.yaml b/docs/zh/_toc.yaml index 266fc547e73ddcebb24f8659c4918324554320b5..a6b8c81d46b42301b6c42f743a73df993d7ad3c5 100644 --- a/docs/zh/_toc.yaml +++ b/docs/zh/_toc.yaml @@ -1,14 +1,15 @@ label: oeDeploy 用户指南 isManual: true -description: 'oeDeploy 是一款轻量、易用的软件部署工具' +description: oeDeploy 是一款轻量、易用的软件部署工具 sections: - label: oeDeploy简介 href: ./introduction.md - - label: 命令行工具oedp使用指南 + - label: 使用命令行工具oedp href: ./command.md - - label: oeDeploy工具特性 - href: ./feature.md - label: oeDeploy应用案例 - href: ./usecase.md - - label: oeDeploy插件开发指南 - href: ./develop_guide.md + href: ./use_case.md + - label: oeDeploy插件开发 + href: ./develop_instruction.md + - label: oeDeploy MCP Server使用说明 + href: ./mcp_instruction.md + \ No newline at end of file diff --git a/docs/zh/command.md b/docs/zh/command.md new file mode 100644 index 0000000000000000000000000000000000000000..f423569c8bf285e498ef31898ad783284577f084 --- /dev/null +++ b/docs/zh/command.md @@ -0,0 +1,189 @@ +# # `oedp`命令行设计 & 使用说明 + +## `oedp` + +| 选项 | 选项简写 | 功能说明 | +| ------------- | -------- | ---------- | +| `--version` | `-v` | 查询版本号 | + +## `oedp info` + +查看项目的详细信息，默认为当前路径。 + +| 选项 | 简写 | 是否必需 | 功能说明 | +| -------------------- | ------ | -------- | ------------------------ | +| `--project [path]` | `-p` | N | 项目路径，默认为当前路径 | + +## `oedp run [action]` + +执行项目某个方法，默认为当前路径；`[action]`为插件可使用的方法，可通过 `oedp info`命令查询。 + +| 选项 | 简写 | 是否必需 | 功能说明 | +| -------------------- | ------ | -------- | ------------------------ | +| `--project [path]` | `-p` | N | 项目路径，默认为当前路径 | +| `--debug` | `-d` | N | 以debug模式运行 | + +## `oedp list` + +列举源中可用的插件。 + +## `oedp init [plugin]` + +插件初始化到指定路径，`[plugin]`可以是插件压缩包路径、插件下载地址、插件名称。 + +- `[plugin]`如果为本地的插件压缩包（以`tar.gz`结尾），则直接初始化到指定路径。 +- `[plugin]`如果为插件下载地址（以`tar.gz`结尾），则先下载到缓存路径`/var/oedp/plugin/`，再初始化到指定路径。 +- `[plugin]`如果为插件名称，从已经配置的插件源中查找，下载到缓存路径后初始化到指定路径。 + +| 选项 | 简写 | 是否必需 | 功能说明 | +| ------------------ | ---- | -------- | ------------------------------------------------------------ | +| `--project [path]` | `-p` | N | 项目路径，若不存在则创建 | +| `--dir [path]` | `-d` | N | 项目的父路径，若不存在则创建。如果未指定项目路径与父路径，则父路径默认取当前目录 | +| `--force` | `-f` | N | 强制覆盖路径，请谨慎使用；如果路径存在，会先删除该路径中的所有文件，再初始化 | + +示例：假设当前路径为家目录`~`，如下5个命令的效果，都是初始化了一个目录为`~/kubernetes-1.31.1`的 oeDeploy 插件。 + +````bash +oedp init kubernetes-1.31.1 +oedp init kubernetes-1.31.1.tar.gz +oedp init https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/plugins/kubernetes-1.31.1.tar.gz +oedp init kubernetes-1.31.1 -p ~/kubernetes-1.31.1 +oedp init kubernetes-1.31.1 -d ~ +```` + +## `oedp repo` + +插件源管理。支持本地插件源、远端插件源。 + +| 选项 | 功能说明 | +| -------------------- | ---------------------- | +| `list` | 查询所有已配置的插件源 | +| `update` | 更新插件索引缓存 | +| `set [name] [url]` | 修改插件源地址 | +| `del [name]` | 删除插件源 | +| `enable [name]` | 使能插件源 | +| `disable [name]` | 去使能插件源 | + +插件源配置文件 `/etc/oedp/config/repo/repo.conf`示例。 + +````ini +[openEuler] +url = https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/plugins/ +enabled = true + +[local] +url = file:///root/.oedp/plugins/ +enabled = false +```` + +## `oedp check [action]`（开发中） + +检查项目中指定方法的检查项，默认为当前路径。 + +| 选项 | 简写 | 是否必需 | 功能说明 | +| -------------------- | ------ | -------- | ------------------------ | +| `--project [path]` | `-p` | N | 项目路径，默认为当前路径 | + +## `oedp clean`（开发中） + +清理所有临时插件文件。 + +# # `oedp`工具相关文件与路径 + +| 路径 | 说明 | +| --------------------------------- | ---------------------- | +| `/etc/oedp/config/` | 配置文件路径 | +| `/etc/oedp/config/repo/cache/` | 插件源索引文件缓存路径 | +| `/etc/oedp/config/repo/repo.conf` | 插件源配置文件 | +| `/usr/lib/oedp/src/` | 源码路径 | +| `/var/oedp/log/` | 日志文件路径 | +| `/var/oedp/plugin/` | 插件缓存路径 | + +# # 插件源 + +## 格式说明 + +oeDeploy 支持从可访问的插件源自动获取安装部署插件，并初始化到本地。 + +插件源的根目录下必须有一个索引文件 `index.yaml`，其描述了当前插件源中所有可访问插件的具体信息，包括下载地址。 + +oeDeploy 提供了脚本 `tools/make_repo_index/make_repo_index.py`，用于自动生成 `index.yaml`。 + +`index.yaml`格式如下： + +```yaml +--- +apiversion: v1 +plugins: +- kubernetes-1.31.1: + - name: kubernetes-1.31.1 + version: 1.0.0-1 + updated: "2025-03-05T10:31:02.608017752+08:00" + description: oeDeploy plugin for kubernetes deployment + icon: https://gitee.com/openeuler/oeDeploy/blob/master/oedp/build/static/oeDeploy.png + type: app + sha256sum: 683995d14bbf425f18d1086858f210fc704b1d14edb274382d0e518a5d2a92c1 + size: 1061949301 + urls: + - https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/plugins/kubernetes-1.31.1.tar.gz + - name: kubernetes-1.31.1 + version: 1.0.0-2 + ... +- pytorch: + - name: pytorch + version: 1.0.0-1 + updated: "2025-03-05T10:31:02.608017752+08:00" + description: oeDeploy plugin for pytorch deployment + icon: https://gitee.com/openeuler/oeDeploy/blob/master/oedp/build/static/oeDeploy.png + type: app + sha256sum: 3fe0cb97e01ac9af2c1c8d12d12753f82988ab0e39b5878f359829574102c79d + size: 2373 + urls: + - https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/plugins/pytorch.tar.gz + ... +... +``` + +插件字段含义： + +| 字段 | 含义 | 获取方式 | +| ------------- | ------------------------------------------------------------ | ------------------------------ | +| `name` | 插件名称。允许插件名称中带有版本号，表示软件本身的版本，而非插件的版本。 | 读取main.yaml | +| `version` | 插件版本号。 | 读取main.yaml | +| `updated` | 插件更新的时间，格式为`%Y-%m-%dT%H:%M:%S%z`。允许为空。 | 读取main.yaml | +| `description` | 插件介绍。允许为空。 | 读取main.yaml | +| `icon` | 插件图标地址，用于Web端显示。允许为空。 | 读取main.yaml | +| `type` | 插件类型。保留字段，暂不生效。默认值 `app`。 | 读取main.yaml | +| `sha256sum` | 插件文件sha256数值，用于下载时的完整性校验。 | `sha256sum xxx.tar.gz`命令查询 | +| `size` | 插件文件大小，单位Bytes。 | 压缩包实际大小 | +| `urls` | 插件下载地址，可以有多个。所有url地址都必须在当前插件源目录的范围内。 | 前缀与相对路径的拼接结果 | + +其他字段： + +| 字段 | 含义 | 获取方式 | +| -------------- | --------------------------------------------------------- | -------- | +| `apiversion` | 索引文件格式的版本号。保留字段，暂不生效。默认值 `v1`。 | 脚本生成 | + +## 插件源构建方式 + +执行如下命令，一键生成索引文件 `index.yaml`： + +````bash +python3 make_repo_index.py [plugins_dir] [url_prefix] [output_dir] +```` + +- `plugins_dir`表示当前 Linux 环境下的插件源根目录，脚本会自动识别目录下（包括所有子目录）所有符合条件的 oeDeploy 插件（后缀为.tar.gz的压缩包）。 + oeDeploy 插件合法性的判断标准是：.tar.gz文件中根目录下包含`main.yaml`、`config.yaml`两个文件和`workspace`目录。 + `name`、`version`、`updated`、`description`、`icon`、`type`信息都从`main.yaml`中读取，如果未读取到，则字段可以缺失。 + +- `url_prefix`表示每个插件源的 url 索引前缀，即对外暴露的插件源根目录。 + +- `output_dir`表示索引文件 `index.yaml`输出的目录。 + +例如，当前 Linux 环境上 `/root/build_workspace/storages/plugins`目录中有多个 oeDeploy 插件，同时映射到 `http://x.x.x.x:8080/plugins`，作为文件服务器对外暴露。 + +执行如下命令，可以在 `/root/build_workspace/storages/plugins`目录下生成一个 `index.yaml`，其中每个插件的 `urls`字段是其在文件服务器上的真实访问地址，可以直接下载。 + +````bash +python3 make_repo_index.py /root/build_workspace/storages/plugins http://x.x.x.x:8080/plugins /root/build_workspace/storages/plugins +```` diff --git a/docs/zh/develop_guide.md b/docs/zh/develop_guide.md deleted file mode 100644 index 55f879801df104457858caae6d33b57bc7f42368..0000000000000000000000000000000000000000 --- a/docs/zh/develop_guide.md +++ /dev/null @@ -1,146 +0,0 @@ -# oeDeploy 插件开发指南 - -## 1 oeDeploy 插件介绍 - -oeDeploy 插件（plugin）是 oeDeploy 工具中提供自动化部署能力的组件，通过将复杂的部署流程 ansible 化来实现自动化部署。插件中可能会集成多种部署操作（action），例如安装、卸载、环境清理等，每一个部署操作都会对应一个或多个 ansible playbook。插件的所有可配置项都应当集中配置，以降低使用者的学习成本和开发者的维护成本。 - -## 2 插件目录结构 - -插件开发者在开发插件时应当遵循以下目录结构： - -```text -{ plugin_name } -|-- main.yaml -|-- config.yaml -|-- doc/ -`-- workspace/ -``` - -| 文件或者目录名 | 介绍 | -| -------------- | ------------------------------------------------------------ | -| config.yaml | 包含主机相关的配置，如 ip、密码、密钥、端口号等，还包含了应用的一些部署相关的配置，支持 jinja2 语法 | -| main.yaml | oedp 识别应用部署流程的主配置文件 | -| doc（可选） | 插件相关的文档目录 | -| workspace | 应用的部署能力库 | - -其中，`plugin_name`有以下约束： - -+ 该插件部署的软件名称为`name`，版本为`version`。 -+ `plugin_name`必须是以下两种之一： - + `{name}-{version}` - + `{name}-{version}-xxx` -+ 例如，一个插件用于部署 kubernetes 软件，版本为 1.31.1，那么该插件的名称可以是：kubernetes-1.31.1，kubernetes-1.31.1-20240101，kubernetes-1.31.1-offline-20240101 等。 - -## 3 main.yaml - -main.yaml 主要用于记录插件的关键信息，包括：名称（name）、版本（version）、介绍（description）、操作（action）等，当用户执行`oedp info`命令时，oedp 工具会读取并解析该文件，然后向用户展示其详细信息。 - -在`action`项中，应当是一个字典（key-value map），每一个 key 将作为操作的名称，对应的 value 中记录了该操作的详情。 - -操作详情是一个字典，其中的`description`项是该操作的说明，用于在执行`oedp info`命令时向用户展示，而`tasks`项中则记录该操作的具体步骤，为一个列表，执行该操作时，将按顺序执行每一项步骤。 - -在步骤中，开发者应当指定该步骤需要执行的`playbook`的路径，如果有需要，也可以在`vars`中指定变量文件的路径。所有路径都是相对`workspace`的相对路径。此外，可以指定`scope`，即该步骤需要执行的主机组，默认为 all。 - -```yaml -name: kubernetes -version: 1.31.1 -description: install kubernetes 1.31.1 -action: - install: - description: install kubernetes - tasks: - - name: install kubernetes - playbook: init-k8s.yml - vars: variables.yml - scope: all - delete: - description: delete kubernetes - tasks: - - name: delete kubernetes - playbook: delete-k8s.yml - vars: variables.yml - scope: all - clean: - description: clean cache files - tasks: - - name: clean cache files - playbook: clean-k8s.yml - scope: all -``` - -## 4 config.yaml - -config.yaml 是插件中的用户配置文件，主要包含对主机组的配置和一些其他的全局配置，遵循 ansible 的 inventory 文件配置规则，在执行 ansible playbook 时可直接作为 inventory 传入。 - -```yaml -all: - children: - masters: - hosts: - HOST_IP1: # e.g. 192.168.10.1 - ansible_host: HOST_IP1 # e.g. 192.168.10.1 - ansible_port: 22 - ansible_user: root - ansible_password: "" - architecture: amd64 # e.g. [ amd64, arm64 ] - oeversion: 22.03-LTS # e.g. [ 22.03-LTS, 24.03-LTS ] - workers: - hosts: - HOST_IP2: - ansible_host: HOST_IP2 - ansible_port: 22 - ansible_user: root - ansible_password: "" - architecture: amd64 - oeversion: 22.03-LTS - HOST_IP3: - ansible_host: HOST_IP3 - ansible_port: 22 - ansible_user: root - ansible_password: "" - architecture: amd64 - oeversion: 22.03-LTS - vars: - init_cluster_force: "true" # e.g. [ "true", "false" ] 强制初始化集群 - service_cidr: 10.96.0.0/16 # 服务网段 - pod_cidr: 10.244.0.0/16 # pod ip 网段 - certs_expired: 3650 # 证书过期时间 - has_deployed_containerd: "false" # e.g. [ "true", "false" ] 是否已有 containerd -``` - -## 5 workspace - -workspace 目录中承载了部署脚本的主体内容，目录结构不做限制，需要与 main.yaml 和 config.yaml 中的各参数对应。 - -workspace 目录视为整个插件的根目录。 - -当前示例中，workspace 中的目录结构为： - -```text -workspace -|-- roles -| `-- ... -|-- init-k8s.yml -|-- delete-k8s.yml -|-- clean-k8s.yml -|-- variables.yml -`-- ... -``` - -## 6 插件打包 - -如果要发布插件供用户使用，需要将插件打包成`{plugin_name}.tar.gz`的格式，压缩包的名称和包内目录的名称要对应，且解压后应当仅生成一个目录，例如： - -```text -kubernetes-1.31.1.tar.gz -`-- kubernetes-1.31.1 - |-- main.yaml - |-- config.yaml - `-- workspace/ -``` - -当前示例中，使用如下命令行完成打包： - -````bash -tar zcvf kubernetes-1.31.1.tar.gz kubernetes-1.31.1/ -```` diff --git a/docs/zh/develop_instruction.md b/docs/zh/develop_instruction.md new file mode 100644 index 0000000000000000000000000000000000000000..3176ec5e396afcf505a7bb69ff3e83a384d69b98 --- /dev/null +++ b/docs/zh/develop_instruction.md @@ -0,0 +1,140 @@ +# oeDeploy 插件开发 + +## 1 oeDeploy 插件介绍 + +oeDeploy 插件（plugin）是 oedp 工具中提供自动化部署能力的组件，将复杂的部署流程 ansible 化来实现自动化部署。插件中可能会集成多种部署操作（action），例如安装、卸载、环境清理等，每一个部署操作都会对应一个或多个 ansible playbook。插件的所有可配置项都应当集中配置，以降低使用者的学习成本和开发者的维护成本。 + +## 2 插件目录结构 + +oeDeploy 插件目录名称，即插件名称，可以包含版本号（表示软件本身的版本，而非插件的版本） + +插件目录下包含如下内容： + +| 文件或者目录名 | 类型 | 介绍 | +| -------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| config.yaml | yaml | 对用户暴露的唯一配置文件。包含主机相关的配置，如 ip、密码、密钥、端口号等，还包含了软件部署相关的配置项。 | +| main.yaml | yaml | 包含了插件的各种信息，例如名称、版本号、描述，也包含了每个部署操作（action）执行时的具体步骤，每个步骤都对应一个脚本或者playbook（以workspace为根目录）。 | +| doc | 目录 | 承载插件相关的用户文档。该目录非必需。 | +| workspace | 目录 | 承载了软件安装部署所使用的所有文件、源码、二进制、脚本、playbook等等。目录内结构不做限制。 | + +## 3 main.yaml + +`main.yaml`主要用于记录插件的关键信息，包括：名称（`name`）、版本（`version`）、介绍（`description`）、操作（`action`）等，当用户执行 `oedp info` 命令时，`oedp` 工具会读取并解析该文件，然后向用户展示其详细信息。 + +- `action` 字段是一个字典（key-value map），每一个 key 将作为操作的名称。在下方的案例中，用户可以通过 `oedp run install`、`oedp run delete`、`oedp run clean` 命令行来触发对应的执行步骤（`tasks`）。 +- 每一个具体操作中，`description` 项是该操作的说明，用于在执行 `oedp info` 命令时向用户展示；而 `tasks` 项中则记录该操作的具体步骤，为一个列表，执行该操作时，将按顺序执行每一项步骤。 +- 在每个步骤中，开发者应当指定该步骤需要执行的 `playbook` 的路径，也可以在 `vars` 中指定变量文件的路径，`vars` 字段不是必需的。这里所填写的路径都是 `workspace` 目录的相对路径。此外，可以指定 `scope`，即该步骤需要执行的主机组，默认为 all。 +- 在下方的案例中，当用户执行了 `oedp run install` 命令，工具会按顺序执行如下命令： + `ansible-playbook set-env.yml -i config.yaml -e variables.yml --limit all` + `ansible-playbook init-k8s.yml -i config.yaml -e variables.yml --limit all` + 这里的 `config.yaml` 会在下文介绍。 + +```yaml +name: kubernetes +version: 1.31.1 +description: install kubernetes 1.31.1 +action: + install: + description: install kubernetes + tasks: + - name: prepare for install + playbook: set-env.yml + scope: all + - name: install kubernetes + playbook: init-k8s.yml + vars: variables.yml + scope: all + delete: + description: delete kubernetes + tasks: + - name: delete kubernetes + playbook: delete-k8s.yml + scope: all + clean: + description: clean cache files + tasks: + - name: clean cache files + playbook: clean-k8s.yml + scope: all +``` + +## 4 config.yaml + +`config.yaml`是插件中的用户配置文件，主要包含主机组的节点信息，以及部署软件相关的信息，遵循 ansible 的 inventory 文件配置规则，工具在执行 ansible playbook 时直接作为 inventory 传入。 + +需要注意，`config.yaml` 是对普通用户暴露的唯一配置文件，应当注意美观，避免歧义，并保留适当的注释说明。 + +```yaml +all: + children: + masters: + hosts: + 172.27.76.114: # master node IP + ansible_host: 172.27.76.114 # master node IP + ansible_port: 22 + ansible_user: root + ansible_password: PASSWORD + architecture: amd64 # amd64 or arm64 + oeversion: 24.03-LTS # 22.03-LTS or 24.03-LTS + workers: + hosts: + 172.27.70.60: # worker node IP + ansible_host: 172.27.70.60 # worker node IP + ansible_port: 22 + ansible_user: root + ansible_password: PASSWORD + architecture: amd64 + oeversion: 24.03-LTS + 172.27.72.90: # worker node IP + ansible_host: 172.27.72.90 # worker node IP + ansible_port: 22 + ansible_user: root + ansible_password: PASSWORD + architecture: amd64 + oeversion: 24.03-LTS + vars: + init_cluster_force: "true" + service_cidr: 10.96.0.0/16 + pod_cidr: 10.244.0.0/16 + certs_expired: 3650 + has_deployed_containerd: "false" + ansible_ssh_common_args: "-o StrictHostKeyChecking=no" +``` + +## 5 workspace + +`workspace` 目录中承载了部署脚本的主体内容，目录结构不做限制，需要与 `main.yaml`和 `config.yaml`中的各参数对应。 + +`workspace` 目录视为整个插件执行过程中的根目录。 + +当前示例中，`workspace`中的目录结构为： + +```text +workspace +|-- roles +| `-- ... +|-- clean-k8s.yml +|-- delete-k8s.yml +|-- init-k8s.yml +|-- set-env.yml +|-- variables.yml +`-- ... +``` + +## 6 插件打包 + +如果要发布插件供用户使用，需要将插件打包成 `{plugin_name}.tar.gz` 的格式，压缩包的名称和包内目录的名称要对应，且解压后应当仅生成一个目录，例如： + +```text +kubernetes-1.31.1.tar.gz +`-- kubernetes-1.31.1 + |-- main.yaml + |-- config.yaml + `-- workspace/ +``` + +当前示例中，使用如下命令行完成打包： + +````bash +tar zcvf kubernetes-1.31.1.tar.gz kubernetes-1.31.1/ +```` diff --git a/docs/zh/feature.md b/docs/zh/feature.md deleted file mode 100644 index 4c269cd2f6e33ff8b472ed0745f31dd47da763af..0000000000000000000000000000000000000000 --- a/docs/zh/feature.md +++ /dev/null @@ -1,19 +0,0 @@ -# 开发中特性 - -- Debug 模式，支持执行指定的 task。 -- 部署插件初始化功能。 -- 部署插件检查模块。 -- 插件源管理模块，根据插件名称自动下载、解压插件，插件源可配置。 -- oeDeploy Web页面，支持自定义部署任务、节点信息管理、部署流程可视化。 - -# 已规划特性 - -- 部署插件商店，页面展示插件列表，支持页面创建部署任务。 -- 兼容 Helm 部署项目。 - -# 已发布特性 - -## v1.0.1 - -- 使用 ansible 作为分布式节点的命令下发平台。 -- 支持 playbook 粒度的流程编排。 diff --git a/docs/zh/Introduction.md b/docs/zh/introduction.md similarity index 69% rename from docs/zh/Introduction.md rename to docs/zh/introduction.md index d2e60b86350812ea5811ce4d07bfdcf83dcce782..f21fc26bd6b166446f297365ded3e832f281180f 100644 --- a/docs/zh/Introduction.md +++ b/docs/zh/introduction.md @@ -9,13 +9,12 @@ oeDeploy 是一款轻量级的软件部署工具，旨在帮助开发者快速 # 下载 / Download -- [命令行工具 oedp（aarch64）](https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/aarch64/Packages/oedp-1.0.1-1.oe2503.aarch64.rpm) -- [命令行工具 oedp（x86_64）](https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/x86_64/Packages/oedp-1.0.1-1.oe2503.x86_64.rpm) +- [命令行工具 oedp (noarch)](https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/) - [oeDeploy 部署插件](https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/plugins/) # 文档 / Docs - [命令行工具 oedp 使用指南](./command.md) -- [oeDeploy 工具特性](./feature.md) -- [oeDeploy 应用案例](./usecase.md) -- [oeDeploy 插件开发指南](./develop_guide.md) +- [oeDeploy 应用案例](./use_case.md) +- [oeDeploy 插件开发指南](./develop_instruction.md) +- [oeDeploy MCP Server 使用说明](./mcp_instruction.md) diff --git a/docs/zh/mcp_instruction.md b/docs/zh/mcp_instruction.md new file mode 100644 index 0000000000000000000000000000000000000000..09b48e31de319de58618e7d3e8b2a9a45b223005 --- /dev/null +++ b/docs/zh/mcp_instruction.md @@ -0,0 +1,8 @@ +# oeDeploy MCP Server 使用说明 + +MCP（Model Context Protocol，模型上下文协议）是一项开放协议，旨在为 AI 系统与外部数据源、工具之间建立标准化连接接口；其核心是通过客户端—服务器架构，让大语言模型能安全高效地访问本地文件、数据库、API服务等资源，实现跨平台、跨工具的智能交互。 + +oeDeploy 当前提供两种 MCP Server： + +1. [oeDeploy MCP Server mcp-oedp](https://gitee.com/openeuler/oeDeploy/blob/master/oedp-mcp/mcp-oedp/README.md)，该 MCP Server 用于帮助用户智能调用 oeDeploy 相关能力实现软件快速部署。 +2. [oeDeploy MCP Server mcp-make-oedp-plugin](https://gitee.com/openeuler/oeDeploy/blob/master/oedp-mcp/mcp-make-oedp-plugin/README.md)，该 MCP Server 用于帮助用户快速开发自定义 oeDeploy 插件。 diff --git a/docs/zh/use_case.md b/docs/zh/use_case.md new file mode 100644 index 0000000000000000000000000000000000000000..3132b3ac5ab10054e0e1e3dc902946e0878d9dec --- /dev/null +++ b/docs/zh/use_case.md @@ -0,0 +1,898 @@ +# oeDeploy 应用案例 + +## 应用案例 1：Kubernetes 一键部署 + +1. 准备 3 个 2U4G 的虚拟机环境（三层网络互通），使用的 OS 版本为 openEuler 24.03 或 22.03 的任意版本，目标是部署由 1 个 master、2 个 worker 构成的 k8s 集群。 + +2. 在任意节点上，下载并安装 oeDeploy 的命令行工具 oedp。 + + ````bash + wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/oedp-1.1.1-0.oe2403sp2.noarch.rpm + yum install -y oedp-1.1.1-0.oe2403sp2.noarch.rpm + ```` + +3. 执行以下命令，获取插件包，确保当前目录下出现了目录`kubernetes-1.31.1`。 + + ```shell + oedp repo update + oedp init kubernetes-1.31.1 + ``` + +4. 执行`info`命令以查看插件详细信息。 + + ```shell + oedp info -p kubernetes-1.31.1 + ``` + +5. 修改项目配置文件，根据实际情况配置节点信息。 + + ```shell + vim kubernetes-1.31.1/config.yaml + ``` + + ````yaml + all: + children: + masters: + hosts: + # master节点数量须为奇数 + 172.27.76.114: # master node IP + ansible_host: 172.27.76.114 # master node IP + ansible_port: 22 + ansible_user: root + ansible_password: "" + architecture: amd64 # [ amd64, arm64 ] + oeversion: 24.03-LTS # [ 22.03-LTS, 24.03-LTS ] + runtime: docker # [ docker, containerd ] + workers: + hosts: + 172.27.70.60: # worker node IP + ansible_host: 172.27.70.60 # worker node IP + ansible_port: 22 + ansible_user: root + ansible_password: "" + architecture: amd64 + oeversion: 24.03-LTS + runtime: docker + 172.27.72.90: + ansible_host: 172.27.72.90 + ansible_port: 22 + ansible_user: root + ansible_password: "" + architecture: amd64 + oeversion: 24.03-LTS + runtime: docker + new-workers: # new-workers 字段不可删除 + hosts: + vars: + ansible_ssh_common_args: '-o StrictHostKeyChecking=no' + + init_cluster_force: "true" # e.g. [ "true", "false" ] 强制初始化集群 + remove_master_no_schedule_taints: "true" + service_cidr: 10.96.0.0/16 # 服务网段 + pod_cidr: 10.244.0.0/16 # pod ip 网段 + certs_expired: 3650 # 证书过期时间 + # lb_kube_apiserver_ip: + lb_kube_apiserver_port: 8443 + has_deployed_containerd: "false" # e.g. [ "true", "false" ] 是否已有 containerd + + # 以下参数需要与 build 过程中的 host.ini 保持一致，如果不涉及请忽视 + kubernetes_version: 1.31.1 + calico_version: 3.28.2 + pause_image: "registry.k8s.io/pause:3.10" + ```` + + > 注意：须确保节点间 ssh 可联通，支持密码登录和密钥登录，如果使用密钥登录，则不需要配置密码。 + +6. 执行以下命令以开始自动化部署。 + + ```shell + oedp run install -p kubernetes-1.31.1 + ``` + +7. 执行以下命令以卸载 Kubernetes。 + + ```shell + oedp run uninstall -p kubernetes-1.31.1 + ``` + + > -p 参数表示解压后的文件目录。如果进入 kubernetes-1.31.1 插件根目录，执行 oedp 命令时无需 -p 参数。 + +## 应用案例 2：AnythingLLM 一键部署 + +1. 下载 oedp 命令行工具，并用 yum 安装。如有更新的 oedp 版本，可以选择新版本。 + + ```bash + wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/oedp-1.1.1-0.oe2403sp2.noarch.rpm + yum install -y oedp-1.1.1-0.oe2403sp2.noarch.rpm + ``` + +2. 获取并初始化`AnythingLLM`插件。 + + ```shell + oedp repo update + oedp init anythingLLM + ``` + +3. 根据实际情况，修改 config.yaml。确保部署节点网络正常。 + +4. 一键部署： + + ````bash + oedp run install -p angthingLLM # -p <插件目录> + ```` + +5. 一键卸载： + + ````bash + oedp run uninstall -p angthingLLM # -p <插件目录> + ```` + +### Demo：部署并打印 AnythingLLM 信息 + +1. 编辑 config.yaml 文件。 + + ````yaml + all: + hosts: + host1: + ansible_host: 192.168.124.17 # 远端IP + ansible_port: 22 # 端口号 + ansible_user: root # 用户名 + ansible_password: passwd # 密码 + + vars: + docker_download_url: + x86_64: https://download.docker.com/linux/static/stable/x86_64/docker-26.1.4.tgz + aarch64: https://download.docker.com/linux/static/stable/aarch64/docker-26.1.4.tgz + docker_download_path: /tmp + docker_image_urls: https://docker.m.daocloud.io + + container_name: "anythinglLLM-container" + docker_image: "mintplexlabs/anythingllm" + storage_location: "{{ lookup('env', 'HOME') }}/anythingllm" + host_port: 3001 + ```` + +2. 进入容器并测试 AnythingLLM 服务。 + + - 进入容器： + + ````bash + docker exec -it anythinglLLM-container /bin/bash + ```` + + - 测试 AnythingLLM 服务： + + ````bash + curl localhost:3001 + ```` + +3. 部署环境测试 AnythingLLM 服务。 + + ```bash + -curl 192.168.124.17:3001/ curl localhost:3001 + ``` + +4. 正常返回如下: + + ```html + + + + + + + AnythingLLM | Your personal LLM trained on anything + + + + + + + + + + + + + + + + + + +
+ + + ``` + +## 应用案例 3：DeepSeek-R1 一键部署 + +1. 准备一个 openEuler 环境（22.03-LTS-SPX、24.03-LTS-SPX），8B 模型的建议规格大于 8U16G。 + +2. 下载 oedp 命令行工具，并用 yum 安装。 + + ````bash + wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/oedp-1.1.1-0.oe2403sp2.noarch.rpm + yum install -y oedp-1.1.1-0.oe2403sp2.noarch.rpm + ```` + +3. 获取并初始化`DeepSeek-R1`插件。 + + ````bash + oedp repo update + oedp init deepseek-r1 + ```` + +4. 根据实际情况修改 deepseek-r1/config.yaml。用户可以直接使用这里的示例，不需要任何修改。 + + ````yaml + all: + hosts: + # 本地部署 或 远端部署 二选一 + # ================ 本地部署 ===================== + localhost: + ansible_connection: local + # ================ 远端部署 ===================== + # host1: + # ansible_host: 127.0.0.1 # 远端IP + # ansible_port: 22 # 端口号 + # ansible_user: root # 用户名 + # ansible_password: PASSWORD # 密码 + vars: + deepseek_version: 8b + # ollama 官方下载地址: https://ollama.com/download/ollama-linux-amd64.tgz，注意区分amd64和arm64 + # 为提高下载速度，已暂存在 OEPKGS 服务器上 + ollama_download: https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/2025.0330/ollama-linux-amd64.tgz + ollama_download_path: /tmp # 下载的目标路径 + # 模型文件下载地址: https://www.modelscope.cn/models/unsloth/DeepSeek-R1-Distill-Llama-8B-GGUF/resolve/master/DeepSeek-R1-Distill-Llama-8B-Q4_K_M.gguf + # 为提高下载速度，已暂存在 OEPKGS 服务器上 + modelfile_download: https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/2025.0330/DeepSeek-R1-Distill-Llama-8B-Q4_K_M.gguf + modelfile_download_path: /tmp # 下载的目标路径 + # 模型参数 + parameter: + temperature: 0.7 + top_p: 0.7 + top_k: 30 + num_ctx: 4096 + num_thread: 8 # 线程数，建议不超过 CPU 核数 + num_gpu: 0 # GPU数 0 for none, -1 for all. + + ansible_ssh_common_args: '-o StrictHostKeyChecking=no' + ```` + +5. 一键触发 DeepSeek-R1 自动化部署，oeDeploy 工具会下载所需的文件，自动安装部署，并完成对 DeepSeek-R1 的配置。 + + ````bash + oedp run install -p deepseek-r1 # -p + ```` + +6. 在部署完成后的节点上，打开 DeepSeek-R1 交互终端，开始对话。 + + ````bash + ollama run deepseek-r1:8b + ```` + +## 应用案例 4：EulerCopilot 一键部署 + +### 前提条件 + +1. 组件介绍 + + | 组件 | 端口 | 说明 | + |-------------------------|-------------------------|------------| + | euler-copilot-framework | 8002（内部端口） | 智能体框架服务 | + | euler-copilot-web | 8080 | 智能体前端界面 | + | euler-copilot-rag | 9988（内部端口） | 检索增强服务 | + | authhub-backend-service | 11120 （内部端口） | 鉴权服务后端 | + | authhub-web-service | 8000 | 鉴权服务前端 | + | mysql | 3306（内部端口） | MySQL数据库 | + | redis | 6379（内部端口） | Redis数据库 | + | minio | 9000（内部端口） 9001（外部部端口） | minio数据库 | + | mongo | 27017（内部端口） | mongo数据库 | + | postgres | 5432（内部端口） | 向量数据库 | + | secret_inject | 无 | 配置文件安全复制工具 | + +2. 软件要求 + + | 类型 | 版本要求 | 说明 | + |--------|----------------------------------|-----------------------------------------------------------| + | 操作系统 | openEuler 22.03 LTS 及以上版本 | 无 | + | K3s | >= v1.30.2，带有 Traefik Ingress 工具 | K3s 提供轻量级的 Kubernetes 集群，易于部署和管理 | + | Helm | >= v3.15.3 | Helm 是一个 Kubernetes 的包管理工具，其目的是快速安装、升级、卸载 EulerCopilot 服务 | + | python | >= 3.9.9 | python3.9.9 以上版本为模型的下载和安装提供运行环境 | + +3. 硬件要求 + + | 硬件资源 | 服务器（最小要求） | 服务器（推荐） | + |----------|-----------------------------|-------------------------| + | CPU | 4 核心 | 16 核心及以上 | + | RAM | 4 GB | 64 GB | + | 存储 | 32 GB | 64G | + | 大模型名称 | deepseek-llm-7b-chat | DeepSeek-R1-Llama-8B | + | 显存（GPU） | 8 GB（NVIDIA RTX A4000, 1个） | 16 GB（NVIDIA A100, 2个） | + + **注意**： + + - 若无 GPU 或 NPU 资源，建议通过调用 OpenAI 接口的方式来实现功能。 + - 调用第三方 OpenAI 接口的方式不需要安装高版本的 python (>=3.9.9)。 + - 如有 k8s 集群环境，则不需要单独安装 k3s，要求 version >= 1.28。 + +4. 网络要求 + + - 可访问 hub.oepkgs.net + - 可访问 modelscope.cn + - 开放端口：80/443/ + +5. 域名要求 + + 为确保 EulerCopilot 的正确部署和使用，请准备以下两个服务的域名：authhub、eulercopilot。这些子域名需属于同一个主域名下，例如 +`www.eulercopilot.local`、`authhub.eulercopilot.local`。 + + 您可以通过两种方式来完成这项准备工作： + + - **预先申请域名**：为每个服务（AuthHub、Euler Copilot）分别注册上述格式的子域名。 + - **本地配置**：如果是在开发或测试环境中，您可以直接在本地 Windows 主机文件中进行配置。打开位于 + `C:\Windows\System32\drivers\etc\hosts` 的文件，并添加相应的条目以映射这些子域名到本地或特定的 IP 地址，例如： + + ```bash + 172.0.0.1 authhub.eulercopilot.local + 172.0.0.1 www.eulercopilot.local + ``` + +### 部署过程 + +1. 安装 oeDeploy 工具。 + + ```shell + wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/oedp-1.1.1-0.oe2403sp2.noarch.rpm + yum install -y oedp-1.1.1-0.oe2403sp2.noarch.rpm + ``` + +2. 获取并初始化 EulerCopilot 插件。 + + ```shell + oedp repo update + oedp init euler-copilot + ``` + +3. 根据实际情况修改 `config.yaml` 文件，示例如下： + + ```yaml + all: + hosts: + host1: + # 节点空余内存需要大于 16G，建议规格 32G 以上 + # 部署节点 IP + ansible_host: HOST_IP + # 部署节点 SSH 端口 + ansible_port: 22 + # 部署节点用户 + ansible_user: root # 目前仅支持 root 用户 + # 部署节点密码 + ansible_password: PASSWORD + + vars: + ansible_ssh_common_args: '-o StrictHostKeyChecking=no' + + # 部署日志目录 + log_dir: "/var/log/deploy-euler-copilot" + + # 源码仓库配置 + repo_config: + # 源码 url + url: "https://gitee.com/openeuler/euler-copilot-framework.git" + # 源码仓放置目录 + dest_dir: "/opt/euler-copilot-framework" + # 指定分支、tag 和 commit + version: "release-0.9.5" + # 是否覆盖本地修改 + force: yes + + # 模型配置 + models: + # 用于问答的大模型；需要为 OpenAI 兼容接口 + answer: + # [必填] 接口 URL（无需带上“v1”后缀） + endpoint: https://api.deepseek.com + # [必填] 接口 API Key；默认置空 + key: sk-xxx + # [必填] 模型名称 + name: deepseek-chat + # [必填] 模型最大上下文数；建议 >= 8192 + ctxLength: 8192 + # 模型最大输出长度，建议 >= 2048 + maxTokens: 8192 + # 用于 Function Call 的模型；建议使用特定推理框架 + functionCall: + # 推理框架类型，默认为 ollama + # 可用的框架类型：["vllm", "sglang", "ollama", "openai"] + backend: openai + # 模型地址；不填则与问答模型一致 + endpoint: https://dashscope.aliyuncs.com/compatible-mode/v1 + # API Key；不填则与问答模型一致 + key: sk-xxx + # 模型名称；不填则与问答模型一致 + name: qwen-plus + # 模型最大上下文数；不填则与问答模型一致 + ctxLength: + # 模型最大输出长度；不填则与问答模型一致 + maxTokens: + # 用于数据向量化（Embedding）的模型 + embedding: + # 推理框架类型，默认为 openai + # [必填] Embedding 接口类型：["openai", "mindie"] + type: openai + # [必填] Embedding URL（需要带上“v1”后缀） + endpoint: https://api.siliconflow.cn/v1 + # [必填] Embedding 模型 API Key + key: sk-xxx + # [必填] Embedding 模型名称 + name: BAAI/bge-m3 + ``` + +4. 一键部署： + + ```shell + oedp run install -p ./euler-copilot + ``` + +5. 验证安装： + + 您可以参考 [此文档](https://e.gitee.com/open_euler/repos/openeuler/euler-copilot-framework/blob/master/docs/user-guide/%E9%83%A8%E7%BD%B2%E6%8C%87%E5%8D%97/%E7%BD%91%E7%BB%9C%E7%8E%AF%E5%A2%83%E4%B8%8B%E9%83%A8%E7%BD%B2%E6%8C%87%E5%8D%97.md#%E9%AA%8C%E8%AF%81%E5%AE%89%E8%A3%85) 来验证安装是否成功。 + +6. 一键卸载： + + ```shell + oedp run uninstall -p ./euler-copilot + ``` + +## 应用案例 5：KubeRay 一键部署 + +### 环境准备 + +1. 部署 Kubernetes 集群： + + 在目标集群机器上部署 Kubernetes 1.31.1，此处以 1 master + 2 worker 的标准 K8S 集群为例，其中 master 节点的 IP 为 192.168.1.101。可使用`kubernetes-1.31.1`插件进行自动化部署。 + +2. 安装 Helm： + + 在 master 节点上安装 Helm，可使用`helm-3.9.0`插件进行自动化安装。 + +### 部署 KubeRay + +1. 获取`kuberay`插件： + + 使用以下命令，获取并初始化`kuberay`插件。 + + ```shell + oedp repo update + oedp init kuberay + ``` + +2. 修改`config.yaml`： + + 以下是`kuberay/config.yaml`的示例，根据实际情况修改此文件。 + + ```yaml + all: + hosts: + host1: + ansible_host: 192.168.1.101 # master 节点的 IP + ansible_port: 22 # ssh 的端口 + ansible_user: root # ssh 的用户，非root用户需要 sudo 权限 + ansible_password: PASSWORD # 上述用户的密码 + vars: + temp_path: /tmp + namespace: kuberay # 命名空间 + version: 1.2.2 # KubeRay chart 的版本 + + helm_repo_name: "kuberay" # 本地 Helm 仓库别名 + helm_repo_url: "https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/2025.0330/kuberay-helm" + + kuberay_operator_values_file: "" + # 以上配置项 kuberay_operator_values_file 为高级配置：指定一个 values 文件，用于自定义 + # KubeRay operator 组件的安装。需填写绝对路径，若留空，则采用以下配置： + kuberay_operator_values: + repository: "hub.oepkgs.net/oedeploy/quay.io/kuberay/operator" # KubeRay operator docker 镜像 url + tag: v1.2.2 # KubeRay operator docker 仓库 tag + + ray_cluster_values_file: "" + # 以上配置项 ray_cluster_values_file 为高级配置：指定一个 values 文件，用于自定义 + # Ray 组件的安装。需填写绝对路径，若留空，则采用以下配置： + ray_cluster_values: + repository: "hub.oepkgs.net/oedeploy/rayproject/ray-with-pytorch" # Ray docker 镜像 url + tag: 2.9.0 # Ray docker 仓库 tag；使用默认 docker 源时，x86 为 2.9.0, arm 为 2.9.0-aarch64；具体的 tag 请至配置的仓库确认 + head: # 头节点资源 + cpu: "1" + memory: "2G" + worker: # 工作节点资源 + num: 1 + cpu: "1" + memory: "1G" + training: # 模型训练参数 + pip: "https://pypi.tuna.tsinghua.edu.cn/simple" + batch_size: 1024 + epoch: 5 + ``` + +3. 执行自动化部署： + + 在插件目录下执行`oedp run install`，或在任意位置执行`oedp run install -p [插件目录]`，即可完成自动化部署 KubeRay。 + +### 查看 Dashboard + +1. 查询对应端口： + + 在 master 节点，使用`kubectl get svc -A`命令查看端口映射： + + ````bash + NAMESPACE NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + default kubernetes ClusterIP 10.96.0.1 443/TCP 24h + kube-system kube-dns ClusterIP 10.96.0.10 53/UDP,53/TCP,9153/TCP 24h + kuberay kuberay-operator ClusterIP 10.96.175.101 8080/TCP 9h + kuberay ray-cluster-kuberay-head-svc NodePort 10.96.168.232 10001:32414/TCP,8265:31457/TCP,8080:31582/TCP,6379:31938/TCP,8000:32102/TCP 9h + ```` + + 其中 8265 对应的端口，即为 Dashboard 的端口。 + +2. 打开 Dashboard 页面： + 使用 `http://ip:port/` 链接，即可打开 Dashboard 页面，查看 Ray Job / Serve / Cluster 及资源、日志等信息。其中 IP 为 master 节点 IP，port 为 3.1 中 8265 对应的端口。 + +### Demo 1：基于 FashionMNIST 数据集的 MLP 模型训练推理 + +1. 已完成 KubeRay 部署，Pod 资源要求至少 4U。 + +2. 在 master 节点，执行以下命令，即可一键自动完成模型训练、推理。 + + ````bash + oedp run train -p kuberay + ```` + +### Demo 2：单 Pod 与多 Pod 运行同个训练模型的时间对比 + +在 Kuberay 部署前，通过修改 config.yaml，进行 Pod 资源配置。 + +1. 将单 Pod 的资源设置为： + + ````bash + head: + cpu: "7" + memory: "14G" + worker: + num: 0 + ```` + + 然后执行： + + ````bash + oedp run install -p kuberay + oedp run train -p kuberay + ```` + +2. 将多 Pod 的资源设置为： + + ````bash + head: + cpu: "7" + memory: "14G" + worker: + num: 2 + cpu: "5" + memory: "10G" + ```` + + 然后执行： + + ````bash + oedp run install -p kuberay + oedp run train -p kuberay + ```` + +3. 对比两者运行时间： + + 该条件下，单 Pod 运行时间约为 25s，多 Pod 运行时间约为 67s。 + +## 应用案例 6：Pytorch 一键部署 + +1. 准备一个 k8s 集群。 + +2. 下载 oedp 命令行工具，并用 yum 安装。如有更新的 oedp 版本，可以选择新版本。 + + ````bash + wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/oedp-1.1.1-0.oe2403sp2.noarch.rpm + yum install -y oedp-1.1.1-0.oe2403sp2.noarch.rpm + ```` + +3. 获取并初始化`pytorch`插件。 + + ```shell + oedp repo update + oedp init pytorch + ``` + +4. 根据实际情况，修改 config.yaml。请确保目标节点为 k8s 的 master 节点。`kubectl_apply`需要与 workspace 下的 playbook 对应。 + +5. 一键部署： + + ````bash + oedp run install -p pytorch # -p <插件目录> + ```` + +6. 一键卸载： + + ````bash + oedp run uninstall -p pytorch # -p <插件目录> + ```` + +### Demo 1：部署并打印 PyTorch 信息 + +1. 根据实际情况，修改 config.yaml。以下为示例： + + ````yaml + all: + hosts: + localhost: + ansible_connection: local + vars: + ansible_ssh_common_args: '-o StrictHostKeyChecking=no' + # ================ demo 1: pytorch with http.server ===================== + kubectl_apply: pytorch-deployment.yaml + namespace: pytorch-namespace + replicas: 1 + containers: + http: + name: http-container + image: hub.oepkgs.net/oedeploy/pytorch/pytorch:latest # amd64 + # image: hub.oepkgs.net/oedeploy/pytorch/torchserve:latest-arm64 # arm64 + workspace_mount: /tmp + service: + port: 8080 + target_port: 8080 + node_port: 30699 + training: + epoch: 2 + ```` + +2. 执行一键部署。 + + ```shell + oedp run install -p pytorch + ``` + +3. 查看 pod。 + + ````bash + kubectl get pods -n pytorch-namespace + ```` + + ```` + NAME READY STATUS RESTARTS AGE + pytorch-deployment-db5d59bcb-ptqnp 1/1 Running 0 15m + ```` + +4. 查看端口映射。 + + ````bash + kubectl get svc -n pytorch-namespace + ```` + + ```` + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + pytorch-service NodePort 10.96.50.156 80:30699/TCP 15m + ```` + +5. 访问网页。 + + ````text + http://x.x.x.x:30699/ # master所在节点 + ```` + +6. 进入容器。 + + ````bash + kubectl exec -n pytorch-namespace -it pytorch-deployment-db5d59bcb-ptqnp -- /bin/bash + ```` + +7. 打印 PyTorch 信息。 + + ````bash + python -c "import torch; print(torch.__version__); print(torch.tensor([1.0, 2.0, 3.0]) + torch.tensor([4.0, 5.0, 6.0]))" + ```` + +### Demo 2：基于 MNIST 数据集的轻量 CNN 模型训练 + +1. 基于 demo 1 已完成 PyTorch 部署。 + +2. 一键自动完成模型训练。 + + ````bash + oedp run train -p pytorch # -p <插件目录> + ```` + + 回显形如： + + ````bash + ...... + TASK [Display training output] ***************************************************************************************************************************************************************************************************************** + ok: [localhost] => { + "msg": [ + "Train Epoch: 0 [0/60000]\tLoss: 2.3114", + "Train Epoch: 0 [6400/60000]\tLoss: 0.3884", + "Train Epoch: 0 [12800/60000]\tLoss: 0.1483", + "Train Epoch: 0 [19200/60000]\tLoss: 0.0510", + "Train Epoch: 0 [25600/60000]\tLoss: 0.1151", + "Train Epoch: 0 [32000/60000]\tLoss: 0.0191", + "Train Epoch: 0 [38400/60000]\tLoss: 0.0690", + "Train Epoch: 0 [44800/60000]\tLoss: 0.1995", + "Train Epoch: 0 [51200/60000]\tLoss: 0.0417", + "Train Epoch: 0 [57600/60000]\tLoss: 0.1821", + "Test Accuracy: 9862/10000 (98.62%)", + "Train Epoch: 1 [0/60000]\tLoss: 0.0052", + ...... + "Train Epoch: 1 [57600/60000]\tLoss: 0.0115", + "Test Accuracy: 9877/10000 (98.77%)" + ] + } + ```` + +## 应用案例 7：TensorFlow 一键部署 + +1. 准备一个 k8s 集群。 + +2. 下载 oedp 命令行工具，并用 yum 安装。如有更新的 oedp 版本，可以选择新版本。 + + ````bash + wget https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/noarch/oedp-1.1.1-0.oe2403sp2.noarch.rpm + yum install -y oedp-1.1.1-0.oe2403sp2.noarch.rpm + ```` + +3. 获取并初始化`tensorflow`插件。 + + ```shell + oedp repo update + oedp init tensorflow + ``` + +4. 根据实际情况，修改 config.yaml。请确保目标节点为 k8s 的 master 节点。`kubectl_apply`需要与 workspace 下的 playbook 对应。 + +5. 一键部署： + + ````bash + oedp run install -p tensorflow # -p <插件目录> + ```` + +6. 一键卸载： + + ````bash + oedp run uninstall -p tensorflow # -p <插件目录> + ```` + +### Demo 1: TensorFlow with Jupyter + +1. 编辑 config.yaml 文件。 + + ````yaml + all: + hosts: + localhost: + ansible_connection: local + + vars: + ansible_ssh_common_args: '-o StrictHostKeyChecking=no' + + kubectl_apply: tensorflow-deployment.yaml + namespace: tensorflow-namespace + replicas: 1 + containers: + name: tensorflow-jupyter + image: hub.oepkgs.net/oedeploy/tensorflow/tensorflow:latest-jupyter # amd64 only + command: ["jupyter", "notebook", "--ip=0.0.0.0", "--allow-root", "--no-browser"] + service: + name: tensorflow-service + port: 80 + target_port: 8888 + node_port: 30088 + ```` + +2. 查看 pod 状态。 + + ````bash + kubectl get pods -n tensorflow-namespace + ```` + + ```` + NAME READY STATUS RESTARTS AGE + tensorflow-deployment-75b85948d8-w2n7b 1/1 Running 0 4m1s + ```` + +3. 进入 pod 容器，会有一个很明显的 TensorFlow 大字提示。 + + ````bash + kubectl exec -n tensorflow-namespace -it tensorflow-deployment-75b85948d8-w2n7b -- /bin/bash + ```` + +4. 打印 TensorFlow 信息。 + + ````bash + python -c "import tensorflow as tf; print(tf.__version__)" + ```` + +5. 打开 Jupyter 界面。 + + ````bash + http://x.x.x.x:30088/ # master 所在节点 + ```` + +### Demo 2：分布式部署训练集群 + +1. 编辑 config.yaml 文件。 + + ````yaml + all: + hosts: + localhost: + ansible_connection: local + + vars: + ansible_ssh_common_args: '-o StrictHostKeyChecking=no' + + kubectl_apply: tensorflow-distributed.yaml + namespace: tensorflow-namespace + ps: + replicas: 2 + containers: + name: tensorflow-ps + image: hub.oepkgs.net/oedeploy/tensorflow/tensorflow:latest # amd64 only + service: + name: tensorflow-ps-service + port: 2222 + target_port: 2222 + worker: + replicas: 2 + containers: + name: tensorflow-worker + image: hub.oepkgs.net/oedeploy/tensorflow/tensorflow:latest # amd64 only + service: + name: tensorflow-worker-service + port: 2222 + target_port: 2222 + ```` + +2. 查看 pod 状态。 + + ````bash + kubectl get pods -n tensorflow-namespace + ```` + + ```` + NAME READY STATUS RESTARTS AGE + tensorflow-ps-fdddfdb5f-8fc98 1/1 Running 0 2m59s + tensorflow-ps-fdddfdb5f-dgqm9 1/1 Running 0 2m59s + tensorflow-worker-6cd8947b75-gxcnq 1/1 Running 0 2m59s + tensorflow-worker-6cd8947b75-wbt57 1/1 Running 0 2m59s + ```` + + ````bash + kubectl logs tensorflow-ps-fdddfdb5f-8fc98 -n tensorflow-namespace + ```` + + ```` + 2025-02-07 09:25:24.882206: I tensorflow/core/util/port.cc:153] oneDNN custom operations are on. You may see slightly different numerical results due to floating-point round-off errors from different computation orders. To turn them off, set the environment variable `TF_ENABLE_ONEDNN_OPTS=0`. + 2025-02-07 09:25:24.915813: I tensorflow/core/platform/cpu_feature_guard.cc:210] This TensorFlow binary is optimized to use available CPU instructions in performance-critical operations. + To enable the following instructions: AVX2 AVX512F AVX512_VNNI FMA, in other operations, rebuild TensorFlow with the appropriate compiler flags. + TensorFlow version: 2.18.0 + Environment variables: environ({'PATH': '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin', 'HOSTNAME': 'tensorflow-ps-fdddfdb5f-8fc98', 'DEBIAN_FRONTEND': 'noninteractive', 'LANG': 'C.UTF-8', 'TF_CONFIG': '{\n "cluster": {\n "ps": ["tensorflow-ps:2222"],\n "worker": ["tensorflow-worker-0:2222", "tensorflow-worker-1:2222"]\n },\n "task": {"type": "ps", "index": 0}\n}\n', 'KUBERNETES_PORT_443_TCP_PROTO': 'tcp', 'TENSORFLOW_PS_PORT_2222_TCP_PROTO': 'tcp', 'TENSORFLOW_WORKER_SERVICE_PORT': '2222', 'TENSORFLOW_WORKER_PORT': 'tcp://10.96.56.106:2222', 'KUBERNETES_SERVICE_HOST': '10.96.0.1', 'KUBERNETES_PORT_443_TCP_PORT': '443', 'TENSORFLOW_PS_PORT_2222_TCP_PORT': '2222', 'TENSORFLOW_WORKER_PORT_2222_TCP_ADDR': '10.96.56.106', 'TENSORFLOW_WORKER_SERVICE_HOST': '10.96.56.106', 'TENSORFLOW_WORKER_PORT_2222_TCP_PROTO': 'tcp', 'KUBERNETES_SERVICE_PORT': '443', 'KUBERNETES_SERVICE_PORT_HTTPS': '443', 'KUBERNETES_PORT': 'tcp://10.96.0.1:443', 'KUBERNETES_PORT_443_TCP': 'tcp://10.96.0.1:443', 'TENSORFLOW_PS_PORT_2222_TCP': 'tcp://10.96.88.2:2222', 'TENSORFLOW_PS_PORT_2222_TCP_ADDR': '10.96.88.2', 'TENSORFLOW_WORKER_PORT_2222_TCP_PORT': '2222', 'KUBERNETES_PORT_443_TCP_ADDR': '10.96.0.1', 'TENSORFLOW_PS_SERVICE_HOST': '10.96.88.2', 'TENSORFLOW_PS_SERVICE_PORT': '2222', 'TENSORFLOW_PS_PORT': 'tcp://10.96.88.2:2222', 'TENSORFLOW_WORKER_PORT_2222_TCP': 'tcp://10.96.56.106:2222', 'HOME': '/root', 'ENABLE_RUNTIME_UPTIME_TELEMETRY': '1', 'TF2_BEHAVIOR': '1', 'TPU_ML_PLATFORM': 'Tensorflow', 'TPU_ML_PLATFORM_VERSION': '2.18.0'}) + This is the parameter server. + [2025-02-07 09:25:26.288107] Parameter server is running... + [2025-02-07 09:26:26.288219] Parameter server is running... + [2025-02-07 09:27:26.288358] Parameter server is running... + [2025-02-07 09:28:26.288519] Parameter server is running... + ```` + +3. 卸载 pod。 + + ````bash + kubectl delete -f tensorflow-distributed.yaml + ````