読み取り専用APIキーと新しいAPIを使った安心で便利なサーバ管理

MackerelではAPIを使っていろいろな機能を実現することができます。 本記事ではより便利になったMackerelのAPIの活用事例を紹介します。

MackerelのAPIについて

MackerelではAPIを使用して、各種の情報の取得や更新が出来ます。

例えば管理しているホストの一覧はcurlを使って以下のように取得できます。

$ curl -H "X-Api-Key: <YOUR_API_KEY>" https://mackerel.io/api/v0/hosts.json

レスポンスはJSONで返ってくるため、各言語のJSONライブラリを使ってパースしたり、jqなどのツールで必要な情報を取り出すことが出来ます。

詳しくはAPI仕様をご覧ください。

help-ja.mackerel.io

安全に使用できる読み取り専用APIキーの登場

MackerelのAPIはオーガニゼーション毎に作成したAPIキーを使って認証を行います。

しかしながら、これまではすべてのAPIキーに書き込み権限があり、気軽に利用するにはいくつかの不安点がありました。

  • 誤って更新操作をしてしまう心配があった
  • 漏洩したときに不正な操作をされてしまう心配があった

もちろん漏洩した場合はAPIキーを削除して無効化することが出来ましたが、無効化するまでの間に、悪意のある第三者によって不正に操作されてしまう危険性がありました。

mackerel.io

これらの問題を解決し、気軽にAPIを利用出来るように、読み取りのみの権限が設定出来るようになりました。 今後は安心してAPIを利用することが出来ます。

本記事では、最近新たに追加されたAPIの紹介も兼ねて、特に読み取り専用のAPIキーを使った活用事例を紹介します。

利用事例を3つご紹介

APIを利用したサーバオペレーション

MackerelのAPIからホスト情報を取得することで、例えばあるサービスの特定のロールの属するホストに同時にSSHでログインするといった、よく行うがちょっとめんどうな作業を効率化することが出来ます。

ここでは、簡単なシェルスクリプトを書くことで、より便利にAPIを使用することが出来ることを示します。

これから紹介するスクリプトは環境変数にMACKEREL_APIKEYを設定することによって使用できます。

$ export MACKEREL_APIKEY="YOUR API KEY"

サービス一覧を取得するスクリプト

#!/bin/bash
curl -s -H "X-Api-Key: $MACKEREL_APIKEY" "https://mackerel.io/api/v0/services" | jq -a -M -r '.services[].name'

上記のスクリプトを利用してサービス一覧を取得することができます。

サービスに属するロール一覧を取得するスクリプト

#!/bin/bash
if [[ $1 == '' ]]; then
  echo "requried service name"
  exit 1
fi
curl -s -H "X-Api-Key: $MACKEREL_APIKEY" -X GET "https://mackerel.io/api/v0/services/$1/roles" | jq -a -M -r '.roles[].name'

引数にサービス名渡すと、サービスに紐付いたロールの一覧を取得することができます。

組み合わせてもっと便利に

このような小さなスクリプトではあまり便利には感じないのですが、これらを組み合わせることで毎日のオペレーションが少し便利になります。

最初にご紹介した、あるサービスのロールに属するホスト一覧に同時にSSHするためにMackerelからホストの一覧を取得してみます。

#!/bin/bash
if [[ $1 == '' ]]; then
  # サービス一覧を取得するスクリプト
  service=$(services | peco)
else
  service=$1
fi

if [[ $2 == '' ]]; then
  # ロール一覧を取得するスクリプト
  role=$(roles $service | peco)
else
  role=$2
fi

curl -s -H "X-Api-Key:$MACKEREL_APIKEY" -X GET "https://mackerel.io/api/v0/hosts.json?service=$service&role=$role" | jq -a -M -r ".hosts[].name"

ここではpecoというフィルタリングツールを利用して、APIから取得したサービス一覧や、ロール一覧を絞りこみながら選択して、最後にホストの一覧をAPIで取得しています。

この例では複数のロールを選択するなどの柔軟なことは出来ませんが、毎回ホスト名を入力していたことを考えると便利になったのではないでしょうか。

このようにシンプルなAPIでも、組み合わせ次第でとても便利に使うこと出来ます。

tmux + ssh + Mackerel API を組み合わせたとにかくモダンなサーバオペレーション - ゆううきブログ

上記のエントリーでもモダンなサーバーオペレーションを実現していますが、新しく公開されたサービス・ロールAPIを使うことで、さらにモダンなオペレーションになりました！

使用したAPI

簡単にカスタムダッシュボード作成! Mackerel Dashboard Generator

カスタムダッシュボードを使うと好きなグラフを並べて表示することができます。

help-ja.mackerel.io

この機能を使って、あるサービスのロールに属するホストの各メトリクスのグラフを表示したいケースがあります。しかし、カスタムダッシュボードでそれらすべてのグラフを手作業で貼り付けていくのはとても時間がかかってしまいます。

そこで、mackerelio/mdgというツールを使用すると、カスタムダッシュボード用のMarkdownを生成することができます。

対象となるサービスとロール、そして表示するグラフの期間を指定すれば、標準メトリクスの埋め込みグラフを表示するMarkdownを自動的に表示することが出来ます。

$ mdg -o Saba -s Saba-service -r db

上記のようにオプションにサービスなどの情報を指定して実行すると以下のようなMarkdownが生成されます。

### disk.writes
|2d|3w|3mo|
|:--|:--|:--|
|<iframe src='https://mackerel.io/embed/orgs/Saba/services/Saba-service/db?graph=disk.writes&amp;period=2d' height='200' width='400' frameborder='0'></iframe>|<iframe src='https://mackerel.io/embed/orgs/Saba/services/Saba-service/db?graph=disk.writes&amp;period=3w' height='200' width='400' frameborder='0'></iframe>|<iframe src='https://mackerel.io/embed/orgs/Saba/services/Saba-service/db?graph=disk.writes&amp;period=3mo' height='200' width='400' frameborder='0'></iframe>|

...

このMakrdownをカスタムダッシュボードに貼り付けると以下のようなダッシュボードが作成できます。

このツール、よく見るとAPIを使っていませんね。しかもサービス名とロール名を入力するのがとても大変です。

そこで前回作ったシェルスクリプトを使ってみてください。サービス名とロール名を取得することが出来ます。

mdgのREDAMEにはAPIとpecoを組み合わせて便利に利用する例を記載しています。

使用したAPI

サーバー管理台帳を自動生成

APIを使うと、サービス・ロールごとに管理しているホストの情報一覧の表を作成することができます。 以下はGoogle Spreadsheetsで作成した例です。

この例では、Google Apps Scriptを使用して管理しているホストの情報を取得し、一覧を作成しています。 また、Googleスプレッドシートを活用することで、自動的に統計情報を表示したりすることも可能です。

報告書の作成や、Mackerel本体だけでは表示出来無い自由な組み合わせで事業の成長とともに増え続けるホストを俯瞰することが出来ます。

使用したAPI

まとめ

新しく追加された、読み取り専用APIキーや、サービス・ロールAPIによって、MackerelのAPIを安心かつより便利に使えるようになりました。

今回ご紹介したAPIの他にもメトリックや監視設定を扱うAPIも提供しております。もちろん書き込み権限のあるAPIキーを使って更新操作を行うAPIも提供しております。 詳しくはAPI仕様（v0）をご覧ください。

help-ja.mackerel.io

開発チームでは今後さらに便利に利用いただけるように開発を続けております。 APIに関する要望、ご意見などのフィードバックもお待ちしております。

さらに使いやすくなったMackerelのAPIを、是非お試しください。