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/

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)

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/