Kompira

Menu Menu

Enterprise Technical information

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

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

 


環境情報

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

項目 バージョン
OS CentOS Linux release 7.8.2003
Kompira ver.1.5.5.post7

 


 

事前準備

APIを利用するためには認証用のトークンが必要になります。以下の画面よりREST APIの機能を有効にして、トークンを取得します。
設定 -> ユーザー管理 -> (ログイン中のアカウント名) -> 「編集」ボタンをクリック

 

Activate REST API

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

API Token

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

 

ジョブフローの作成

ノード情報”server1″に登録されたサーバー機のApache httpdのプロセスをリスタートします。(ここではserviceコマンドを利用していますが、お使いのサーバー機のバージョン、ディストリビューションに合わせて変更してください。)
ここでは”/root/restart_process”という名前のジョブフローを作成します。

 

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

 

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

 

APIのエンドポイント

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

 

となります。

 

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

 

応答は起動したジョブフローのプロセスIDです。
画面上部の「プロセス一覧」>「全てのプロセス」>(該当するID) の画面で、実行結果を確認する事が出来ます。

 

process result detail

 

ちなみにAPIへのリクエストをGETメソッドで送信すると、ジョブフローの情報をJSON形式で取得できます。

 

$ curl -H "Authorization: Token <トークン鍵>" -H "Accept: application/json"  http://<Kompiraサーバー>/root/restart_process.execute
{"id":62,"abspath":"/root/restart_process","owner":"root","fields":{"defaultMonitoringMode":"NOTHING","source":"[__node__ =/root/server1]->\r\n[__sudo__ = true]\r\n-> ['systemctl restart httpd.service && sleep 5']\r\n=> { if $STATUS != 0 |\r\n     print('httpdの起動に失敗しました') -> return(false) }\r\n-> print('httpdを起動しました') \r\n-> return(true)","defaultCheckpointMode":false,"multiplicity":null},"extra_properties":{},"user_permissions":{},"group_permissions":{},"display_name":"restart_process","description":"","created":"2017-02-06T05:22:23.261092Z","updated":"2017-02-06T06:19:47.230524Z","type_object":"/system/types/Jobflow","parent_object":"/root"}

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

 

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

エラー通知を受け取った場合に、状況確認後に急いで一次対応が必要になる場合を考え、メール文中のボタンをクリックする事でジョブフローを起動してみます。(※運用自動化の観点からは、通知メールを送る段階で該当する処理を実行すべきところです。) HTMLメールのフォーム(form)を使って呼び出しURLを作ります。トークンなどをヘッダーに含める事が出来ないため、URLのパラメータとして引き渡します。

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

 

[mailbody="""
<html><body>
サーバーがダウンしました
<form method="POST" action="http://<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の場合)

link on Gmail

 

この「httpdをリブート」ボタンをクリックして、先のcurlコマンドの場合と同様にプロセスIDが表示されれば起動OKです。
(※メールクライアントによっては、URLをクリックしてもGETメソッドでリクエストが送信される場合がありますので、ご注意ください。)

スタートガイド

Kompiraジョブフローの基礎

ジョブフローの簡単な例

Kompiraの機能

外部との連携