From a6c8bb9986c54312a7f114a7bfd633864b80c6cf Mon Sep 17 00:00:00 2001 From: Evawudonger Date: Tue, 10 Jun 2025 14:28:05 +0800 Subject: [PATCH 1/3] =?UTF-8?q?=E5=88=A0=E9=99=A4=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/{zh => }/Introduction.md | 0 docs/{zh => }/UseCase.md | 0 docs/{zh/Command.md => command.md} | 0 docs/{zh => }/develop_guide.md | 0 docs/{zh => }/feature.md | 0 5 files changed, 0 insertions(+), 0 deletions(-) rename docs/{zh => }/Introduction.md (100%) rename docs/{zh => }/UseCase.md (100%) rename docs/{zh/Command.md => command.md} (100%) rename docs/{zh => }/develop_guide.md (100%) rename docs/{zh => }/feature.md (100%) diff --git a/docs/zh/Introduction.md b/docs/Introduction.md similarity index 100% rename from docs/zh/Introduction.md rename to docs/Introduction.md diff --git a/docs/zh/UseCase.md b/docs/UseCase.md similarity index 100% rename from docs/zh/UseCase.md rename to docs/UseCase.md diff --git a/docs/zh/Command.md b/docs/command.md similarity index 100% rename from docs/zh/Command.md rename to docs/command.md diff --git a/docs/zh/develop_guide.md b/docs/develop_guide.md similarity index 100% rename from docs/zh/develop_guide.md rename to docs/develop_guide.md diff --git a/docs/zh/feature.md b/docs/feature.md similarity index 100% rename from docs/zh/feature.md rename to docs/feature.md -- Gitee From 185b8c41f1886c05f9bfe756bfaf49103db4495d Mon Sep 17 00:00:00 2001 From: Evawudonger Date: Tue, 10 Jun 2025 14:29:54 +0800 Subject: [PATCH 2/3] =?UTF-8?q?=E6=96=87=E6=A1=A3=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/zh/command.md | 57 +++++++++++++++ docs/zh/develop_guide.md | 146 +++++++++++++++++++++++++++++++++++++++ docs/zh/feature.md | 19 +++++ docs/zh/introduction.md | 21 ++++++ docs/zh/usecase.md | 84 ++++++++++++++++++++++ 5 files changed, 327 insertions(+) create mode 100644 docs/zh/command.md create mode 100644 docs/zh/develop_guide.md create mode 100644 docs/zh/feature.md create mode 100644 docs/zh/introduction.md create mode 100644 docs/zh/usecase.md diff --git a/docs/zh/command.md b/docs/zh/command.md new file mode 100644 index 0000000..47c9190 --- /dev/null +++ b/docs/zh/command.md @@ -0,0 +1,57 @@ +# 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/develop_guide.md b/docs/zh/develop_guide.md new file mode 100644 index 0000000..55f8798 --- /dev/null +++ b/docs/zh/develop_guide.md @@ -0,0 +1,146 @@ +# 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/feature.md b/docs/zh/feature.md new file mode 100644 index 0000000..4c269cd --- /dev/null +++ b/docs/zh/feature.md @@ -0,0 +1,19 @@ +# 开发中特性 + +- Debug 模式，支持执行指定的 task。 +- 部署插件初始化功能。 +- 部署插件检查模块。 +- 插件源管理模块，根据插件名称自动下载、解压插件，插件源可配置。 +- oeDeploy Web页面，支持自定义部署任务、节点信息管理、部署流程可视化。 + +# 已规划特性 + +- 部署插件商店，页面展示插件列表，支持页面创建部署任务。 +- 兼容 Helm 部署项目。 + +# 已发布特性 + +## v1.0.1 + +- 使用 ansible 作为分布式节点的命令下发平台。 +- 支持 playbook 粒度的流程编排。 diff --git a/docs/zh/introduction.md b/docs/zh/introduction.md new file mode 100644 index 0000000..d2e60b8 --- /dev/null +++ b/docs/zh/introduction.md @@ -0,0 +1,21 @@ +# 简介 / Introduction + +oeDeploy 是一款轻量级的软件部署工具，旨在帮助开发者快速、高效地完成各类软件环境部署，对单节点与分布式场景均可适配。 + +- **通用的全场景支持**：同时支持单节点与集群环境等多种场景。 +- **主流软件一键部署**：内置常见软件的标准化部署方案，开发团队也将持续引入其它主流插件，不断提升 oeDeploy 的部署能力。 +- **灵活的插件化管理**：oeDeploy 提供可扩展架构，支持开发者基于实际需求，使用自定义编写的定制插件，精准匹配自身业务特性。 +- **高效开发体验**：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) +- [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) diff --git a/docs/zh/usecase.md b/docs/zh/usecase.md new file mode 100644 index 0000000..9fd8827 --- /dev/null +++ b/docs/zh/usecase.md @@ -0,0 +1,84 @@ +# 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 参数。 -- Gitee From d3a4454eef3652d4e08e009b0c5485867ddfc6e4 Mon Sep 17 00:00:00 2001 From: Evawudonger Date: Tue, 10 Jun 2025 14:43:34 +0800 Subject: [PATCH 3/3] =?UTF-8?q?=E6=96=87=E6=A1=A3=E8=A7=84=E8=8C=83?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/Introduction.md | 21 ------ docs/UseCase.md | 84 ---------------------- docs/command.md | 57 --------------- docs/develop_guide.md | 146 --------------------------------------- docs/en/_toc.yaml | 2 +- docs/feature.md | 19 ----- docs/zh/_toc.yaml | 6 +- docs/zh/develop_guide.md | 2 +- 8 files changed, 5 insertions(+), 332 deletions(-) delete mode 100644 docs/Introduction.md delete mode 100644 docs/UseCase.md delete mode 100644 docs/command.md delete mode 100644 docs/develop_guide.md delete mode 100644 docs/feature.md diff --git a/docs/Introduction.md b/docs/Introduction.md deleted file mode 100644 index d2e60b8..0000000 --- a/docs/Introduction.md +++ /dev/null @@ -1,21 +0,0 @@ -# 简介 / Introduction - -oeDeploy 是一款轻量级的软件部署工具，旨在帮助开发者快速、高效地完成各类软件环境部署，对单节点与分布式场景均可适配。 - -- **通用的全场景支持**：同时支持单节点与集群环境等多种场景。 -- **主流软件一键部署**：内置常见软件的标准化部署方案，开发团队也将持续引入其它主流插件，不断提升 oeDeploy 的部署能力。 -- **灵活的插件化管理**：oeDeploy 提供可扩展架构，支持开发者基于实际需求，使用自定义编写的定制插件，精准匹配自身业务特性。 -- **高效开发体验**：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) -- [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) diff --git a/docs/UseCase.md b/docs/UseCase.md deleted file mode 100644 index 9fd8827..0000000 --- a/docs/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/command.md b/docs/command.md deleted file mode 100644 index 47c9190..0000000 --- a/docs/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/develop_guide.md b/docs/develop_guide.md deleted file mode 100644 index 55f8798..0000000 --- a/docs/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/en/_toc.yaml b/docs/en/_toc.yaml index 47f509c..7c0b41a 100644 --- a/docs/en/_toc.yaml +++ b/docs/en/_toc.yaml @@ -1,6 +1,6 @@ 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 diff --git a/docs/feature.md b/docs/feature.md deleted file mode 100644 index 4c269cd..0000000 --- a/docs/feature.md +++ /dev/null @@ -1,19 +0,0 @@ -# 开发中特性 - -- Debug 模式，支持执行指定的 task。 -- 部署插件初始化功能。 -- 部署插件检查模块。 -- 插件源管理模块，根据插件名称自动下载、解压插件，插件源可配置。 -- oeDeploy Web页面，支持自定义部署任务、节点信息管理、部署流程可视化。 - -# 已规划特性 - -- 部署插件商店，页面展示插件列表，支持页面创建部署任务。 -- 兼容 Helm 部署项目。 - -# 已发布特性 - -## v1.0.1 - -- 使用 ansible 作为分布式节点的命令下发平台。 -- 支持 playbook 粒度的流程编排。 diff --git a/docs/zh/_toc.yaml b/docs/zh/_toc.yaml index 266fc54..fb4f909 100644 --- a/docs/zh/_toc.yaml +++ b/docs/zh/_toc.yaml @@ -1,14 +1,14 @@ 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插件开发指南 + - label: oeDeploy插件开发 href: ./develop_guide.md diff --git a/docs/zh/develop_guide.md b/docs/zh/develop_guide.md index 55f8798..4f89b61 100644 --- a/docs/zh/develop_guide.md +++ b/docs/zh/develop_guide.md @@ -1,4 +1,4 @@ -# oeDeploy 插件开发指南 +# oeDeploy 插件开发 ## 1 oeDeploy 插件介绍 -- Gitee