Plugin Manager (PM)

Plugin Manager (PM) provides a way for components to define actions and validations via plugins. PM provides dependency management similar to Red Hat systemd.

Table of Contents

Plugin Manager (PM)

Plugins

Plugin Manager basically uses config that are known as Plugins to inform about what it does, it’s dependencies, and the action to be performed.

Description: about the action i.e., what the plugin does.
ExecStart: refers to action to be performed i.e., binary to be executed.
- Note: ExecStart should have absolute path to the binary, so that PM knows where the binary is located. In case, binaries are located in the same plugin directory, then you could specify path using the PM's plugins library path that would be updated in the environment variable i.e., PM_LIBRARY.
- Example: ExecStart=/bin/sh ${PM_LIBRARY}/<component>/example.sh.
RequiredBy: informs that the current plugin must be run before the specified plugins. In other words, the specified plugins must be run after the current plugin.
Requires: informs that the current plugin must be run after the specified plugins. In other words, the specified plugins must be run before the current plugin.

All plugins must be installed (extracted) into ${PM_LIBRARY}/<component-plugin-dir> folder. If you would like to customize this path, you could either

Create/update the config file to look for a different plugins library path, and set the PM_CONF_FILE to the config file.
Specify the plugins library path i.e., -library while calling PM.

The PM_LIBRARY would be set to the library location specified in the PM configuration file. The configuration file currently has library as /system/upgrade/repository/plugins/, but could change in future. And hence one must use the environment variable ${PM_LIBRARY} to access the plugins library path.

Plugin Types and File Extensions

The type of a plugin is identified basically based on plugin file's extension, and it's up to the consumer of the plugin manager to define the plugin types for their actions.

Example: To perform pre-upgrade tasks by various services/components/features in the upgrade workflow, one could define .preupgrade plugin type, and have all these plugins called through plugin manager by specifying -type as preupgrade.

Plugin Dependencies

Plugin Manager allows specifying dependencies between plugins. Basically it allows a plugin to be run before or after certain plugins are run. The below sample show that "d" plugins requires “b” and “c” plugins to be run first before it runs, and “A” must be run after "D".

$ cat <plugins_library>/A/a.prereboot
Description=Applying “A” settings
ExecStart=<path_to_binary>

$ cat <plugins_library>/D/d.prereboot
Description=Applying “D” settings
RequiredBy=A/a.prereboot
Requires=B/b.prereboot C/c.prereboot
ExecStart=${PM_LIBRARY}/D/example.sh

Viewing Plugin and its dependencies

The plugins and its dependencies can be viewed visually in a svg image by running the list command of Plugin Manager.

The PM list command syntax / usage is as shown below:

pm list -type <PluginType>
  [-library=<PluginsLibraryPath>]
  [-log-dir=<LogDirectory>]
  [-log-file=<NameOfLogFile>]

where

type: Indicates the plugin type.
library: Indicates the location of plugins library. Overrides value present in PM configuration.
log-dir: Indicates the log directory path. Overrides value present in PM configuration.
log-file: Indicates the name of the log file. Overrides value present in PM configuration.

Example: Plugin Manager (PM) `list`

$ $GOBIN/pm list -type=preupgrade
Log: pm.2020-01-13T15:56:46.6817949-08:00.log
The list of plugins are mapped in .//preupgrade.2020-01-13T15:56:46.725348-08:00.svg

Configuring Plugin Manager

Plugin Manager can be configured to look for plugins at a specific location, and to write logs to a specific file by specifying those details in the Plugin Manager configuration file /etc/asum/pm.config.yml.

Instead of updating the default config file, one can choose to provide his/her own custom config file. This can be done by setting the environment variable PM_CONF_FILE to the custom config file path as shown below.

export PM_CONF_FILE=sample/pm.config.yaml

The config file could be either a yaml or a json file. Below is a sample yaml configuration file.

$ cat pm.config.yaml
---
PluginManager:
  # `library` is the location where plugin directories containing plugins are expected to be present
  library: "./sample/library"
  log dir: "./"
  # `log file` indicates the name of the log file.
  #   The timestamp and '.log' extension would be appended to this name.
  #   I.e., The format of the log file generated would be: "<log file>.<timestamp>.log"
  #   Example: The below value results in following log file: pm.2020-01-13T16:11:58.6006565-08:00.log
  log file: "pm"
...

Running Plugins

Plugin Manager tries to executes all available plugins of a certain type as mentioned by the -type argument. The result of the execution of a plugin (i.e., result of execution of binary which is specified in ExecStart) is marked as Succeeded or Failed to mean success or failure respectively. The PM checks for exit status of the binary to infer success or failure. If the binary exits with 0, then plugin execution is marked as Succeeded, while any non zero exit value is considered as Failed. In case of non zero exit value of plugins, the PM exits with 1.

The PM run command syntax / usage is as shown below:

pm run -type <PluginType>
  [-library=<PluginsLibraryPath>]
  [-sequential[={true|1|false|0}]]
  [-log-dir=<LogDirectory>]
  [-log-file=<NameOfLogFile>]
  [-output={json|yaml}]
  [-output-file=<NameOfOutputFile>]

where

type: Indicates the plugin type.
library: Indicates the location of plugins library. Overrides value present in PM configuration.
-sequential: Indicates PM to execute only one plugin at a time regardless of how many plugins' dependencies are met. Default: Disabled. To enable, specify -sequential=true or just -sequential while running PM.
log-dir: Indicates the log directory path. Overrides value present in PM configuration.
log-file: Indicates the name of the log file. Overrides value present in PM configuration.
output: Indicates the format to write the plugins run results. Supported formats: "json", "yaml".
output-file: Indicates the name of the output file. Note Specified in conjunction with output. If output format is specified, and output-file is not specified, then result will be displayed on console.

