In last week's release, we announced the addition of our plugin installer feature to the mkr command. This feature makes it easier for users to install their own third party plugins in the system.
Up until now, in order to install your own plugin on the system, you either had to arrange a method of installation by yourself or submit source code to the following central repository.
Using this new feature, it is now possible to install plugins created in your own GitHub repository using the mkr command. This allows the creator of the plugin the ability to continually perform maintenance.
Additionally, when installing a plugin by submitting code to the central repository, developing with Golang was required. However, with this feature, it’s now possible to develop using the language of your choice.
- How to use
- Mackerel plugin package format
- Uploading the Mackerel plugin package in GitHub Releases
- The official plugin registry
- Pull Requests to the existing central repository
- More detailed documentation
- Future expansion
How to use
Using the mkr plugin install command, you can install the contents of the specified Mackerel plugin package on your system.
% sudo mkr plugin install <owner>/<repo>[@<release_tag>]
By specifying the Github owner name, repository name, as well as the tag name for Github Releases, the Mackerel plugin package is obtained from GitHub Releases and installed.
Mackerel plugin package format
The Mackerel plugin package is a simple zip file. There should be an executable file starting with mackerel-plugin- or check- stored in the archive. As long as it’s an executable file, any language can be used.
The mkr plugin install command regards these executable files as Mackerel plugins and places them in the specific directory. By default, they will be located under /opt/mackerel-agent/plugins/bin.
Uploading the Mackerel plugin package in GitHub Releases
% sudo mkr plugin install <owner>/<repo>[@<release_tag>]
When the above command is executed, mkr attempts to acquire the Mackerel plugin package of the following URL.
https://github.com/<owner>/<repo>/releases/download/<release_tag>/<repo>_<GOOS>_<GOARCH>.zip
If the Mackerel plugin package is placed in GitHub Releases’ <release_tag> according to the naming convention <repo>_<GOOS>_<GOARCH>.zip, you’ll be able to download the Mackerel plugin package from the above URL. Take a look at the following with mackerel-plugin-sample used as an example.
https://github.com/mackerelio/mackerel-plugin-sample/releases
The official plugin registry
https://github.com/mackerelio/plugin-registry
Registering useful plugins in the official plugin registry makes it easier for other users to find plugins. Plugins registered in the plugin registry can be installed using the format mkr plugin install <plugin_name>.
Registration is done by sending a Pull Request to the plugin registry’s Github repository. For the contents of the Pull Request, simply create a file called <plugin_name>.json under the plugins/ directory. The JSON file format is as follows.
- Write the location of the plugin using the format
<github owner>/<github repo>in the field labeled “source”- The plugin of the specified repository needs to be installable with
mkr plugin install
- The plugin of the specified repository needs to be installable with
- Write a brief description of the plugin in the description field
- (Example) https://github.com/mackerelio/plugin-registry/blob/master/plugins/mackerel-plugin-sample.json
You can see a list of the plugins that are currently registered at https://github.com/mackerelio/plugin-registry/tree/master/plugins.
Understand that contribution authority and licensing for the plugins registered in the official plugin registry correspond with the referent repository.
Please do not hesitate to send us a Pull Request.
On a separate note, since package management registries like this often have cool names like CPAN, RubyGems, homebrew, we considered doing the same for our official plugin registry. Hatena CTO 
id:motemen even came up with the catchy name tsukiji, but it was ultimately dismissed for various reasons, and we settled with the safe name of plugin-registry.
Pull Requests to the existing central repository
Up until now, it was acceptable to register a new plugin with the above-mentioned central repository, but as a general rule from now on, adding new plugins this way will no longer be accepted. Adding a feature to an existing plugin or fixing a bug is of course welcome.
If you create a new plugin, you should create your own plugin repository on GitHub and register it in the official plugin registry.
If you would like to incorporate a registered plugin into Mackerel’s official plugin package distributed by rpm or deb, please contact us through a separate issue etc. Conversely, the Mackerel development team might reach out to plugin creators to ask for permission to incorporate registered packages into the official plugin package. In such a case, we would appreciate your cooperation.
More detailed documentation
For more details on how to install the third party plugin installer described in this entry or how to create a Mackerel plugin package, please refer to the following help pages.
Future expansion
We are considering the following expansions in the future.
- A flexible template-like naming configuration, since naming for the Mackerel plugin package is currently defined strictly as
<repo>_<GOOS>_<GOARCH>.zip - An update feature for installed plugins
- Metadata plugin support
Of course, we welcome additional proposals and Pull Requests for this feature.
First, create your own plugin, then send a Pull Request to the official plugin registry.
