mkrのサードパーティプラグインインストール機能について

先週のリリースで mkr コマンドへのプラグインのインストール機能が追加がアナウンスされました。これは、ユーザーが自作したサードパーティプラグインをより簡単にシステムに導入しやすくするものです。

これまで、ユーザーが自作したプラグインをシステムに導入するためには、自前でインストールの仕組みを整えるか、以下の中央リポジトリにコードを寄贈いただく必要がありました。

今回のプラグインインストール機能を利用することで、自身のGitHubリポジトリで作成したプラグインを mkr コマンドを用いてインストールすることができます。これにより、プラグインを作成者自身が継続的にメンテンナンス可能になります。

また、中央リポジトリにコードを寄贈頂く場合は、プラグインをGoで開発する必要がありましたが、この機能を利用する場合、プラグインの開発には任意の言語が利用可能です。

利用方法

mkr plugin install コマンドを用いて、指定したMackerelプラグインパッケージの中身をシステムにインストールすることができます。

% sudo mkr plugin install <owner>/<repo>[@<release_tag>]

Githubのowner名とrepository名、さらにGithub Releasesのタグ名を指定することで、GitHub ReleasesからMackerelプラグインパッケージを取得し、インストールをおこないます。

Mackerelプラグインパッケージ形式について

Mackerelプラグインパッケージは単なるzipファイルです。アーカイブの中に mackerel-plugin- もしくは check- から始まる実行可能ファイルが格納していることが期待されています。実行可能ファイルであれば、言語はなんでも構いません。

mkr plugin install コマンドは、それら実行可能ファイルをMackerelプラグインとみなし、所定の位置にプラグインを配置します。デフォルトでは /opt/mackerel-agent/plugins/bin 以下に配置されます。

MackerelプラグインパッケージをGitHub Releasesにアップロードする

% sudo mkr plugin install <owner>/<repo>[@<release_tag>]

上記コマンドを実行した場合、mkr は以下のURLのMackerelプラグインパッケージの取得を試みます。

https://github.com/<owner>/<repo>/releases/download/<release_tag>/<repo>_<GOOS>_<GOARCH>.zip

GitHub Releases の <release_tag> に <repo>_<GOOS>_<GOARCH>.zip という命名規則に従ってMackerelプラグインパッケージを配置すれば、上記のURLから、Mackerelプラグインパッケージをダウンロード可能になります。mackerel-plugin-sample を例に取ると以下のようになります。

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

公式プラグインレジストリについて

https://github.com/mackerelio/plugin-registry

ユーザーが作成した有益なプラグインを、公式プラグインレジストリに登録することで、他のユーザーがプラグインを見つけやすくなります。プラグインレジストリに登録されたプラグインは mkr plugin install <plugin_name> という形式でインストールできるようになります。

登録はプラグインレジストリのGithubレポジトリにPull Requestを送ることでおこないます。Pull Requestの内容は、 <plugin_name>.json というファイルを plugins/ ディレクトリ配下に作成するだけです。JSONファイルのフォーマットは以下のとおりです。

https://github.com/mackerelio/plugin-registry/tree/master/plugins で現在登録されているプラグイン一覧を見ることができます。

公式プラグインレジストリに登録されているプラグイン自体のメンテナンス権やライセンスに関しては、参照先のリポジトリに準ずることをご了承下さい。

是非どしどしPull Requestをお寄せ下さい。

余談ですが、このようなパッケージ管理のレジストリには、 CPAN や RubyGems、 homebrew のようなクールな名前がついていることが多いため、 公式プラグインレジストリにも命名が検討されました。はてなCTO id:motemen による tsukiji が魅力的だったのですが、様々な理由により却下となり、無難な plugin-registry という名前に落ち着きました。

既存の中央リポジトリへのPull Requestについて

これまで、新しいプラグインの登録を上記中央リポジトリで受け付けてきましたが、今後、新しいプラグインの追加は原則受け付けません。もちろん、既存のプラグインへの機能追加やバグ修正はウェルカムです。

新しいプラグインを作成した場合は、ユーザー自身でプラグインリポジトリをGitHub上に作成し、それを、公式プラグインレジストリに登録するようにして下さい。

レジストリに登録されたプラグインを、rpmやdebで配布しているMackerel公式のプラグインパッケージに取り込みたい場合には、別途issue等でご相談下さい。また逆にレジストリに登録されたパッケージを公式プラグインパッケージへ取り込むことを、Mackerel開発チームから作者の方に打診させていただくこともあるかと思いますので、その際はよろしくおねがいします。

より詳細なドキュメントについて

本エントリに記載した、サードパーティのプラグインのインストール方法や、Mackerelプラグインパッケージの作成方法についての詳細は以下のヘルプをご参照下さい。

mackerel.io mackerel.io

今後の拡張について

今後以下の様な拡張を検討しています。

  • 現状、Mackerelプラグインパッケージの命名が <repo>_<GOOS>_<GOARCH>.zip と厳密に定められているため、これを柔軟にテンプレート的に設定できるように
  • インストールしたプラグインのアップデート機能
  • メタデータプラグイン対応

もちろん、本機能に対する追加機能提案やPull Requestもお待ちしています。

まずは、プラグインを自作して、公式プラグインレジストリ へPull Requestをお送りいただけるとうれしいです。