mkr plugin installに対応したプラグインを作成する

Mackerelのプラグインを作った際に、プラグインインストーラの仕様に対応しておくと、mkr plugin installコマンドを利用して簡単にプラグインをインストール出来るようになります。このドキュメントではその対応方法や、作成したプラグインを公式レジストリに登録する方法について説明します。

mkrを使ったプラグインのインストール方法についてはmkr plugin installでプラグインをインストールするを参照してください。Goを使ったプラグインの実装方法については go-mackerel-pluginを利用してカスタムメトリックプラグインを作成するを参照してください。

対応すべき仕様

mkr plugin installコマンドでインストールできるようにするためには、作成したプラグインのGithubレポジトリが以下の仕様を必ず満たす必要があります。

プラグインのレポジトリのGithub Releasesでバージョンごとにリリースタグが切られ、そこに命名規則に従ってOS/Archごとのアーカイブがアップロードされていること
アーカイブのファイル名が(REPOSITORY_NAME)_(GOOS)_(GOARCH).zipという命名規則に従っていること
- GOOSやGOARCHに入る文字列は https://golang.org/doc/install/source#environment を参照してください
- 例) https://github.com/mackerelio/mackerel-plugin-sample がプラグインのレポジトリとすると、64bit Linux用のアーカイブはmackerel-plugin-sample_linux_amd64.zip、32bit macOS用のアーカイブは mackerel-plugin-sample_darwin_386.zip
アーカイブの中に、mackerel-plugin-またはcheck-から始まる、実行権限があるファイルが存在すること

必須ではありませんが、次の仕様に従うことを推奨します。

1つのレポジトリが1つのプラグインの実行ファイルを提供すること
レポジトリ名と実行ファイル名が一致していること
Github Releasesにアップロードするリリースタグはvx.y.zという命名規則で付けること(例: v1.2.3)
README.mdとLICENSEファイルがアーカイブに含まれること

また、必須の仕様を満たしてさえいれば、プラグインをGoで実装していなくてもmkr plugin installコマンドでインストール可能です。

推奨仕様まで満たしたサンプルはmackerelio/mackerel-plugin-sampleに置いています。こちらもご参照ください。

プラグインが仕様を満たすように設定する

それでは実際に自作プラグインを推奨仕様に対応するように設定してみましょう。mackerelio/mackerel-plugin-sample のサンプルレポジトリを例に紹介します。

プラグインインストーラの仕様を満たすためには、実行ファイルの作成、リリースアーカイブの作成、Github Releasesへのリリースの三つを行う必要があります。mackerel-plugin-sampleはGoで実装されているため、実行ファイルとリリースアーカイブの作成はgoxzで、Github Releasesへのリリースはghrで行います。今回はgoxz + ghrでリリースを行っていますが、仕様さえ満たしていればどんなツールを用いても問題ありません。

goxzとghrをインストールする

まず必要なツールである、goxzとghrをインストールしておきます。インストールにはGoの実行環境が必要です。

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

実行ファイルとリリースアーカイブの作成

続いて、goxzを用いて実行ファイルとリリースアーカイブの作成を行います。

プラグインインストーラが推奨している仕様を満たすため、以下のオプションを用いてgoxzを実行してください。そうすると、指定したディレクトリ以下にリリースアーカイブが作られます。

$ 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

今回はwindows/darwin/linux OSのamd64/386 Archで、計6つのプラットフォームに対応した実行ファイルを作成しています。どのプラットフォームに対応するかはgoxzの-osと-archというコマンドラインオプションで調整できるため、適宜調整してください。

goxzの設定について詳しくはgoxzの公式ドキュメントを参照してください。

Github Releasesへのリリース

goxzによるリリースアーカイブの作成ができました。続いてこれらをGithub Releasesへリリースします。これはghrを使えば非常に簡単に行なえます。例えばmackerelio/mackerel-plugin-sampleにv0.0.1というリリースタグでリリースしたい場合、以下のコマンドを実行するだけです。

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

これで、Github Releasesのページで次のように表示されていたら成功です。

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

f:id:mackerelio:20171025162942p:plain

リリースユーティリティを作る

これまでの設定でプラグインインストーラの推奨仕様まで満たして、Github Releasesにリリースすることができました。しかし、手作業で上記の全ての作業を行なうと煩雑なので、作業を一気に行うリリースユーティリティを作っておくとさらに便利です。

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

これを使うと次のコマンドのみでリリースできます。

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

mkr plugin installでインストールできることを確認する

リリースが完了したら、最後に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

公式のプラグインレジストリに登録する

他のユーザーでも簡単に有益なプラグインを見つけられるように、Mackerelでは公式でプラグインレジストリを用意しています。プラグインレジストリに登録されたプラグインはmkr plugin install <plugin_name>という形式でインストール出来るようになります。

登録はプラグインレジストリのGithubレポジトリにPull Requestを送るだけです。

<plugin_name>.jsonというファイルをplugins/ディレクトリ配下に作成する
sourceというフィールドに<github owner>/<github repo>の形式でプラグインの場所を記述する
- 指定したレポジトリのプラグインがmkr plugin installでインストールできる必要があります
descriptionというフィールドにそのプラグインの簡易的な説明を記述する
例) https://github.com/mackerelio/plugin-registry/blob/master/plugins/mackerel-plugin-sample.json

本ドキュメントでは、自作のプラグインをmkr plugin installに対応する方法と、公式のプラグインレジストリに登録する方法について説明しました。有益なプラグインで他のユーザーにも役立ちそうなものができたら、是非プラグインレジストリにPull Requestを送ってみてください。