About Kaholo Plugins
Kaholo plugins are JavaScript applications that if correctly arranged and packaged can be installed in the Kaholo platform to extend functionality. Kaholo plugins are most commonly used for a few different purposes:
- To provide integration with 3rd party systems, e.g. Amazon Web Services, Atlassian Jira, or GitHub
- To provide a CLI capability, e.g. Maven, Terraform, or Ansible
- To provide parameterized GUI access to basic tools, e.g. Bash Commands, FTP, Zip, or File Handling
Once installed, each plugin may appear one or more times in your Kaholo Pipelines as Actions, available in the Design page. The Action offers a collection of methods, each with configurable parameters. The methods are executed by the node.js Kaholo Agent when the pipeline is run. Plugins may also publish a result to “Final Result” on the Kaholo Execution Results Page, which is then accessible in the code layer. This allows the plugin to be orchestrated in the pipeline like any other Action, for example conditionally carrying out other actions based on the result.
There are over 100 plugins already available in the Kaholo Github Site. Instructions to install a plugin can be found in Install.md.
The Kaholo Template Plugin
A simple example plugin is the Kaholo Plugin Template.
This plugin is developed and maintained as a template repository for the development of other plugins. It is also a working Kaholo “Hello World” plugin. Because it has all the necessary parts in correct arrangement, it can be downloaded, installed, and used in Kaholo without modification.
Kaholo Plugin Components
A Kaholo Plugin consists of the following components:
Plugin Code
All plugin code should be written in JavaScript. You should export all of your external methods from the file specified as “main” in config.json
, e.g. app.js
.
The Kaholo Server expects all external methods that can be used by Kaholo users to be async. Each method declared in the config.json file needs to be in the following format:
async function apply(action, settings) { >> some code here << }
Both action and settings are always sent as an input, and are objects containing all metadata and params of the action, and all of the plugin’s settings. You can reach each parameter or setting using action.params.paramName
or settings.settingName
.
Autocomplete Parameters
In config.json, an autocomplete method uses three method-level metadata to identify itself as an autocomplete function and declare which function in autocomplete.js should be used, for example:
"type": "autocomplete", "autocompleteType": "function", "functionName": "listRegions",
The fuction named in functionName must be exported in the file where it is coded.
function listRegions(query = "") { >> some code here << return filterItemsByQuery(autocompleteList, query); } module.exports = {listRegions};
Autocomplete parameters store their value in the format of an object with two fields:
- id – A unique identifier not shown to the user but accessible from the plugin code.
- value – The text shown to the user in the Kaholo UI as a drop-down menu item. This is also accessible from the plugin code.
Resolving Dependencies (npm packages)
Kaholo plugins make use of npm packages to resolve and install dependencies. This is managed using the npm configuration file package.json
as described on the npm Docs website. For example the package.json
for the CSV plugin shows it depends on Kaholo’s plugin library, @kaholo/plugin-library
, and lodash
.
Kaholo CSV plugin’s package.json
{ "name": "kaholo-plugin-csv", "description": "CSV plugin for Kaholo", "main": "app.js", "scripts": { "lint": "npx eslint .", "lint:fix": "npx eslint . --fix" }, "author": "Kaholo team (Roy Talyosef)", "license": "ISC", "devDependencies": { "eslint": "8.16.0", "eslint-config-airbnb-base": "15.0.0", "eslint-plugin-import": "2.26.0" }, "dependencies": { "@kaholo/plugin-library": "^1.3.0", "lodash": "4.17.21" } }
Kaholo Plugin Library
There is a library of commonly needed plugin functions available in the Kaholo Plugin Library. This is regularly published as an npm package. To use these functions simply list the plugin library as a dependency in package.json and then reference the library in code, for example in app.js:
const kaholoPluginLibrary = require("@kaholo/plugin-library");
Coming Soon – Kaholo Plugin Library documentation.
Kaholo Plugin best practices
Here are a few guidelines to make Kaholo plugins that are useful to wide audiences, easier to maintain, and less likely to be broken by future releases of Kaholo.
- Ideally plugins work on both Linux and Windows Kaholo agents.
- Plugins should be developed in the context of real-world pipelines, i.e. with all commonly used parameters and methods – not only those needed for a specific use case.
- Order parameters with required ones first, then commonly used ones, and finally rarely used parameters last. This improves usability.
- Set parameter default values where helpful (“default” in config.json).
- Mark parameters that are absolutely required for a method to work as required (
"required": true
in config.json). Booleans needn’t be required because even left unconfigured and with no default they already have a valid value (false
). - Consider using the Kaholo Accounts feature (“auth” in config.json) to consolidate parameters when:
- The same parameter(s) are required for most methods of the plugin.
- The parameters are likely to require the same values for every Action/Pipeline.
- Configuring the parameters on an Action-by-Action basis is repetetive and tedius.
- Parameters involve authorization – names, passwords, tokens, etc.
- Two or more parameters are related such that changing any one parameter renders the others invalid – for example if username is changed, password most likely must also change.
- Parameters in the Account may be omitted at the Action level without negatively impacting use cases.
- Consider using the Kaholo Plugin Settings feature (“settings” in config.json) to allow parameters to have defaut values when:
- Having a default value automatically populated at the Action level would be decidedly convenient for the end user(s), but may at times also need to be overridden by user input.
- The parameter seems appropriate for the Kaholo Accounts feature but for any reason doesn’t quite work there.
Kaholo Plugins that run in Docker
A useful strategy for Kaholo plugins is to run methods within a Docker container and then to destroy the container once the method completes. This is such a common design that it has been incorporated into the Kaholo Plugin Library for easy re-use. Any plugin that requires some CLI, tool, or other software package (beyond npm dependencies) to be installed in order to work is a good candidate for this design. Since the Kaholo agent is typically deployed already as a docker/kubernetes container, this does mean running a docker container within another container. This takes only a second or two to complete, assuming the docker image is already available in the Kaholo agent’s Docker cache.
This serves several purposes:
- Runs each time within a fresh instance of a purpose-built container for consistent and reliable outcomes regardless of the state or version of the Kaholo agent node
- Allows easier management of Kaholo agents because myriad software components needn’t be installed directly on the agent – only Docker
- Lowers disk space footprint of agents, depending on how many docker images are ultimately cached for use
- Simplifies optionally running multiple version of a dependent software package without conflicts
- Allows for easy upgrade to latest version of docker image
- When plugin method completes, sensitive materials such as caches and credentials used by the method may be destroyed along with the docker container for improved security
However there are a few caveats as well:
- The first time a Kaholo Plugin using docker is run, there is a significant delay as the docker image is downloaded to the agent’s docker cache,
/var/lib/docker
. - Files and configuration on the Kaholo Agent are not available within the docker image unless explicitly mounted as a docker volume.
- Output of methods written to disk get destroyed unless written to mounted parts of the Kaholo Agent’s filesystem.
See Also – Development of Kaholo Plugins using Docker