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という命名規則に従っていること
  • アーカイブの中に、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で実装されているため、実行ファイルとリリースアーカイブの作成はgoxcで、Github Releasesへのリリースはghrで行います。今回はgoxc + ghrでリリースを行っていますが、仕様さえ満たしていればどんなツールを用いても問題ありません。

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

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

$ go get -v -u github.com/laher/goxc
$ go get -v -u github.com/tcnksm/ghr

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

続いて、goxcを用いて実行ファイルとリリースアーカイブの作成を行います。goxcは.goxc.jsonという設定ファイルを置いておくことで細かくリリースアーカイブの作成方法を調整できます。プラグインインストーラが推奨している仕様を満たすため、以下のような.goxc.jsonを作成します。

https://github.com/mackerelio/mackerel-plugin-sample/blob/master/.goxc.json

{
    "ArtifactsDest": "dist",
    "Tasks": [
        "clean-destination",
        "xc",
        "archive-zip",
        "rmbin"
    ],
    "TaskSettings": {
        "archive-zip": {
            "include-top-level-dir": "windows darwin linux",
            "platforms": "windows darwin linux"
        }
    },
    "Arch": "386 amd64",
    "Os": "linux darwin windows",
    "ConfigVersion": "0.9"
}

この設定を置いた後、goxcコマンドを実行することで、dist/snapshot/ディレクトリ以下に推奨仕様に従ったアーカイブを作成できます。

$ goxc
$ ls -1 dist/snapshot
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/snapshot/mackerel-plugin-sample_linux_amd64.zip
$ ls -1 mackerel-plugin-sample_linux_amd64
LICENSE
README.md
mackerel-plugin-sample

今回はwindows/darwin/linux OSのamd64/386 Archで、計6つのプラットフォームに対応した実行ファイルを作成しています。どのプラットフォームに対応するかは.goxc.jsonOsArchという項目で調整できるため、適宜変更してください。

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

Github Releasesへのリリース

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

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

これで、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)
goxc
ghr -u mackerelio -r mackerel-plugin-sample $latest_tag dist/snapshot/

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

$ 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を送ってみてください。