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:
{ 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 isversion
. 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
, andkubernetes-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
)
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.
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:
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:
kubernetes-1.31.1.tar.gz
`-- kubernetes-1.31.1
|-- main.yaml
|-- config.yaml
`-- workspace/
In this example, the following command packages the plugin:
tar zcvf kubernetes-1.31.1.tar.gz kubernetes-1.31.1/
Licensed under the MulanPSL2