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.

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

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
           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

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

Installing only if the plugin of the specified release tag is not already installed

Using the --upgrade option, you can skip the installation process if the plugin of the specified release tag is already installed.

$ 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

This option allows you to avoid meaningless downloads. We recommend adding in this upgrade option when performing plugin installation with provisioning tools.

You can also use the upgrade option to downgrade. For example, if v.0.0.2 is currently installed and v0.0.1 is then specified and executed, v0.0.1 will be installed.

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
           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
# Forcibly overwrite with --overwrite option
$ 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

This option is useful if you want to reinstall plugins of the same version. Otherwise use the --upgrade option.

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.