Example: Plugin Manager (PM) `run`

$ $GOBIN/pm run -type=prereboot
Log: pm.2019-07-12T15:23:07.3494206-07:00.log

Applying "B" settings: Starting

Applying "C" settings: Starting
Applying "C" settings: Succeeded
Applying "B" settings: Succeeded

Applying "D" settings: Starting
Applying "D" settings: Succeeded

Applying "A" settings: Starting
Applying "A" settings: Succeeded
Running prereboot plugins: Succeeded
$

Example: Plugin Manager (PM) with `sequential` flag

The sequential option informs Plugin Manager to execute one plugin at a time. By default, this is disabled, and multiple plugins whose dependencies are met would be run in parallel.

$ $GOBIN/pm run -type=prereboot -sequential
Log: pm.2019-07-12T15:36:33.7415514-07:00.log

Applying "B" settings: Starting
Applying "B" settings: Succeeded

Applying "C" settings: Starting
Applying "C" settings: Succeeded

Applying "D" settings: Starting
Applying "D" settings: Succeeded

Applying "A" settings: Starting
Applying "A" settings: Succeeded
Running prereboot plugins: Succeeded
$

Example: Overriding Plugin Manager (PM) configuration - `library`, `log-dir` and `log-file`

To override the values in the PM configuration, specify one or many of the following optional arguments: library, log-dir and log-file

$ $GOBIN/pm run -type postreboot -library=sample/library/ -log-dir=testlogs/ -log-file=test.log
Log: pm.2019-07-12T15:39:08.1145946-07:00.log
Log: testlogs/test.2019-07-12T15:39:08.1209416-07:00.log

Validating "A's" configuration: Starting
Validating "A's" configuration: Succeeded
Running postreboot plugins: Succeeded
$ ls testlogs/
test.2019-07-12T15:39:08.1209416-07:00.log
$

Example: Writing plugins result to a `output-file` in `output-format` {json, yaml} format

$ $GOBIN/pm run -type preupgrade -output-format=json -output-file=a.json -library ./sample/library/
Log: /log/asum/pm.2021-01-29T17:46:57.6904918-08:00.log

Checking for "D" settings...: Starting
Checking for "D" settings...: Succeeded

Checking for "A" settings: Starting
Checking for "A" settings: Succeeded
Running preupgrade plugins: Succeeded
$

$ cat a.json
{
  "Type": "preupgrade",
  "Plugins": [
    {
      "Description": "Checking for \"D\" settings...",
      "FileName": "D/d.preupgrade",
      "ExecStart": "$PM_LIBRARY/D/preupgrade.sh",
      "RequiredBy": [
        "A/a.preupgrade"
      ],
      "Requires": null,
      "Status": "Succeeded",
      "StdOutErr": "Running preupgrade.sh (path: sample/library//D/preupgrade.sh) with status(0)...\nDisplaying Plugin Manager (PM) Config file path: \nDone(0)!\n"
    },
    {
      "Description": "Checking for \"A\" settings",
      "FileName": "A/a.preupgrade",
      "ExecStart": "/bin/echo \"Checking A...\"",
      "RequiredBy": null,
      "Requires": [
        "D/d.preupgrade"
      ],
      "Status": "Succeeded",
      "StdOutErr": "\"Checking A...\"\n"
    }
  ],
  "Status": "Succeeded",
  "StdOutErr": ""
}$

$ $GOBIN/pm run -type preupgrade -output-format=yaml -output-file=a.yaml -library ./sample/library/
Log: /log/asum/pm.2021-01-29T17:53:15.8128937-08:00.log

Checking for "D" settings...: Starting
Checking for "D" settings...: Failed
Running preupgrade plugins: Failed
$

$ cat a.yaml 
type: preupgrade
plugins:
- description: Checking for "D" settings...
  filename: D/d.preupgrade
  execstart: $PM_LIBRARY/D/preupgrade.sh
  requiredby:
  - A/a.preupgrade
  requires: []
  status: Failed
  stdouterr: "Running preupgrade.sh (path: sample/library//D/preupgrade.sh) with
    status(1)...\nDisplaying Plugin Manager (PM) Config file path: \nFail(1)\n"
status: Failed
stdouterr: 'Running preupgrade plugins: Failed'
$

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github/workflows		.github/workflows
cmd/pm		cmd/pm
config		config
sample		sample
tools		tools
utils		utils
vendor		vendor
.gitignore		.gitignore
LICENSE		LICENSE
Makefile		Makefile
Makefile.conf		Makefile.conf
README.md		README.md
go.mod		go.mod
go.sum		go.sum
graph.go		graph.go
graph_test.go		graph_test.go
plugin.go		plugin.go
plugin_test.go		plugin_test.go

License

VeritasOS/plugin-manager

Folders and files

Latest commit

History

Repository files navigation

Plugin Manager (PM)

Plugins

Plugin Types and File Extensions

Plugin Dependencies

Viewing Plugin and its dependencies

Example: Plugin Manager (PM) list

Configuring Plugin Manager

Running Plugins

Example: Plugin Manager (PM) run

Example: Plugin Manager (PM) with sequential flag

Example: Overriding Plugin Manager (PM) configuration - library, log-dir and log-file

Example: Writing plugins result to a output-file in output-format {json, yaml} format

About

Resources

License

Stars

Watchers

Forks

Languages

Example: Plugin Manager (PM) `list`

Example: Plugin Manager (PM) `run`

Example: Plugin Manager (PM) with `sequential` flag

Example: Overriding Plugin Manager (PM) configuration - `library`, `log-dir` and `log-file`

Example: Writing plugins result to a `output-file` in `output-format` {json, yaml} format