mkr plugin installに対応したプラグインを作成するのドキュメントの仕様を満たしたmackerelプラグイン及びcheckプラグインは、mkr plugin installコマンドでインストールできます。このコマンドは、コマンドを実行したOSやArchを考慮して対応する実行ファイルをGithub Releasesから取り出してくれるため、簡単にプラグインをインストールできます。
本ドキュメントではmkr plugin installコマンドの利用方法について紹介します。
Synopsis
# Usage: mkr plugin install [--prefix <prefix>] [--upgrade] [--overwrite] <install_target> # Install mackerelio/mackerel-plugin-sample(v0.0.1 release) to /opt/mackerel-agent/plugins/bin $ sudo mkr plugin install mackerelio/mackerel-plugin-sample@v0.0.1 # Install mackerel-plugin-sample(latest release) defined in plugin registry to /path/to/plugin_dir/bin $ mkr plugin install --prefix /path/to/plugin_dir mackerel-plugin-sample
Githubからプラグインをインストールする
mkr plugin installを使うと、Githubのレポジトリからプラグインをインストール出来ます。ただし、プラグインはこのドキュメントに書かれた仕様を満たしている必要があります。
Githubからインストールしたいときは、次のようにGithubのowner名とrepository名、さらにGithub Releasesのタグ名を指定します。
$ mkr plugin install <owner>/<repo>[@<release_tag>]
例えば mackerelio/mackerel-plugin-sample のリリースから、v0.0.1のリリースをインストールしたい場合、次のようにします。プラグインの実行ファイルはデフォルトでは/opt/mackerel-agent/plugins/bin以下に配置されます。
$ 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
もしGithub Releasesのタグ名を省略した場合は、Github Releasesから最新のリリースを探してインストールします。最新のリリースを取得するためにGithubのAPIにアクセスするので、後述のとおりGithubのトークンを設定する必要があることにご注意ください。
$ sudo mkr plugin install mackerelio/mackerel-plugin-sample
# 最新のリリースのv0.0.1がインストールされる
レジストリに登録されたプラグインをインストールする
Mackerelでは有益なプラグインを探しやすいように公式でプラグインレジストリを用意しています。plugins/ディレクトリ以下に登録されているプラグインはmkrを使って簡単にインストールできます。
$ mkr plugin install <plugin_name>[@<release_tag>]
例えばレジストリにはmackerel-plugin-sample.jsonというファイルがあるため、これをインストールするには次のようにします。
# mackerel-plugin-sampleのv0.0.1リリースをインストール # 注) リリースタグはレジストリのsourceで定義された実際のGithubレポジトリを見に行く必要があります $ sudo mkr plugin install mackerel-plugin-sample@v0.0.1 # mackerel-plugin-sampleの最新リリースをインストール $ sudo mkr plugin install mackerel-plugin-sample
プラグインを別の場所にインストールする
デフォルトではプラグインの実行ファイルは/opt/mackerel-agent/plugins/binにインストールされますが、--prefixオプションを使うことで別の場所にインストール可能です。
$ mkr plugin install --prefix /path/to/plugin_dir mackerel-plugin-sample # /path/to/plugin_dir/bin 以下にコマンドがインストールされる
指定したリリースタグのプラグインがインストールされていない場合のみインストールする
--upgradeオプションを利用することで、指定したリリースタグのプラグインがインストールされていない場合のみインストールできます。
$ sudo mkr plugin install mackerelio/mackerel-plugin-sample@v0.0.2
Downloading https://github.com/mackerelio/mackerel-plugin-sample/releases/download/v0.0.2/mackerel-plugin-sample_darwin_amd64.zip
Installing /opt/mackerel-agent/plugins/bin/mackerel-plugin-sample
Successfully installed mackerelio/mackerel-plugin-sample@v0.0.2
$ sudo mkr plugin install --upgrade mackerelio/mackerel-plugin-sample@v0.0.2
release_tag v0.0.2 is already installed. Skip installing for now
$ sudo mkr plugin install --upgrade mackerelio/mackerel-plugin-sample@v0.0.3
Downloading https://github.com/mackerelio/mackerel-plugin-sample/releases/download/v0.0.3/mackerel-plugin-sample_darwin_amd64.zip
Installing /opt/mackerel-agent/plugins/bin/mackerel-plugin-sample
Successfully installed mackerelio/mackerel-plugin-sample@v0.0.3
このオプションを付けることで無意味なダウンロードが避けられるため、プロビジョニングツールでのプラグインインストール時にはupgradeオプションを付けることをおすすめします。
なお、upgradeオプションを利用するとダウングレードをすることもできます。たとえば、v0.0.2がインストールされている状況でv0.0.1を指定して実行すると、v0.0.1をインストールできます。
既に同じ名前の実行ファイルがあっても上書きする
デフォルトではmkrは同じ名前の実行ファイルがインストール先にあった場合、そのファイルのインストールをスキップします。--overwriteオプションを付けることで、スキップせずに必ず上書きすることが出来ます。
# 既に実行ファイルが存在する時スキップする $ sudo mkr plugin install mackerel-plugin-sample Downloading https://github.com/mackerelio/mackerel-plugin-sample/releases/download/v0.0.1/mackerel-plugin-sample_darwin_amd64.zip /opt/mackerel-agent/plugins/bin/mackerel-plugin-sample already exists. Skip installing for now Successfully installed mackerel-plugin-sample # --overwriteオプション付きなら強制的に上書きする $ sudo mkr plugin install mackerel-plugin-sample --overwrite 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 mackerel-plugin-sample
このオプションは同一バージョンのプラグインを再インストールしたい場合に有用です。それ以外の場合は--upgradeオプションをご利用ください。
Githubのトークンを設定する
mkr plugin installはGithubから最新のリリースを探すためにGithub APIを利用します。そのため、Githubの設定画面から取得できるアクセストークンを指定しておかなければ、Github APIのRate Limitの制限にあたり、インストールが失敗する可能性があります。
mkrではGITHUB_TOKEN環境変数もしくは.gitconfigのgithub.tokenをアクセストークンとして利用します。このどちらかを指定してください。
# 環境変数での設定 $ export GITHUB_TOKEN=<github_access_token> # .gitconfigでの設定 $ git config --global github.token <github_access_token>
サーバプロビジョニングツールからmkr plugin installを使うときは
Githubのアクセストークンを設定したとしても、ChefやAnsibleなどのサーバプロビジョニングツールを使って大量のサーバから一斉にmkr plugin installした場合、Github APIのRate Limitの制限にかかる事があります。
mkr plugin installではGithub Releasesのリリースタグが明示的に指定された場合、GithubのAPIにアクセスしないため、Rate Limitの制限にかかることはありません。そのため、サーバプロビジョニングツールから利用するときは、リリースタグを明示的に指定することをおすすめします。
mkr plugin installでインストールできるプラグインを作成する
mkr plugin installでインストールできるプラグインを作成したい場合、次のドキュメントを参照してください。
有益なプラグインを作成したら、是非インストーラへの対応やプラグインレジストリへの登録をして頂けたらと思います。
