Kompira Enterprise REST API を利用して外部からジョブフローを実行する

監視ツールなどの外部システムから Kompira Enterprise に登録されているジョブフローを実行したい場合があります。例えば障害発生時には、サーバーやネットワークなどの状況を調べたり、障害プロセスを再起動させるなどの一次対応を行う場合などがあります。
本稿では Kompira Enterprise の REST API 機能を利用して、外部からジョブフローを呼び出してみましょう。

※ 本稿は Kompira Enterprise 1.6系に準拠した画像を用いています。

動作確認環境

本稿は、以下の環境で検証しています。

または

または

事前準備

API を利用するためには認証用のトークンが必要になります。
まず、Kompira Enterprise の画面上部から “設定 > ユーザー管理 > (ログイン中のアカウント名) > 編集” にアクセスします。そして、以下のように REST API 機能を有効にして、トークンを取得します。

※以下の画像は Kompira Enterprise バージョン 1.6.8 時点のものです。他のバージョンでは項目が異なることがあります。

一番下の「REST API 有効化」を選択した状態で「保存」ボタンをクリックします。

「REST API トークン」の「トークンを表示する」をクリックして、表示された文字列が認証用のトークン (Token) ですので、これをメモしておきます。

ジョブフローの作成

ノード情報 “server1” に登録されたサーバーマシンの Apache httpd のプロセスをリスタートします。(「ノード情報」および「アカウント情報」の設定方法については、「[事前準備] 接続先のサーバを登録する」を参考にしてください。) ここでは “/root/restart_process” というジョブフローを作成します。

※ ここでは systemctl コマンドを利用していますが、お使いのサーバーマシンのバージョン、ディストリビューションに合わせて変更してください。

[
    __node__ = ./server1,
    __sudo__ = true
] ->
['systemctl restart httpd.service && sleep 5'] =>
{ if $STATUS != 0 |
    print('httpd 起動に失敗しました') ->
    return(false)
} ->
print('httpd を起動しました') ->
return(true)

このジョブフローを実行して、「起動しました」または「起動に失敗しました」の表示が出ることを確認してください。

API のエンドポイント

Kompira Enterprise REST API のエンドポイントは、通常の Kompira Enterprise オブジェクトへのリソースパスと同じになります。すなわちルートエンドポイントは
http[s]://<Kompira Enterprise サーバー URL>/
となり、上記のジョブフローの場合には
http[s]://<Kompira Enterprise サーバー URL>/root/restart_process
となります。

ブラウザからのアクセスと API リクエストを区別するために、HTTP リクエストの Accept ヘッダに

Accept: application/json

を含めるか、クエリ文字列に

format=json

を含める必要があります。

API のユーザ認証

認証はトークン認証と、セッション認証方式の2種類が許可されています。ここではトークン認証を利用します。以下のようにリクエストの Authorization ヘッダにトークン鍵を含めます。

Authorization: Token <トークン鍵>

または、HTTP リクエストのクエリ文字列に、以下のようにトークン鍵を含める方法もあります。

token=<トークン鍵>

API でのジョブフローの起動

実際に API にリクエストを送ってみましょう。今回は、POST メソッドで送信する必要がありますので、API のクライアントツールやブラウザのプラグイン (例えば、Firefox の “RESTClient” など) を使ってみてください。
ここでは、curl コマンドを用いることにします。

リクエストのURLは

POST <ジョブフローパス>.execute

となります。上記のように、外部のシステムから指定するジョブフローに対応するパス名 + “.execute” と指定することにより、ジョブフローを起動させることができます。

$ curl -H "Authorization: Token <トークン鍵>" -H "Accept: application/json" -XPOST https://<Kompira Enterprise サーバー URL>/root/restart_process.execute --insecure
"/process/id_262"

応答は起動したジョブフローのプロセスIDです。
また、Kompira Enterprise 画面上部の “プロセス一覧 > 全てのプロセス > 該当する ID” で、実行結果を確認することができます。

ちなみに API へのリクエストを GET メソッドで送信すると、ジョブフローの情報を JSON 形式で取得することができます。今回は応答結果を見やすくするために、”jq” で整形しています。

$ curl -H "Authorization: Token <トークン鍵>" -H "Accept: application/json" https://<Kompira Enterprise サーバー URL>/root/restart_process.execute --insecure | jq
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   717  100   717    0     0   5466      0 --:--:-- --:--:-- --:--:--  5690
{
  "id": 599,
  "abspath": "/root/restart_process",
  "owner": "root",
  "fields": {
    "source": "[\r\n __node__ = ./server1,\r\n __sudo__ = true\r\n] ->\r\n['systemctl restart httpd.service && sleep 5'] =>\r\n{ if $STATUS != 0 |\r\n print('httpd 起動に失敗しました') ->\r\n return(false)\r\n} ->\r\nprint('httpd を起動しました') ->\r\nreturn(true)\r\n",
    "multiplicity": null,
    "defaultCheckpointMode": false,
    "defaultMonitoringMode": "NOTHING"
  },
  "extra_properties": {},
  "user_permissions": {},
  "group_permissions": {},
  "created": "2023-06-26T09:03:13.459085+09:00",
  "updated": "2023-06-26T09:03:13.547353+09:00",
  "display_name": "restart_process",
  "description": "",
  "type_object": "/system/types/Jobflow",
  "parent_object": "/root"
}

※ Kompira Enterprise 1.5系と1.6系では、原則 https による HTTP リクエストしか認めていません。今回は簡単にするために、 --insecure オプションをつけることで、SSL 証明書がなくても HTTP リクエストを送れるようにしています。

応用例: 通知メールからの呼び出し

メールにて障害通知を受け取った場合を想定します。また、障害状況確認後に早急な一次対応が必要であるとします。

そこで、早急な一次対応を実現するために、メール文中のボタンをクリックすることで、一次対応用のジョブフローを起動する方法を考えてみます。

まず、HTML メールのフォーム (form) を使って呼び出し URL を作ります。この場合、トークンなどをヘッダーに含めることができないため、URL パラメータとして渡すようにしています。

次に、通知メールを送るジョブフローを以下のように作成します。

※ 今回は簡単にするために、事前に呼び出すジョブフローを静的に決めています。しかし運用自動化の観点からは、通知メールを送る段階で、該当する処理を動的に選択するべきです。

[
    mailbody = """
<html><body>
サーバーがダウンしました
<form method="POST" action="https://<Kompiraサーバー>/root/restart_process.execute?token=<トークン鍵>&format=json">
<input type="submit" value="httpd をリブート" />
</form>
</body></html>
""" 
] ->
print(mailbody) ->
mailto(
    to="宛先のメールアドレス",
    from="差出元メールアドレス",
    subject="[ALERT] Server Down",
    body=mailbody,
    html_content=mailbody
)

Gmail の場合の受信メール例は、以下の通りです。

この「httpd をリブート」ボタンをクリックして、先の curl コマンドの場合と同様にプロセス ID が表示されることを確認してください。

※ メールクライアントによっては、URL をクリックしても GET メソッドでリクエストが送信される場合がありますので、ご注意ください。