Using mkr plugin install

Mackerel plugins as well as check plugins that meet the specifications listed in the document “Creating plugins supported with mkr plugin install” can be installed using the mkr plugin install command. This command retrieves the corresponding executable file from Github Releases, taking into account the OS or CPU Architecture that executed the command, in order to easily install the plugin.

In this document, we’ll be introducing how to use the mkr plugin install command.


# Usage: mkr plugin install [--prefix <prefix>] [--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

Installing plugins from Github

Using mkr plugin install, plugins can be installed from Github's repository. However, the plugin must meet the specifications described in this document.

To install from Github, specify the Github owner name, repository name, as well as the tag name for Github Releases as shown below.

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

Using this release of mackerelio/mackerel-plugin-sample as an example, installing the v0.0.1 release should be as follows. The plugin’s executable file will be under /opt/mackerel-agent/plugins/bin by default.

$ sudo mkr plugin install mackerelio/mackerel-plugin-sample@v0.0.1
           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

If you omit the tag name for Github Releases, the latest release from Github Releases will be sought and installed. Please note that in order to obtain the latest release, the Github API will be accessed and you will need to configure the Github token as described later on.

$ sudo mkr plugin install mackerelio/mackerel-plugin-sample
# The latest release v0.0.1 to be installed

Installing plugins registered in the repository

Mackerel provides an official plugin registry to help users find helpful plugins. Plugins registered under plugins/directory can easily be installed using mkr.

$ mkr plugin install <plugin_name>[@<release_tag>]

For example, in order to install the file in the registry called mackerel-plugin-sample.json, do the following.

# Install mackerel-plugin-sample release v0.0.1
# Note) The release tag must go to the actual Github repository defined by the registry source
$ sudo mkr plugin install mackerel-plugin-sample@v0.0.1
# Install the latest release of mackerel-plugin-sample
$ sudo mkr plugin install mackerel-plugin-sample

Installing plugins in a different location

By default, the plugin's executable file is installed in /opt/mackerel-agent/plugins/bin, but can be installed in a different location by using the --prefix option.

$ mkr plugin install --prefix /path/to/plugin_dir mackerel-plugin-sample
# Command to be installed under /path/to/plugin_dir/bin

Overwriting existing executable files with the same name

If an executable file with the same name already exists, mkr will skip the installation of that file by default. By attaching the --overwrite option you can choose to always overwrite without skipping.

# Skip when executable file already exists
$ sudo mkr plugin install mackerel-plugin-sample
           /opt/mackerel-agent/plugins/bin/mackerel-plugin-sample already exists. Skip installing for now
           Successfully installed mackerel-plugin-sample
# Forcibly overwrite with --overwrite option
$ sudo mkr plugin install mackerel-plugin-sample --overwrite
           Installing /opt/mackerel-agent/plugins/bin/mackerel-plugin-sample
           Successfully installed mackerel-plugin-sample

Currently mkr plugin install does not have a feature for upgrading release tags, so please use this --overwrite option when updating plugins.

Configuring the Github token

mkr plugin install uses the Github API to find the latest release from Github. Therefore, if you do not specify an access token that can be obtained from the Github settings screen, the installation may fail due to the Github API Rate Limit.

In mkr, the environment variable GITHUB_TOKEN or github.token from .gitconfig is used as the access token. Please specify one of these.

# Configure with environment variable
$ export GITHUB_TOKEN=<github_access_token>
# Configure with .gitconfig
$ git config --global github.token <github_access_token>

Using mkr plugin install from a server provisioning tool

Even if the Github access token is configured, you may be subject to restrictions of the Github API Rate Limit if using mkr plugin install from a large number of servers all at once with a server provisioning tool such as Chef or Ansible.

If a tag for Github Releases is explicitly specified in mkr plugin install, then the Github API will not be accessed and thus you will not be subject to the Rate Limit restrictions. Therefore, we recommend that you explicitly specify the release tag when using mkr plugin install from a server provisioning tool.

Creating a plugin that can be installed with mkr plugin install

If you want to create a plugin that can be installed with mkr plugin install, refer to the following documents.

If you create a useful plugin, we’d love to have you register it in the plugin registry and supported with the installer.