Creating plugins supported with mkr plugin install

When creating a Mackerel plugin, if the plugin installer specifications are met, you can easily install the plugin using the mkr plugin install command. This document explains how to do that and how to register your created plugin in the official registry.

For details on how to install plugins using mkr, see Using mkr plugin install. For details on how to implement plugins using Go, see Using go-mackerel-plugin to create a custom metric plugin.

Required specifications

In order to install with the mkr plugin install command, the Github repository of the created plugin must meet the following specifications.

  • Release tags for each version in Github Releases of the plugin repository must be removed and an archive for each OS/Arch must be uploaded according to the naming convention
  • The archive filename must follow the (REPOSITORY_NAME)_(GOOS)_(GOARCH).zip naming convention

Although not required, it is recommended that you also follow the specifications listed below.

  • One repository should provide one execution file for the plugin
  • The repository name and the execution file name should match
  • The naming convention vx.y.z should be followed for release tags uploaded in Github Releases (Example: v1.2.3)
  • The README.md and LICENSE file should be included in the archive

Additionally, as long as the required specifications are met, even plugins not implemented using Go can be installed using the mkr plugin install command.

Refer to mackerelio/mackerel-plugin-sample for samples that meet the recommended specifications.

Configuring the plugin to meet specifications

So now let’s try configuring your plugin to correspond with the recommended specifications. We’ll use the sample repository mackerelio/mackerel-plugin-sample as an example.

In order to meet the specifications of the plugin installer, you’ll need to do three things: create an executable file, create a release archive, and make a release in Github Releases. Since the mackerel-plugin-sample is implemented with Go, we’ll create the executable file and release archive with goxz and make the release in Github Releases with ghr. For this example, we’ll be using the tools goxz + ghr , but as long as the specifications are met, the type of tool is not significant.

Install goxz and ghr

First, let’s install the tools, goxz and ghr. Go execution environment is necessary for installation.

$ go install github.com/Songmu/goxz/cmd/goxz@latest
$ go install github.com/tcnksm/ghr@latest

Create an executable file and release archive

Next, let’s create an executable file and release archive using goxz.

In order to meet the spectifications of the plugins installer, execute goxz using following options. Then a release archive is created below the specified directory.

$ goxz -d dist/v0.0.1 -z -os windows,darwin,linux -arch amd64,386
$ ls -1 dist/v0.0.1
mackerel-plugin-sample_darwin_386.zip
mackerel-plugin-sample_darwin_amd64.zip
mackerel-plugin-sample_linux_386.zip
mackerel-plugin-sample_linux_amd64.zip
mackerel-plugin-sample_windows_386.zip
mackerel-plugin-sample_windows_amd64.zip
$ unzip dist/v0.0.1/mackerel-plugin-sample_linux_amd64.zip
$ ls -1 mackerel-plugin-sample_linux_amd64
CHANGELOG.md
LICENSE
README.md
mackerel-plugin-sample

Using windows/darwin/linux OS amd64/386 Architecture, we create an executable file that corresponds with a total of six platforms. You can adjust which platforms to support by the -os and -arch command line options of goxz.

Please refer to official goxz documentation for configuration details.

Release in Github Releases

Now that we’ve created the release archive by goxz, let’s release it in Github Releases. This can be done very easily using ghr. For example, if you want to release to mackerelio/mackerel-plugin-sample with the release tag v.0.0.1, just execute the following command.

$ GITHUB_TOKEN=... ghr -u mackerelio -r mackerel-plugin-sample v0.0.1 dist/v0.0.1

The following will be displayed in the Github Releases page if successful.

https://github.com/mackerelio/mackerel-plugin-sample/releases

f:id:mackerelio:20171025162942p:plain

Creating a release utility

With the configurations made up until this point, we’ve met the recommended specifications of the plugin installer and made a release in Github Releases. However, performing all of the above-mentioned work can be tedious and it may be more convenient to create a release utility to do the work all at once.

https://github.com/mackerelio/mackerel-plugin-sample/blob/master/script/release

#!/bin/sh
set -e
latest_tag=$(git describe --abbrev=0 --tags)
goxz -d dist/$latest_tag -z -os windows,darwin,linux -arch amd64,386
ghr -u mackerelio -r mackerel-plugin-sample $latest_tag dist/$latest_tag

By using this, you can make a release with just the following command.

$ git tag v0.0.1
$ GITHUB_TOKEN=... script/release

Test mkr plugin install

After you complete the release, let’s check and see if you can install with mkr plugin install.

$ sudo mkr plugin install mackerelio/mackerel-plugin-sample@v0.0.1
           Downloading https://github.com/mackerelio/mackerel-plugin-sample/releases/download/v0.0.1/mackerel-plugin-sample_darwin_amd64.zip
           Installing /opt/mackerel-agent/plugins/bin/mackerel-plugin-sample
           Successfully installed mackerelio/mackerel-plugin-sample@v0.0.1
$ /opt/mackerel-agent/plugins/bin/mackerel-plugin-sample
sample.dice.d6  1       1508917208
sample.dice.d20 16      1508917208

Register in the official plugin registry

To make it easier for other users to find helpful plugins, Mackerel provides an official plugin registry. Registered plugins can be installed in the format of mkr plugin install <plugin_name>.

To register, just send a Pull Request to the plugin registry’s Github repository.

In this document, we’ve gone over how to make your own plugins compatible with mkr plugin install and how to register them in the official plugin registry. If you happen to create a useful plugin that other users might find helpful plugin, by all means, send a Pull Request to the plugin registry.