From 94baf4000bf7e68ad88e66036aa6def94ecee74f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=BB=B4=E5=9F=BA=E9=B1=BC?= Date: Fri, 30 May 2025 09:53:11 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=90=8C=E6=AD=A5=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/en/_toc.yaml | 14 ++++ docs/en/command.md | 58 ++++++++++++++++ docs/en/develop_guide.md | 146 +++++++++++++++++++++++++++++++++++++++ docs/en/feature.md | 19 +++++ docs/en/introduction.md | 21 ++++++ docs/en/usecase.md | 84 ++++++++++++++++++++++ docs/zh/Command.md | 57 +++++++++++++++ docs/zh/Introduction.md | 21 ++++++ docs/zh/UseCase.md | 84 ++++++++++++++++++++++ docs/zh/_toc.yaml | 14 ++++ docs/zh/develop_guide.md | 146 +++++++++++++++++++++++++++++++++++++++ docs/zh/feature.md | 19 +++++ 12 files changed, 683 insertions(+) create mode 100644 docs/en/_toc.yaml create mode 100644 docs/en/command.md create mode 100644 docs/en/develop_guide.md create mode 100644 docs/en/feature.md create mode 100644 docs/en/introduction.md create mode 100644 docs/en/usecase.md create mode 100644 docs/zh/Command.md create mode 100644 docs/zh/Introduction.md create mode 100644 docs/zh/UseCase.md create mode 100644 docs/zh/_toc.yaml create mode 100644 docs/zh/develop_guide.md create mode 100644 docs/zh/feature.md diff --git a/docs/en/_toc.yaml b/docs/en/_toc.yaml new file mode 100644 index 0000000..47f509c --- /dev/null +++ b/docs/en/_toc.yaml @@ -0,0 +1,14 @@ +label: oeDeploy User Guide +isManual: true +description: 'oeDeploy is a lightweight deployment tool designed for simplicity.' +sections: + - label: oeDeploy Introduction + href: ./introduction.md + - label: oedp Command Guide + 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 diff --git a/docs/en/command.md b/docs/en/command.md new file mode 100644 index 0000000..32519db --- /dev/null +++ b/docs/en/command.md @@ -0,0 +1,58 @@ +# oedp Command Reference + +## `oedp` + +| Option | Shortcut | Description | +| ----------- | -------- | -------------------- | +| `--version` | `-v` | Displays the version | + +## `oedp info` + +Displays project details (defaulting to the current directory). + +| Option | Shortcut | Mandatory | Description | +| ------------------ | -------- | --------- | -------------------------------- | +| `--project [path]` | `-p` | No | Specifies the project directory. | +| | | | | + +## `oedp run [action]` + +Executes a project action (defaulting to the current directory). `[action]` refers to a plugin method (query via `oedp info`). + +| Option | Shortcut | Mandatory | Description | +| ------------------ | -------- | --------- | -------------------------------- | +| `--project [path]` | `-p` | No | Specifies the project directory. | +| `--debug` (WIP) | `-d` | No | Runs in debug mode. | + +## `oedp list` + +List available plugins from sources + +| Option | Shortcut | Mandatory | Description | +| ---------------- | -------- | --------- | -------------------------------- | +| `--local [path]` | `-l` | No | Specifies the local source path. | + +## `oedp check [action]` (WIP) + +Validates project action requirements (defaulting to the current directory). + +| Option | Shortcut | Mandatory | Description | +| ------------------ | -------- | --------- | -------------------------------- | +| `--project [path]` | `-p` | No | Specifies the project directory. | + +## `oedp init [plugin]` (WIP) + +Initialize a plugin (`[plugin]` names available via `oedp list`) + +| Option | Shortcut | Mandatory | Description | +| ------------------ | -------- | --------- | --------------------------------------------------------------------------------- | +| `--project [path]` | `-p` | Yes | Specifies the initialization directory. | +| `--local [path]` | `-l` | No | Specifies the local source path. | +| `--force` | `-f` | No | Forces overwrite (deletes all files in the target directory before initializing). | + +## oedp Directory Structure + +- **/var/oedp/log/**: log files +- **/var/oedp/plugin/**: plugin cache +- **/usr/lib/oedp/src/**: source code +- **/etc/oedp/config/**: configuration files diff --git a/docs/en/develop_guide.md b/docs/en/develop_guide.md new file mode 100644 index 0000000..c721a24 --- /dev/null +++ b/docs/en/develop_guide.md @@ -0,0 +1,146 @@ +# oeDeploy Plugin Development Guide + +## 1. Introduction to oeDeploy Plugins + +oeDeploy plugins are components that provide automated deployment capabilities within the oeDeploy tool. They achieve automation by converting complex deployment processes into Ansible playbooks. A plugin may integrate multiple deployment actions (such as installation, uninstallation, and environment cleanup), each corresponding to one or more Ansible playbooks. All configurable parameters should be centralized to reduce both user learning costs and developer maintenance efforts. + +## 2. Plugin Directory Structure + +Adhere to the following directory structure: + +```text +{ plugin_name } +|-- main.yaml +|-- config.yaml +|-- doc/ +`-- workspace/ +``` + +| File/Directory | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | +| config.yaml | Contains host-related configurations (IP addresses, passwords, keys, and ports) and application deployment settings. Supports Jinja2 templating. | +| main.yaml | Primary configuration file for oedp to identify deployment workflows. | +| doc | Optional. Documentation directory for the plugin. | +| workspace | Deployment capability library for the application. | + +Naming constraints for `plugin_name`: + +- The deployed software name is `name`, and its version is `version`. +- `plugin_name` must follow one of these formats: + - `{name}-{version}` + - `{name}-{version}-xxx` +- **Example**: For a Kubernetes deployment plugin (version 1.31.1), valid names include `kubernetes-1.31.1`, `kubernetes-1.31.1-20240101`, and `kubernetes-1.31.1-offline-20240101`. + +## 3. main.yaml + +The **main.yaml** file records key plugin information including: `name`, `version`, `description`, and `action`. When users run the `oedp info` command, `oedp` reads and parses this file to display detailed information. + +The `action` field should be a dictionary (key-value map), where each key serves as an action name, and its corresponding value contains details about that action. + +Action details are structured as a dictionary. The `description` field provides explanatory text displayed during `oedp info` execution, while the `tasks` field lists the specific steps for the action. These steps are executed sequentially. + +For each step, specify the `playbook` path to execute. Optionally, a `vars` field can define variable file paths. All paths are relative to the `workspace` directory. Additionally, the `scope` field determines the target host group (defaulting to `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 + +The **config.yaml** file serves as the user configuration file for the plugin, primarily containing host group settings and other global configurations. It follows Ansible inventory file rules and can be directly passed as an inventory during Ansible playbook execution. + +```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" ] (forced cluster initialization) + service_cidr: 10.96.0.0/16 # Service subnet + pod_cidr: 10.244.0.0/16 # Pod IP address subnet + certs_expired: 3650 # Certificate expiration time + has_deployed_containerd: "false" # e.g. [ "true", "false" ] (whether containerd is available) +``` + +## 5. workspace + +The **workspace** directory contains the core deployment scripts. Its structure is flexible but must align with parameters defined in main.yaml and config.yaml. + +The **workspace** directory is treated as the root directory of the entire plugin. + +In this example, the **workspace** directory structure is: + +```text +workspace +|-- roles +| `-- ... +|-- init-k8s.yml +|-- delete-k8s.yml +|-- clean-k8s.yml +|-- variables.yml +`-- ... +``` + +## 6. Plugin Packaging + +To distribute a plugin, package it into `{plugin_name}.tar.gz` format. The compressed file name must match the internal directory name, and extraction should yield only one directory. For example: + +```text +kubernetes-1.31.1.tar.gz +`-- kubernetes-1.31.1 + |-- main.yaml + |-- config.yaml + `-- workspace/ +``` + +In this example, the following command packages the plugin: + +```bash +tar zcvf kubernetes-1.31.1.tar.gz kubernetes-1.31.1/ +``` diff --git a/docs/en/feature.md b/docs/en/feature.md new file mode 100644 index 0000000..7076f75 --- /dev/null +++ b/docs/en/feature.md @@ -0,0 +1,19 @@ +# 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 new file mode 100644 index 0000000..eada8bb --- /dev/null +++ b/docs/en/introduction.md @@ -0,0 +1,21 @@ +# Introduction + +oeDeploy is a lightweight software deployment tool designed to help developers quickly and efficiently set up various software environments, supporting both single-node and distributed scenarios. + +- **Universal scenario support**: Compatible with single-node and cluster environments. +- **One-click deployment for mainstream software**: Includes standardized deployment solutions for common software, with ongoing plugin additions to expand capabilities. +- **Flexible plugin management**: Features an extensible architecture, allowing developers to write custom plugins tailored to specific service needs. +- **Efficient development experience**: Supports the CLI and a GUI tool (work in progress), enabling developers to focus on workflow orchestration and core functionality with minimal coding. + +# Download + +- [oedp CLI tool (aarch64)](https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/aarch64/Packages/oedp-1.0.1-1.oe2503.aarch64.rpm) +- [oedp CLI tool (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 plugins](https://repo.oepkgs.net/openEuler/rpm/openEuler-24.03-LTS/contrib/oedp/plugins/) + +# Docs + +- [oedp Command Guide](./command.md) +- [oeDeploy Features](./feature.md) +- [oeDeploy Use Cases](./usecase.md) +- [oeDeploy Plugin Development Guide](./develop_guide.md) diff --git a/docs/en/usecase.md b/docs/en/usecase.md new file mode 100644 index 0000000..699cf93 --- /dev/null +++ b/docs/en/usecase.md @@ -0,0 +1,84 @@ +# oeDeploy Use Cases + +## Use Case 1: One-Click Kubernetes Deployment + +Prepare three virtual machines with 2 cores and 4 GB memory (with Layer-3 network connectivity) running openEuler 24.03 LTS SP1. The goal is to deploy a Kubernetes cluster consisting of 1 master and 2 worker nodes. + +On any node, download and install oeDeploy CLI tool `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 +``` + +Download and extract the Kubernetes plugin package (verify that the **kubernetes-1.31.1** directory appears). + +```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 +``` + +View plugin details. + +```shell +oedp info -p kubernetes-1.31.1 +``` + +Modify the project configuration file with actual node information. + +```shell +vim kubernetes-1.31.1/config.yaml +``` + +```yaml +all: + children: + masters: + hosts: + 172.27.76.114: # master node IP address + ansible_host: 172.27.76.114 # master node IP address + 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 address + ansible_host: 172.27.70.60 # worker node IP address + 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" +``` + +> Note: Ensure SSH connectivity between nodes (supports both password and key-based authentication). If using key-based authentication, omit password configuration. + +Execute automated deployment. + +```shell +oedp run install -p kubernetes-1.31.1 +``` + +To uninstall Kubernetes: + +```shell +oedp run delete -p kubernetes-1.31.1 +``` + +> The `-p` flag specifies the extracted plugin directory. When running `oedp` commands from within the **kubernetes-1.31.1** root directory, omit this parameter. 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/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 参数。 diff --git a/docs/zh/_toc.yaml b/docs/zh/_toc.yaml new file mode 100644 index 0000000..266fc54 --- /dev/null +++ b/docs/zh/_toc.yaml @@ -0,0 +1,14 @@ +label: oeDeploy 用户指南 +isManual: true +description: 'oeDeploy 是一款轻量、易用的软件部署工具' +sections: + - label: oeDeploy简介 + href: ./introduction.md + - label: 命令行工具oedp使用指南 + href: ./command.md + - label: oeDeploy工具特性 + href: ./feature.md + - label: oeDeploy应用案例 + href: ./usecase.md + - label: oeDeploy插件开发指南 + href: ./develop_guide.md 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 粒度的流程编排。 -- Gitee