Golem CLI Plugins
Manage the available plugins
To manage the plugins available for installation, use the golem plugin
commands.
See the Plugins page for general information about Golem plugins.
List the available plugins
To list the available plugins, use the golem plugin list
command.
golem plugin list
Plugins can be installed to different scopes. By default the command lists the plugins installed in the global scope.
Use the following options to list plugins in other scopes:
--project <PROJECT_NAME>
: List plugins installed in the given project's scope--component <COMPONENT_NAME>
: List plugins installed in the given component's scope.
Get information about a registered plugin
To get more information about one of the available plugins, use the golem plugin get
command:
golem plugin get <PLUGIN_NAME> <PLUGIN_VERSION>
Register a new plugin
Plugins are identified by their name and version. To register a new plugin, use the golem plugin register
command:
golem plugin register <MANIFEST_PATH>
The parameter should point to a plugin manifest YAML describing all the properties of the plugin.
The plugin manifest
The plugin manifest consists of the following required global fields:
field name | description |
---|---|
name | The name of the plugin |
version | The version of the plugin |
description | A short description of the plugin |
icon | Path to the plugin's icon |
homepage | URL to the plugin's homepage |
The details of the plugin are specified in the specs
field, which is an object.
The specs.type
field specifies the type of the plugin. It can be one of the following:
ComponentTransformer
: The plugin is a component transformer plugin.OplogProcessor
: The plugin is an oplog processor plugin.App
: The plugin is an application plugin.Library
: The plugin is a library plugin.
The rest of the fields of the spec
object depend on the plugin type.
ComponentTransformer fields
field name | required | description |
---|---|---|
providedWitPackage | No | The path to the WIT file describing the extra provided interfaces the plugin adds |
jsonSchema | No | The path to the JSON schema file describing the plugin's configuration fields |
validateUrl | Yes | URL to the external component transformation service's validate endpoint |
transformUrl | Yes | URL to the external component transformation service's transform endpoint |
OplogProcessor fields
field name | required | description |
---|---|---|
component | Yes | The path to the oplog processor component (WASM) |
App fields
field name | required | description |
---|---|---|
component | Yes | The path to the application component (WASM) |
Library fields
field name | required | description |
---|---|---|
component | Yes | The path to the library component (WASM) |
Unregister a plugin
To unregister an available plugin, use the following command:
golem plugin unregister --plugin-name <PLUGIN-NAME> --version <PLUGIN-VERSION>
Manage a component's plugins using the app manifest
The recommended way to apply plugins to components is to define them in the app manifest.
The set of installed plugins can be set for each component in the app manifest under the plugins
key:
components:
my:example:
template: ts
plugins:
- name: component-transformer-1
version: v1
parameters:
x: 1
y: 2
The name
and version
fields of each installed component must match one of the available components installed to the system with the golem plugin
commands described above.
The parameters
field contains an arbitrary set of key-value pairs, their meaning depending on the actual plugin.
It is possible to install multiple plugins to a component, and the order they are going to be applied is going to match the order of the elements in the app manifest.
To apply the changes, use one of the golem app deploy
or the golem component deploy
commands.
Manage a component's plugins explicitly
There are CLI commands to explicitly install, uninstall or update a component's set of installed plugins. These commands may get deprecated in the future in favor of using the app manifest as described above.
A subset of the registered plugins can be installed for a component using te golem component plugin
commands.
Get the installed plugins
To get the list of installed plugins for a component, use the following command:
golem component plugin get <COMPONENT-NAME> <VERSION>
Install a plugin
To install a plugin for a component, use the following command:
golem component plugin install --plugin-name <PLUGIN_NAME> --plugin-version <PLUGIN_VERSION> --priority <PRIORITY> [COMPONENT_NAME]
Many plugins require per-installation configuration. These are key-value pairs that can be passed as arguments to the install
command as --param <KEY=VAL>
.
The priority is a number that determines the order in which plugins are applied.
Uninstall a plugin
To uninstall a plugin from a component, use the following command:
golem component plugin uninstall --installation-id <INSTALLATION_ID> [COMPONENT_NAME]
The installation ID is a unique identifier assigned every time a plugin is installed for a component. It is not enough to use the plugin name and version here, because one plugin can be installed multiple times (for exampel with different configuration) for a component.
Updating a plugin's priority or configuration
To update a plugin's priority or set of configuration parameters, use the following command:
golem component plugin update --installation-id <INSTALLATION_ID> --priority <NEW_PRIORITY> --param <KEY=VALUE> [...--param <KEY=VALUE>] [COMPONENT_NAME]
The installation ID is a unique identifier assigned every time a plugin is installed to a given component version, or its configuration has been changed.
Manage a project's plugins
In Golem Cloud it is also possible to install plugins for a project. Every component created in the project will get the installed plugins from the project.
Get the installed plugins
To get the list of installed plugins for a project, use the following command:
golem project plugin get [PROJECT_NAME]
The PROJECT_NAME
parameter can be either a project's name (if it is not ambigous), or it can be prefixed by the project's owner account's email address.
Install a plugin
To install a plugin for a project, use the following command:
golem project plugin install --plugin-name <PLUGIN_NAME> --plugin-version <PLUGIN_VERSION> --priority <PRIORITY> --param <KEY=VALUE> [...--param <KEY=VALUE>] [PROJECT_NAME]
Many plugins require per-installation configuration. These are key-value pairs that can be passed as arguments to the install
command as --param <KEY=VAL>
.
The priority is a number that determines the order in which plugins are applied.
Uninstall a plugin
To uninstall a plugin from a project, use the following command:
golem project plugin uninstall --installation-id <INSTALLATION_ID> [COMPONENT_NAME]
The installation ID is a unique identifier assigned every time a plugin is installed for a component. It is not enough to use the plugin name and version here, because one plugin can be installed multiple times (for exampel with different configuration) for a component.
### Updating a plugin's priority or configuration
To update a plugin's priority or set of configuration parameters, use the following command:
```shell copy
golem project plugin update --installation-id <INSTALLATION_ID> --priority <NEW_PRIORITY> --param <KEY=VALUE> [...--param <KEY=VALUE>] [PROJECT_NAME]
The installation ID is a unique identifier assigned every time a plugin is installed to a given component version, or its configuration has been changed.
Controlling oplog processor plugins per worker
If a component has oplog processors plugins installed, they can be dynamically activated or deactivated for each worker.
Activating a plugin on a worker
TODO
Deactivating a plugin on a worker
TODO