Technical information

Kompira cloud Pegionを利用した通知電話の利用

システム運用業務における重要な作業としてシステムの障害対応があります。監視システムからの異常通知を受けるために、昔はポケベル、最近は電話での音声通知や電子メール、メッセージングアプリなどが利用されています。特に通知を見逃さないための呼び出し手段として、電話は今もって重要な手段となっています。

ただし音声での電話通知の機能を構築するには、かつてはPBXを含む大がかりなシステムが必要でした。最近は各社より電話APIが提供されるようになり、電話での音声通知のシステムが比較的簡単に導入できるようになりました。

当社フィックスポイントでもKompira cloud Pegionという、システム運用における通知に特化した自動電話サービスを提供しております。本記事ではKompira enterpriseのジョブフローからPegionを使って電話通知を行う手順をご紹介します。

Kompira cloudのアカウントの取得

自動電話サービス”Pegion”を利用するためには、Kompira cloudのアカウント取得と電話API機能の開始登録が必要になります。以下のURLから必要事項を記載の上、アカウントを取得してください。”スペースID”はKompira cloudのユーザーを識別する固有の文字列であり、URLに使われます。例えばスペースIDが”shibuya”の場合、アクセス先はhttps://shibuya.cloud.kompira.jp/ となります。)

https://register.cloud.kompira.jp/

登録が完了すると、Kompira cloudのスペースIDごとの個別にURLが発行されますので、アクセスの上、認証してください。またいたずら防止のため、電話の発呼が出来ませんのでご注意ください。

Pegionの設定

続いて自動電話の設定を登録していきます。登録内容は(1) 連絡先 (2) コールフロー(電話をかける順番) (3) ガイダンス(読み上げるメッセージの内容など)となります。

詳しい設定方法は下記のTutorial記事をご参照ください。ここでは最低限の設定を行っていきます。

https://blog.cloud.kompira.jp/entry/manual/pigeon-tutorial

 

連絡先の登録

まず画面左の「連絡先」メニューページから、右上の+ボタンをクリックします。

表示名の名前と電話番号を入力して「保存」をクリックします。

コールフローの登録

同様に画面左の「コールフロー」ページから、右上の+ボタンをクリックして登録します。

表示名、最大ループ回数、連絡先を指定して「保存」をクリックします。

 

ガイダンスの登録

同様に画面左の「ガイダンス」ページから、右上の+ボタンをクリックして登録します。

表示名、メッセージテンプレート(読み上げるメッセージ)、応答を入力します。

「メッセージテンプレート」中の{{}} でくくられたキーワードは、API呼び出しの際に指定できます。

 

IDの取得

APIを呼び出す際のAPI token(認証トークン)、コールフローID、ガイダンスIDを取得します。

まずはAPI token から。右上のユーザーアイコン>設定をクリック。

 

 

API token画面の右上の+ボタンをクリック

トークンを識別する表示名とトークンを失効させる日付を指定して保存をクリック

次の画面でトークン文字列が表示されます。

文字列が表示されるのは、この画面が最初で最後です。必要に応じてメモ帳などに転記してください。以後、トークン文字列を紛失した場合には削除の上、新しいAPIトークンを発行します。

 

コールフローIDの取得

コールフロー画面で設定したいコールフローを選択します。画面右上の半角英数字の文字列が該当するコールフローIDですので、これを転記してください。(またはコールフローのトップ画面で、表示項目に”callflowID”を追加する事で表示できます)

 

ガイダンスIDの取得

コールフローIDと同様に、呼び出したいガイダンスの画面を選択し、画面右上の文字列を転記します。

ここまでで、Pegionの設定は出来ました。

 

Kompira enterpriseのジョブフローの作成

続いて、Kompira enterpriseのジョブフローからPegionのAPIを呼び出して、電話をかけてみます。

例えば、次のような「障害コール」という名前のジョブフローを作成します。

ここで、(API Token文字列)、(コールフローID文字列)、(ガイダンスID文字列)は、それぞれ先に転記したものを記載します。また parametersの “server”と”incident”は、Kompira cloudのガイダンス設定画面で指定した文字列を置換する文字列を指定します。

このジョブフローを実行しますと、指定の電話番号に「テスト用サーバーに軽度の障害を検出しました。・・・・」とメッセージが再生されます。

このようなコードを電話での通知の箇所に追記したり、ジョブフロー自体を -> [./障害コール] -> … のように呼び出してください。

ネットワーク機器へのコマンド投入

運用自動化する上でネットワーク機器に接続し設定情報や構成を取得したい場合があるかと思います。
Kompira enterprise(以降Kompiraと表記)にはネットワーク機器やサーバに接続しコマンド実行を行う機能があります。
本稿ではその機能を利用したネットワーク機器からの情報収集の手順を紹介します。

紹介する内容は以下の通りです。

・NW機器にSSH接続し、コマンド実行によって機器の情報を取得する
・NW機器にProxy経由でSSH接続し、コマンド実行によって機器の情報を取得する

なお、対応している接続方法についてはSSH(version2)のみとなります。
SSH(version1)やtelnetには対応していません。

 


環境情報

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

Kompiraサーバ

項目 バージョン
OS CentOS Linux release 7.6.1810
Kompira ver.1.5.3

VyOSルータ

項目 バージョン
OS VyOS 1.1.8

プロキシ(踏み台)サーバ

項目 バージョン
OS CentOS Linux release 7.6.1810

 

 


ネットワーク機器にSSH接続

Kompiraにはネットワーク機器に接続する機能がデフォルトで用意されています。

本稿ではその機能を使用して接続します。

 

以下の手順でネットワーク機器に接続します。

・Kompira上にアカウント情報オブジェクトを作成

・Kompira上にノード情報オブジェクトを作成

・VyOS上にスクリプト配置(※)

・コマンド実行

※: VyOSの場合、VyOSコマンドの直接実行は動作しないためスクリプトを配置する必要があります。

 

ネットワーク構成

以下のような環境で検証しています。

 

Kompira上にアカウント情報オブジェクトを作成

まず対象機器(VyOSルータ)に接続するためのアカウントを作成します。

次のオブジェクトを作成します。

名前 VyOSユーザ
アカウント情報

このオブジェクトの編集画面では、「ユーザー名」「パスワード」の指定をします。
認証に鍵ファイルが必要な場合は、別途鍵ファイルのパスやパスフレーズを登録してください。

 

Kompira上にノード情報オブジェクトを作成

次に接続先のノード情報を作成します。

次のオブジェクトを作成します。

名前 VyOSルータ
ノード情報

以下のような設定を実施します。

項目
IPアドレス 192.168.1.Z(VyOSルータのIPアドレス)
ポート番号 22
接続種別 ssh
シェル使用 チェックなし
アカウント VyOSユーザ

 

VyOS上にスクリプト配置

VyOSの場合、BashのComplete機能を用いてコマンドを実現しています。
通常のBashコマンド(date等)であれば動作はしますが、VyOSコマンドの直接実行は動作しません。
VyOSを使用しない場合は本手順は不要です。

以下のようなスクリプトを経由させて間接的にコマンドを実行する必要があります。

実行権限を付与します。

 

コマンド実行

以下のようなジョブフローを生成し、VyOSからバージョン情報を取得します。
ジョブフローはVyOSノード情報と同階層のディレクトリに作成します。

 

名前 VyOS設定取得ジョブフロー
ジョブフロー

 

 

正常に実行できた場合はバージョン情報が以下のように出力されます。

 

プロキシ(踏み台)経由の接続

ネットワーク環境によっては情報収集の対象機器に対して、Kompiraからの直接SSH接続を許可していない場合もあります。
この場合、プロキシサーバを経由した接続をしているネットワーク環境がほとんどだと思われます。
本項ではプロキシサーバ経由のSSH接続について紹介します。

以下の手順で設定します。

・プロキシサーバ用のアカウント情報の作成

・プロキシサーバ用のノード情報の作成

・VyOSルータのノード情報の修正

 

ネットワーク構成

以下のような環境で検証しています。

 

プロキシサーバ用のアカウント情報の作成

プロキシサーバに接続するためのアカウントを作成します。

次のオブジェクトを作成します。

名前 プロキシユーザ
アカウント情報

このオブジェクトの編集画面では、「ユーザー名」「パスワード」の指定をします。
認証に鍵ファイルが必要な場合は、別途鍵ファイルのパスやパスフレーズを登録してください。

 

プロキシサーバ用のノード情報の作成

プロキシサーバ用のノード情報を作成します。

次のオブジェクトを作成します。

名前 プロキシサーバ
ノード情報

 

項目
IPアドレス  192.168.1.Y(プロキシサーバのIPアドレス)
ポート番号 22
接続種別 ssh
シェル使用 チェック有
アカウント プロキシユーザ

 

 

VyOSルータのノード情報の修正

VyOSルータのノード情報を修正します。

IPアドレス 192.168.1.Z(プロキシサーバより接続できるIPアドレス)
プロキシ プロキシサーバ

 

設定後、VyOS設定取得ジョブフローを実行します。
コマンドの実行結果が正常であればプロキシ経由での実行は正常に動作しています。

またプロキシサーバの/var/log/secureを確認し、以下のようなログが出力されていればプロキシ経由での接続ができていることが分かります。

 

 

まとめ

本稿ではKompiraの機能を使ったネットワーク機器からの情報収集について紹介しました。
今回紹介したのは単純な情報取得のコマンドの実行までですが、「Kompiraのセッション機能を利用して対話的にコマンドを実行する」といった記事と組み合わせれば、複雑な運用の自動化も可能です。

 

参考

本文中にでてきたVyOS内で実行するスクリプトについては以下のブログを参考にしました。
http://d.hatena.ne.jp/iamsandman/20110510/1304984590

フィールド修飾子でフィールドの入力内容に制約を設ける

フォームからジョブフローへ渡す値の入力やテーブルなどオブジェクトに項目を登録・編集する際に、フィールドに対して何らかのルールを設けたい場面があるかと思います。
ジョブフローを実行するフォームを作成するでは、これを実現するフィールド修飾子について、enum, objectの指定による簡単な例についてご紹介しました。
今回は、上記コラムでは挙げられていない制限に関するフィールド修飾子についてご紹介いたします。

 


環境情報

本記事で説明するフィールド修飾子は、バージョン1.5.1で追加されたものも含まれます。
ご確認の際は、1.5.1以降のバージョンのKompiraをご用意ください。

項目 バージョン
OS CentOS Linux release 7.5.1804
Kompira ver.1.5.2

 


フィールド修飾子のおさらい

本題に入る前に、フィールド修飾子について振り返りたいと思います。

フィールド修飾子は、Kompiraオブジェクトのフィールド型に対し、表示の制御や制約内容を設定するものです。
Kompira上で作成可能なオブジェクトのうち、型オブジェクト設定オブジェクトフォームの3点で設定することが出来ます。
具体的には、次の場面で設定した内容が適用されます。

1. フォーム上のパラメータ(ジョブフローへ渡す引数)指定
2. テーブルへ項目を登録、登録済みの項目を変更
3. 設定または独自の型オブジェクトの登録または変更

フィールド修飾子は、JSON形式{“key”:”value”}で記入します。例えば、フィールドの初期値を予め設定したい場合は下記の通りになります。

記入はオブジェクトの登録・編集画面内の「フィールド修飾子フィールド」または、フィールド横のボタン(下記画像の赤丸)を押すことで表示されるエディタから行います。

型フィールド入力画面

フィールド修飾子の編集画面

 

次に現在のKompiraで用意されているフィールド修飾子についてご説明します。
下記の表は、使用可能なフィールド修飾子と対応するフィールド型をまとめたものです。
各フィールド修飾子の役割(Kompiraドキュメント「5.2.2. フィールド修飾子」に記載)は割愛させていただきますが、太字の項目が入力内容に制約を持たせるものになります。

フィールド修飾子名 設定可能なフィールド型 備考
default 全フィールド 1.5.1よりArray, Dictionary型に対応
invisible 全フィールド
help_text 全フィールド
object Object
directory Object
no_empty Object
enum Enum
pattern String 1.5.1より追加
min_length String 1.5.1より追加
max_length String 1.5.1より追加
min_value Integer 1.5.1より追加
max_value Integer 1.5.1より追加
file_accept File 1.5.1より追加

紹介するフィールド修飾子について

振り返りを踏まえて、制約に関わる下記6点を順に説明していきます。

目次

1. 入力可能な文字列の長さを指定する(min_lengthとmax_length)
2. 入力可能な整数値を指定する(min_valueとmax_value)
3. 入力可能な文字列を正規表現で指定する(pattern)
4. Object型フィールドで選択可能なオブジェクトを制限する(object)
5. Object型フィールドで未選択を許可しない(no_empty)
6. アップロード可能なファイル形式を制限する(file_accept)

 


入力可能な文字列の長さを指定する(min_lengthとmax_length)

String型フィールドは文字列を入力するためのフィールドです。
String型フィールドに入力可能な文字数の制限を設けたい場面があるかと思います。
最小文字数を指定するmin_length、最大文字数を指定するmax_lengthを指定することでString型フィールドの文字数を制限することができます。
下記の例では、5文字以上10文字以内の文字列のみ許可します。

この設定を無視して、範囲外の文字列を登録・変更しようとした場合、画面上に警告と設定した文字数の案内が表示されます。

 


入力可能な整数値を指定する(min_valueとmax_value)

整数値を入力するためのInteger型フィールドに対して入力可能な値に制限を設けることが可能です。
最小・最大値を表すmin_valueとmax_valueの2つのフィールド修飾子が用意されています。

下記の例では、1~10の範囲の整数値のみ許可します。

 

この設定を行うと、フィールド内の値の上下ボタンで指定可能な値の範囲に設定した最小・最大値が反映されます。
なお、フィールドへ直接入力した場合、設定した範囲外の値を入力することは可能ですが、保存する際に画面上に警告と設定可能な範囲が案内されます。

 


入力可能な文字列を正規表現で指定する(pattern)

patternを指定することで、String型フィールドに入力可能な文字列の制約を正規表現で設定することが出来ます。
例えば、英数字のみ入力できるフィールドを用意する場合、次のようなパターン文字列を指定します。

この設定を無視して、登録・変更しようとした場合、画面上に警告が表示されます。

patternを活用することで、前述の文字数制限以外にString型フィールドへ独自の制約を設けることが出来ます。

例:03からはじまるハイフンあり電話番号(03-4桁-4桁)のみ許可

例:郵便番号(半角数字3桁-半角数字4桁)のみ許可

例:24時間制の時刻(hh:mm:ss, 0埋め2桁)を表す文字列のみ許可

 


Object型フィールドで選択可能なオブジェクトを制限する(object)

フィールド修飾子objectを使って、フィールドで選択可能なオブジェクトをシステムで定義、独自に定義した型オブジェクトに制限する方法を紹介します。

システムで定義されている型オブジェクトに制限する

システム定義型ディレクトリ(/system/types)に格納されている型オブジェクト全23件が指定できます。

システム定義型ディレクトリ

設定オブジェクトに限定させたい場合、object修飾子に/system/types/Configを指定します。

なお、特定ディレクトリ配下の設定オブジェクトのみ参照させる場合は、directory修飾子を使用して参照できるディレクトリを制限します。
下記の例ではフォームと同じディレクトリ下にあるConfigsフォルダの設定オブジェクトに限定しています。

独自に定義した型オブジェクトに制限する

システムで定義されている型オブジェクトと同様に、object修飾子に独自の型オブジェクトを指定します。
下記の例では、同じディレクトリ下にあるSampleTypeを型オブジェクトに指定しています。

 


Object型フィールドで未選択を許可しない(no_empty)

フィールド修飾子no_emptyを指定することで、Object型フィールドのオブジェクト選択を必須とします。
以下のように設定します。

 


アップロード可能なファイル形式を制限する(file_accept)

File型フィールドを使用する際に、利用するファイルの拡張子を制限したい場合があるかと思います。
フィールド修飾子file_acceptを指定することで、File型フィールドに制限をかけることができます。
フィールド修飾子file_acceptに制限したいファイルの拡張子を指定する際は、”.拡張子”形式で指定します。
下記の例では、.txt形式の選択のみ許可します。

フィールド修飾子を設定すると、下記のようにファイル選択ダイアログ上で選択可能なファイル形式が制限されます。
これにより、誤った形式のファイルの指定を防ぐことが出来ます。

 

ただし、ダイアログ上のファイル形式の種類(上記画像では「Text Document」の部分)はユーザーで変更可能です。
より厳格に制限するには、フォームであれば、file_acceptの設定と合わせて、ジョブフロー側でのファイル形式チェック処理(下記)を設けます。

 


まとめ

本記事では、制限に関するフィールド修飾子の使い方をご紹介しました。
フィールド修飾子を設定することで、人間の操作が必要な場面での入力負担の軽減や入力ミスの防止が期待できます。
型オブジェクト、設定オブジェクト、フォームを用意する際は、合わせてフィールド修飾子の使用もご検討下さい。

KompiraからWindowsGUIアプリケーションを操作する (1/2)

運用の中で既に利用されているアプリケーションを自動化することができれば、運用効率の向上が期待できます。しかし、そのアプリケーションのインターフェースがGUIしか存在しない場合、それを自動化することは容易ではありません。

そこで本稿では、「KompiraからWindowsGUIアプリケーションを操作する」方法(全2回)を紹介します。
初回である今回は、Windowsアプリケーション操作ライブラリFriendlyを用いて、Windowsの代表的なアプリケーションの「メモ帳」を操作します。
2回目は、KompiraからWindowsに接続し、メモ帳を操作する方法を紹介します。

図: 全体像

Windowsアプリケーションの自動操作

Windowsアプリケーションを自動操作する方法には、以下の2種類の方法が考えられます。

・マウスやキーボードをエミュレートする
・ボタンやテキストボックスなどUI要素にアクセスし操作する

ここでは、 時刻や内部データに応じて、UIの表示量や表示順が変わる場合でも、確実に操作できる「UI要素にアクセスし操作する」方法を取り上げます。

Friendly

Friendlyとは、Codeer社が開発したWindowsアプリケーション操作用ライブラリです。Friendlyを使用することで、対象アプリケーションに別のプロセスからアタッチし、操作することができます。

Friendlyによるメモ帳の操作

以下は、「メモ帳」の編集欄に任意の文字列を入力するコンソールアプリケーションのコードです。
このアプリケーションを実行すると、メモ帳を触ることなく、メモ帳に”buz”という文字列を表示することができます。

Friendlyライブラリの読み込み

Friendlyのライブラリを読み込みます。

Friendlyはnugetに登録されているので、プロジェクト設定ファイル.csprojに以下の設定を追加することで、使用することができます (※)。

※ または、以下のように開発環境上で以下のコマンドを実行すると、.csprojに自動的に上記が追加することができます。

プロセスへアタッチ及び構成要素へのアクセッサ取得

プロセスIDを指定し、メモ帳のプロセスへアタッチします。
メモ帳は、下図のように、「編集欄」と「ステータスバー」から構成されます。

図: メモ帳の構成

編集欄のIDを指定し、アクセッサ(text_edit)を取得します。

構成要素のIDを取得するためには、別途、アプリケーションの解析が必要となります。
アプリケーションの解析方法については、後ほど説明します。

編集欄への書き込み
取得したアクセッサを使い、文字列を編集欄へ書き込みます。

アプリケーションの解析

構成要素を指定・操作するためには、対象となる要素のIDを知っておく必要があります。IDは、専用のツールを用いてアプリケーションを解析することで得ることができます。

TestAssistant
TestAssistantはCooder社が提供するGUI解析用ツールです。以下からダウンロードすることで使用することができます。

https://www.codeer.co.jp/CodeAndTool

TestAssistantによるメモ帳の解析

それでは、TestAssistantを使って、メモ帳を解析してみましょう。

1. メモ帳を起動します
2. TestAssistantを起動します
3. メモ帳にアタッチします

テスト対象プロセス選択ボタンを押して、対象アプリケーション(=メモ帳)にアタッチします

4. 要素の解析を行います
4.1. トップレベルウインドウ解析ボタンを押下します

4.2. 中央ペインで、編集欄をクリックすると、右ペイン下の表に指定した要素の情報が記載されます

本稿では、DialogId=15を用いて、記入欄の要素にアクセスします(※)

※ 要素のIDには、複数の種類が存在します。アプリケーションによっては、同じIDを持つ構成要素が存在するため、状況に応じてIDを使い分けてください。

TestAssistantによる操作のキャプチャ

TestAssistantには、アプリケーションの操作をキャプチャする機能が存在します。この機能を用いることで、アプリケーション操作の実装が簡単になるため、覚えておいた方がよいでしょう。

1. メモ帳、TestAssistantを起動し、メモ帳にアタッチします
2. 「操作によるコード生成ボタン」を押下します

3. メモ帳の編集欄にフォーカスし、文字を入力します

4. 操作によるコード生成ウインドウに入力した文字列を入力する操作のコードが生成されます

5. OKボタンを押下すると、TestAssistantの左ペインに、以下のような「メモ帳の編集欄に文字列を追加する」操作のコードが追加されます。

まとめ
本稿では、Friendlyを用いてメモ帳を操作する方法を紹介しました。この方法を応用することで様々なWindows GUIアプリケーションを自動的に操作することができます。

次回は、今回説明した方法を拡張し、Kompiraからメモ帳を操作する方法をご紹介いたします。

メールを送信する

サーバー監視でエラーが発生した場合は、ルーチンの処理の成否など、運用の現場では処理の結果を把握しておきたいケースが多々あります。今回の記事ではKompiraからメールを用いて通知を行う方法をご紹介します。

今回の記事では「簡単なWebサーバーの監視をする」ジョブフローを利用し、エラーが発生した場合には指定の担当者にメールで通知するジョブフローを作っていきます。

Kompiraよりメールを送信する際にはmailto()を使用します。ここで文字列で記載された表題、文面などで指定されたアドレスに送信されます。

このように各項目に指定をすると”tantou@sample.co.jp”宛にメールが送信されます。

mailto()の引数は以下の様なものがあります。各項目の詳細はKompiraドキュメントを参照ください。

さて、Webサーバーの監視ジョブフローは次のようなものでした。

ここでprint()での表示の代わりにmailto()で置き換えてみましょう。

このようにしてジョブフローの処理結果の通知などをメールで送信する事が出来ます。

mailto ジョブで送信したメールの User-Agent ヘッダは “Kompira verX.XX” となります。”X.XX” の部分は Kompira のバージョンが入ります。また、メールの送信はKompiraサーバーのpostfixを通じて行われます。Kompiraからの通知メールが迷惑メールに振り分けされるような場合には、spf認証設定などを別途行う必要があります。

メール受信をトリガーにしてジョブフローを実行する

運用の現場ではSlackのようなメッセンジャーアプリが利用されてきていますが、メールによる通知もまだまだ多いと思います。具体的には、システム側でのcronによる処理結果や監視ツールからのレポートなどがメールで通知されてくるケースがあります。今回はKompiraがメールサーバーよりメールを受信し、その内容によってメンテナンス処理を実行する方法をご紹介します。

ここでは、メールサーバーよりIMAP4/POP3プロトコルを通じて、メールを取り込む「メールチャネル」を利用します。メールチャネルは設定されているメールサーバー(IMAP4/POP3サーバー)をチェックし、メール受信をした場合にはそのメールを取得し、ジョブフローに渡します。この際に受信したメールはメールサーバーから削除されます。メールチャネルはあらかじめ指定された時間間隔でメール受信のポーリング処理を行います。

 
動作確認環境

ソフトウェア バージョン
Kompira 1.4.10.post2

 
メールチャネルの作成

「メールチャネル」はジョブフローと同様に、管理画面から作成します。この際に型指定のプルダウンでは「メールチャネル」を指定します。ここでは「mchan」という名前で作成します。

メールチャネルの作成

次のようなメールチャネルの設定画面が表示されます。

メールチャネル設定画面

 

フィールド 説明
サーバー名 IMAP/POP3サーバーをホスト名かIPアドレスで指定
プロトコル メール受信のプロトコルとしてIMAP/POP3のいずれかを指定
SSL SSLによる通信を行う場合に有効化します。
ポート番号 受信のポート番号を指定します。指定が無い場合にはデフォルトのポートが使用されます。
ユーザー名 メールサーバーのユーザー名を指定
パスワード メールサーバーのパスワードを指定
受信チェック間隔 新着メッセージを確認する間隔を分単位で指定します。デフォルトは10分で、「0」を指定するとデフォルト値が指定されます。負の値を指定した場合は新着メッセージの確認を行いません。
無効 メールサーバーへの接続を無効にします
ログサイズ ログの最大サイズを指定。最大サイズを超えた場合には古いメッセージから削除されます。(ログはメールチャネル画面の”ログ”タブで閲覧可)

 

 
メールを受信するジョブフローの作成

作成したメールチャネル”mchan”をジョブフロー中で利用する際には、”<./mchan>”のように、<>で囲みます。受信したメッセージの内容は$RESULTに格納されます。

メッセージの内容はヘッダー部分も本文部分も一緒になっているため、mail_parse() という組み込み関数を利用して、辞書型のデータに変換します。メールのヘッダー情報に加えて”Body”キーでメールの本文、”Filename”キーで添付ファイル名にアクセスできます。またメールの本文はContent-TypeがText/Plainで添付ファイルが無い場合に限りutf-8形式にエンコードされます。Content-Typeがmultipartの場合は”Is-Multipart”キーがtrueになり、”Body”キーの要素が辞書オブジェクトの配列になります。

上記のジョブフローを一部修正して、メールの表題が”DOWN”であった場合には、指定のサーバーのプロセスを再起動するジョブフローを呼び出すようにしてみます。

「プロセス再起動」は「ジョブフローから別のジョブフローを呼び出す」で作成したジョブフローをそのまま使いましたが、もちろん他の処理を記述していただいても構いません。(関係者への通知、チケットシステムへの投稿、予備系への切り替えなど)

 
ジョブフローの常駐化

上記で作成したジョブフローはメールを1通処理して終了となりますが、これを継続的に行なえるように変更してみましょう。
繰り返しの処理を指定するためにwhileブロックを使用し、あわせて何らかの原因で受信処理に異常が発生した場合でも全体が強制終了しないように、tryブロックを追加します。

このジョブフローを実行して、メールを指定のアドレスに送信すると、以下のような結果となります。このジョブフローは無限ループとしているので、停止させる場合は手動で「中止」ボタンをクリックする必要があります。 (プロセスが実行中であるかどうかはKompira画面上部の「プロセス一覧」メニューで確認することができます。)

メール受信処理

メールチャネルを利用する際、ポーリング処理でメールを取り込んだ後は、メールサーバー上から該当のメールが削除されることに注意してください。今回の記事で紹介したようなメール連携を行う場合、連携処理専用のアカウントをメールサーバーに作成し、そのアドレスに対してメールを送信することを推奨しています。

アラートメールをフィルタリングして転送する

Unix/Linux系OSではシステムのセルフチェックを行い、結果を管理者にメールで通知するといった仕組みが動いています。また、システム管理ツールがサーバ監視を行い、異常時にはアラートメールを送信するように設定しているケースも多くあります。しかし、管理しているサーバー数が多いとメールの数も膨大となり、すべてに目を通す事は現実的ではありません。そのため、受信したメールのうち警告の通知だけを読みたい、もしくは障害通知だけ受け取れればよいといった要望があります。

今回は、受信したメールのうち差出人やタイトルが一定のパターンに一致するものをフィルタリングし、転送するジョブフローを作成します。

動作確認環境

ソフトウェア バージョン
Kompira 1.5.0
LinuxOS CentOS7.5_1804

メール転送の設定

ここでは、メールサーバーよりIMAP4/POP3プロトコルを通じて、メールを取り込む「メールチャネル」を利用します。取得の際、メールはサーバーから削除されます。またKompiraのメールチャネルがチェックできるアカウントは1つであるため、メールサーバーにKompira用のメールアカウントを作成し、そのアカウントにメールが転送されるように設定を行ってください。

メールチャネルの設定

まず、メール受信を行うためのメールチャネルを作成します。
先程設定した転送先のメールアドレス宛のメールを受信する、 ”メール受信チャネル”という名前のメールチャネルを作成します。メールチャネルの詳細については、「メール受信をトリガーにしてジョブフローを実行する」にて紹介しております。

メールを処理するジョブフローの作成

ここでは
(1)メールアドレスを抽出するジョブフロー
(2)メールを転送するジョブフロー
(3)メールサーバーから受信し、他のジョブフローを呼び出すジョブフロー
の3つを作成します。

(1) メールアドレスを抽出するジョブフロー

メールアドレスの形式としては “taro@example.jp” といったアドレスだけを記載したものと、 “コンピラ太郎 <taro@example.jp>”のようにアカウントの名前が併記されているものがあります。アカウント名が併記されている場合にはFrom行からアドレス以外の項目を除外します。

次のジョブフローを「アドレス抽出」という名前で作成します。

3行目では、正規表現を用いて< >で囲まれた部分をメールアドレスとして取り出すためのパターンを記述しています。パターン型データのメソッド match( ) は、 文字列と正規表現がマッチすればその情報を辞書型にして返し、マッチしなければfalseを返します。ここでは< >で囲まれていなかった場合は全文を、囲まれていた場合はその中身を取得しています。

(2) メールを転送するジョブフロー

メールの転送は mailto()関数を使って行います。詳細については「メールを送信する」を参照してください。メールが平文の場合はmailto()関数でそのまま送信することができますが、メッセージがHTML形式ものなど追加の処理が必要になる場合があります。

最初に、受信メールを扱いやすくするためにmail_parse()関数を用いて辞書型データに変換します。本文の内容はキーワード”Body”で取得できます。メールが平文の場合(Content-Typeが”text/plain;”の場合)は

のようになりますが、HTML形式のメッセージと一緒に送られる場合(Content-Typeが”multipart/alternative;”の場合など)は

のように平文とHTMLがそれぞれ配列の要素として格納されます。 このため、Body要素で渡されたデータが文字列の場合はそのまま処理を行い、配列の場合はそれぞれの要素を抽出して処理を行います。 この処理を行うジョブフロー「メール転送」を次のように作成します。

このジョブフローではtype()関数を用いて、本文の型をチェックしています。平文の場合には”String”という文字列が返りますので、このままmailto()関数のbodyパラメータに渡します。それ以外の場合は配列と判断し、平文部分をbodyパラメータに、HTML部分をhtml_contentパラメータに渡します。

(3) メールサーバーから受信し、他のジョブフローを呼び出すジョブフロー

ここでは、作成したメールチャネルとジョブフローを組み合わせ、実際に転送を行うジョブフローを作成します。
条件として
(1) タイトルに”ALERT”または”WARNING”という文字列を含む
(2) 差出人が “loginaccount@system.local”である
の両方を満たす場合にメールを転送するものとします。
メールの差出人は適宜変更してください。
条件を満たさない場合には”スキップします”というメッセージを表示して次のメールを処理します。

転送条件として各ヘッダーの項目や本文の内容などを用いる事が出来ます。例えば受信日時は msg_dict.Date で参照することができます。本文を処理する際にはジョブフロー「メール転送」で見てきたように、HTML形式のメッセージの扱いにご注意ください。システムから送信されるメールが対象の場合はほぼ全てが平文のメールであるため、HTMLを含むメールを無視しても問題は少ないと思われますが、処理する対象によっては重要となります。

また本文の構造が複雑な場合には、Kompiraジョブフローのパターンマッチングだけでは難しい場合があります。その場合はKompiraのライブラリ型オブジェクトを使うことで、Python言語の文字列処理関数を利用できます。ライブラリ型オブジェクトについては、「Pythonで記述された処理をKompiraから呼び出す」を参考にしてみてください。

Kompiraでの文字列のパターンマッチング

Kompiraがチャネル、メールチャネル、API、kompira_sendevtモジュールなど、外部から受信したデータを解析して、ジョブフローの処理の起動を行ったり、処理条件を変える事があります。このような場合には受信した文字列を解析するために、文字列のパターンマッチングが必要となります。

動作確認環境

ソフトウェア バージョン
Kompira 1.5.0

Kompiraでパターンマッチングを行う場合には、パターン型オブジェクトを利用します。パターンの種別は、’r’ (正規表現パターン)、’g’ (glob パターン)、’e’ (完全一致パターン) の3種類があります。また、パターンマッチングを行う場合、大文字、小文字を区別しないモード (‘i’) を組み合わせることもできます。

パターン型オブジェクトを作成するには、組み込み関数”pattern()”を利用します。

引数:

■ pattern は、マッチングを行うパターンを指定します。
■ typ はパターンの種別を表し、 “r” (正規表現パターン)、”g” (glob パターン)、”e” (完全一致パターン) のいずれかを指定することができます。
■ mode には、”i”を指定すると大小文字を区別しないパターン照合となります。指定しない場合は、大小文字を区別します。

戻り値:
■ パターン型オブジェクト(ptn_obj)を返します。

パターン型オブジェクトは、文字列 s とパターンとのマッチングを試みるmatch()メソッドを備えています。

引数:

■ sは、マッチング対象の文字列を指定します。

戻り値:

■ マッチした場合は true、もしくはパターンが正規表現パターンの場合はマッチした情報を格納した辞書を返します。
■ マッチしなかった場合は、false を返します。

続いて、ログファイルの行をサンプルにして、各マッチング種別の動きを見ていきましょう。


完全一致パターン

完全一致パターンは、対象の文字列とパターンで指定した文字列が一致するかを確認します。
対象の文字列とパターンで指定した文字列が一致する場合はtrue, 一致しない場合にはfalseを返します。

上記の場合、ptn_1とのマッチング結果は結果は、trueとなり、ptn_2とのマッチング結果は、falseとなります。

rst_e_match

完全一致パターンは、以下のように単純な文字列比較として記述することもできます。


globパターン

globパターンでは、Unixのシェル形式のワイルドカードを用いることができ、以下の特別な文字に対応しています。

■ * すべての文字にマッチ
■ ? 任意の一文字にマッチ
■ [seq] seq にある任意の文字にマッチ
■ [!seq] seq にない任意の文字にマッチ
■ *、?、[などの特殊文字をエスケープしたい場合は、[*]、[?]、[[]のように[]で囲って記述する

ログに”[warn]”という文字列が含まれているかを判別する処理は、以下のよう(“*[[]warn[]]*”)に、globパターンを用いて記述することができます。
match()は一致する場合はtrue, 一致しない場合にはfalseを返します。以下の例では、ptn_1はtrueを返しますが、ptn_2はfalseを返します。

globパターンは、比較的単純なマッチングにおいて有効な方法です。


正規表現パターン

正規表現パターンは、プログラミング言語 Python の re モジュールの正規表現に準じています。
また、match()メソッドの応答は、完全一致やglob型と異なり、マッチした場合は、マッチした情報を格納した辞書を返します。( )でくくったグループごとに、マッチした文字列を返します。
(マッチしなかった場合は、”false”を返します)
以下の処理では、ログ取得の日時、ログレベル、メッセージの3つの情報にマッチさせて、それぞれ個別に表示します(ptn_1)。
マッチした文字列は応答中のgroupsに格納されます。マッチしない場合は、falseが返ります(ptn_2)。
特殊文字をエスケープしたい場合は、\をエスケープしたい文字の直前に記述します。

img_No-0198

正規表現でのマッチングは、glob型より複雑ですが、より細かい条件設定を行うことが出来ます。


パターンリテラル

これまではマッチングパターンのオブジェクトを作成するためにpattern()関数を利用してきました。
Kompiraでは、pattern()の代わりに、パターンリテラルを用いる事も出来ます。
パターンリテラルは、パターンの種別を表す ‘e’, ‘g’, ‘r’ のいずれかの文字に引き続き、一重引用符(‘)、もしくは、二重引用符(”)で囲まれた0個以上の文字(パターン文字列)で表現されます。

上記の「正規表現パターン」のジョブフローは、パターンリテラルを用いると以下のように既述することができます。

実行結果はpattern()を使った場合と同様になります。正規表現以外にも完全一致、glob型の場合も同様に記述する事が出来ます。


正規表現パターンの名前付きグループ

正規表現を利用してパターンを使って値を参照しようとする場合、値はgroupsという配列に格納されているため、パターン中の順序を意識する必要があります。
Kompiraでは、各パターンのグループに明示的に名前をつけることで、名前を用いて値を参照することができます。

名前つきグループのための構文は、固有拡張の一つ: (?P…) を使います。
上記の「パターンリテラル」のジョブフローを以下のように書き換えることで、名前付きグループを用いることができます。

それぞれの要素に”timestamp”, “level”, “message”という名前を付けています。
出力は、以下のようになります。

regex_title_ret

マッチさせた文字列は、groupdictという辞書に指定した名前をキーにして格納されていますので、上記の例では”match_rst.groupdict.timestamp”のように参照できます。

このようにしてパターン型オブジェクトやパターンリテラルを用いることで、文字列のパターンマッチングを行うことができ、文字列から必要な情報を取得したりするなど、文字列の解析を行うことができます。

チャネルを利用して外部システムからデータを受信する

メール受信をトリガーにしてジョブフローを実行する」では、Kompiraでメールを利用する方法をご説明しました。
今回の記事はKompiraの「チャネル」を用いて、外部システムからKompiraに情報を送信する方法をご紹介します。

「メールチャネル」では外部のメールサーバーに対してポーリングをかけ、メールサーバーからメールを受信する動作をしますが、「チャネル」は外部からデータが送られてくるのを待機するという動きになります。「チャネル」にデータを送るのは専用のツール「kompira_sendevt」を用います。

 
Linuxへのkompira_sendevtインストール

まずはデータを送信するためのツールを用意します。次のようなコマンドで必要なモジュールをインストールします。

<version> はkompiraのバージョン(例えば1.4.8)を、
<Kompiraサーバー名> はKompiraサーバーのホスト名、またはIPアドレスを指定します。

ここまで実行できましたら、/opt/kompira/bin 以下に”kompira_sendevt”コマンドが配置されます。必要に応じてパスを通す設定を行ってください。

 
Windowsへのkompira_sendevtインストール

windowsでは動作のためにPythonの動作環境が必要となります。この記事執筆の時点ではPythonは古いバージョン2系と新しいバージョン3系がメンテナンスされています。これらはプログラムの記載方法などで差がありますが、今回はバージョン2系を利用します。

1. Python のインストール
Python2系 を Windows にインストールします。 (この記事の執筆時点での最新バージョンは 2.7.11) 公式ダウンロードサイト( (https://www.python.org/downloads/windows) からPython2系の最新パッケージをダウンロードしてインストールしてください。

インストールが完了したら、コマンドラインから Python が起動できるように、環境変数のパスを追加しておきます。

2. easy_install コマンドのインストール

Python の easy_install コマンドをインストールします。
https://bitbucket.org/pypa/setuptools/raw/bootstrap/ez_setup.py

上記のリンクを右クリックして保存します。ダウンロードしたら、コマンドラインを起動し、該当のファイルのあるところまで移動してから、以下のように実行します。

これで、easy_install コマンドがインストールされます。

3. kompira_sendevt パッケージのインストール

Kompira パッケージを Windows 上にダウンロードして展開し、展開したディレクトリに移動してから、以下のコマンドを実行します。(インストールしたPythonのバージョンに合わせてパス名を修正してください。)

以上で、イベント送信パッケージのインストールは完了です。以下のようにwindowsのコマンドコンソールで kompira_sendevt コマンドを実行してバージョン番号が表示されることを確認してください。

すでにAnacondaなどのパッケージでPythonの実行環境がインストールされている場合、上記のコマンドを参考に、個別にパッケージのインストールを行ってください。

 
ジョブフローでチャネルを扱う

ここまででデータの送信側の設定を行ってきましたが、今度は受信側のジョブフローの記載を行っていきます。ここではKompiraのデフォルトのチャネル 「/system/channels/Alert」を利用して、下記のようなジョブフローを実行します。

上記のジョブフローを実行しますと、実行画面の右側の「プロセス情報」のステータスは「待ち」状態になり、コンソールには実行中の表示と、データを受信した際には受信したメッセージが表示されます。
(このジョブフローを停止させるには「中止」「停止」ボタンを利用してください。)

次にkompira_sendevtコマンドをインストールしたサーバーからデータを送信します。次のようなコマンドを実行してみてください。

数秒後にkompiraのコンソールには以下のような表示が現れます。

上記のように “key=msg”というデータを送信すると、{ } でくくられたkey-value関係の辞書型のデータとして格納されます。また、この値は複数を送る事が出来ます。

 

次にデータをコマンドラインのパイプを使って送り込んでみます。

するとコンソールの表示は以下のようになります。

このように、パイプで送られたデータの場合には辞書型ではなく、通常の文字列として受信します。

「処理のトリガーとなるようなメッセージを送信する場合にはコマンドラインから送信する」「コマンドの出力結果などを送る場合にはパイプを利用する」といった使い分けをしてみてください。

チャネルで受信したデータにより、ジョブフローを起動するには、例えば下記のようにジョブフローを修正します。

ここで

というようにデータを送信すると、[./プロセス再起動]というジョブフローが実行される事になります。(ここでは仮に、[./プロセス再起動]が、再起動の対象となるサーバー名を引数にとることを想定しています。)

 
独自のチャネルを作成する

ここまではkompiraのデフォルトで用意されたチャネル”Alert”を利用してきましたが、これだけでは様々な機器や条件で受信したデータを振り分けるのに複雑になります。独自のチャネルを用意する方法をご紹介します。

方法は非常に簡単で、ジョブフローを作成するのと同様に、名前を指定し、型を「チャネル」にしてオブジェクトを作成します。

独自チャネルの作成

作成後は特に何かを設定する必要はありません。このチャネルを利用して先のジョブフローを書き換えると以下のようになります。

このジョブフローはデフォルトの”Alert”チャネルを用いた場合と機能的には差がありません。ただし、データを送る側では明示的にチャネルを指定する必要があります。

同一のチャネルを複数のジョブフローから利用する事も可能ですが、その際には最初に処理したジョブフローだけがメッセージを処理する事になります。このため実務面から見ますと、ジョブフローの用途に応じて、送信側のサーバーごと、または発生させるイベント種別ごとにチャネルを作成すると、受信データの扱いが楽になりますし、思わぬ事故を防ぐ事になります。

チャネル自体は、それを利用するジョブフローの有無や、ジョブフローが動作中/停止中などの状態に関係なく、データを受信します。また受信したデータは内部的にはメッセージキューに格納され、受信順にFIFO(First-in-First-out)で処理されます。

このように外部のサーバーからkompiraにデータを送る手段をご用意してありますので、運用ツールと連携させたり、スクリプトから呼び出して、kompira上のジョブフローを制御してみてください。

Kompira上でWikiページを作成する

運用チームでKompiraを共有して利用する場合、作業手順などの情報をKompiraで共有して閲覧できるようにするために、Wikiを作成することが出来ます。例えばオペレータ向けに確認事項やジョブフローへのリンクをまとめておくと重宝するでしょう。
またジョブフローを実行して得られた情報などもWikiに自動的に記録しておくこともできます。

 
Wikiの作成

新規のジョブフローを作成する場合と同様に、Wikiページ型のKompiraオブジェクトを作成します。ここでは「作業手順」という名前で作成してみましょう。
Wikiの作成

次のような編集画面が表示されます。
Wiki編集画面

Wikiでメモを書いていくには、単純にテキストを書いていく他に、「スタイル」と呼ばれる一定の記法に従って書くと、太字、イタリックなどの表示、表の作成、外部リンクの作成などが出来るようになります。
「スタイル」では(1) Creole(デフォルト) (2) Markdown (3) Textileの三種類のWiki記法から選択する事が出来ます。各記法の詳細については、画面の「Wikiテキスト」欄の下に、それぞれリンクがありますので参照してください。
ここでは昔からWikiに利用されているCreole記法を使っていきます。

簡単な例として、Wikiテキスト欄に次の様に記載してみます。

保存ボタンをクリックすると、次の様に表示されます。

Wiki画面

上記の例では、行の先頭に “#” を記載すると番号付きリストになり、[[ ]] で囲んだパスはリンクになるCreole記法の例です。
このようにして手順の解説とジョブフローへのリンクをまとめておくと便利でしょう。

 
ジョブフローからWikiに保存する方法

Wikiオブジェクトのフィールドを調べると、”wikitext”フィールドがwikiページのテキストを格納します。
Wikiオブジェクト

さて既存のWikiオブジェクト “Wikiページ”が存在しているとして、この”Wikiページ”の内容をジョブフローから変更するのは、次の様にします。

“Wikiページ”にメッセージを追記していくのは次の様に、いったん内容を変数に保存して、追記文字列を結合した後に、改めてwikitextフィールドに書き戻します。(下記の例で’\n’は改行を表します。)

上記のように、ジョブフローより既存のWikiページの内容を書き換える事が出来ます。取得したシステムの情報や、作業記録を追記していくような用途などでご利用ください。

Webページから内容を取得する

デスクトップでの作業を自動化するためにRPA (Robotic Process Automation) が広く知られています。しかし、ブラウザを通じたWebアプリケーションの操作であればブラウザとサーバ間の通信を模倣するだけで再現することができます。例えば特定のフォームに値を入力して送信するような操作や、Webページから値を抽出するスクレイピングのような操作を行うことができます。

ここではKompiraを用いて通信を模倣することで通常はブラウザ画面を用いて行う作業を自動化します。今回はWebサイトから内容を取得し、フィルタリングして表示するジョブフローを作成します。

htmlファイルを扱うためにPythonのライブラリであるBeautiful Soup4を使用します。ライブラリの使用に関しては「Pythonで記述された処理をKompiraから呼び出す」の記事にて紹介しています。このライブラリを用いて本コラムのタイトル一覧を取得します。

動作確認環境

ソフトウェア バージョン
Kompira 1.5.0
LinuxOS CentOS7.5_1804

Pythonライブラリの準備

まずPythonライブラリであるBeautifulSoup4を導入します。Kompira1.5では/opt/kompira/bin/pipを使用してライブラリをインストールします。
Kompiraサーバにログインし、以下のようにしてインストールします。

インストール後、つぎのコマンドを実行し情報が表示されればインストールされています。

htmlリソースの取得

まずKompiraの組み込み関数であるurlopen()を使いHTTPリクエストを送信して結果を取得します。urlopen()の詳細に関しては「簡単なWebサーバの監視をする」の記事にて紹介しています。今回はKompiraの運用自動化コラムのページのhtmlソースを取得するのでつぎのジョブフローを作成します。

取得に成功していた場合200が表示されます。

Kompiraライブラリの作成

今回はコラムページからタイトル一覧を取得するライブラリを作成します。ライブラリはHTMLリソースを取得するジョブフローと同じ階層にKompiraWebpageAnalyzerという名前で作成します。
ブラウザ付属のツールを用いてウェブページの内容を確認します。ここではChromeのデベロッパーツールを使って取得しています。

チャネルを利用して外部システムからデータを受信するというタイトルはつぎのような内容であることがわかります。

タイトルのタグとクラスがわかったので、タグが<a>でクラスが”qa-q”である要素を取得するライブラリを作成します。

ただこのままではタグ等がついたままで扱いづらいので、タイトル以外を除去して取得する関数をライブラリに追記します。

タイトル一覧の取得
作成したライブラリを使用してタイトル一覧を取得するようにジョブフローをつぎのように作成します。

実行に成功すればつぎのようにコラムのタイトル一覧が表示されます。

本記事ではコラムサイトのhtmlソースからタイトル一覧を取得しましたが、htmlソースの他のタグやクラスを指定することで様々な情報を取得することができます。例えばテーブルの内容を取得し、行ごとに処理する事ができます。取得したいデータがどのようなタグやクラスを持つか確認することでその値を取得し、自動で処理することが可能になります。

Redmineへ新規チケットを登録する

チケット管理システムにチケットが登録された場合にKompiraから何らかの処理を行わせたり、逆にKompiraの処理結果よりチケットを新規登録、内容更新を行いたい場合があると思います。今回の記事では代表的なチケット管理システム”Redmine”に新規チケットを登録する方法をご紹介します。
(既に動いているRedmineサーバーがあり、管理者権限で作業できることを想定しています。)

※本記事の内容の動作確認にはRedmine3.2.4を使用しています。

 
Redmineプロジェクトの作成

まずは新規のプロジェクトを作成しました。名称を”kompira-project”としています。
redmineのプロジェクト

 
RedmineのAPI設定

KompiraからはRedmineのREST APIを呼び出してチケット操作を行います。この際には以前の記事で紹介したKompiraの組み込み関数urlopen()を使用します。またAPI呼び出しの結果はJSON形式で応答がありますので、パースする必要が出てきます。

まずはRedmineのREST APIを有効にしていきます。
[管理] -> [設定] -> [API]
この画面で「RESTによるWebサービスを有効にする」を選択して「保存」をクリックします。

API有効化

次にAPIアクセスキーを取得します。
[個人設定] -> [APIアクセスキー] -> [表示]

APIアクセスキー
※表示されない場合には[リセット]をクリックしてみてください。
表示されたキーをテキストエディタにコピーしておきます。

 
新規チケットの投稿

RedmineのAPIは次のページで調べる事が出来ます。
http://www.redmine.org/projects/redmine/wiki/Rest_api
http://www.r-labs.org/projects/r-labs/wiki/Redmine_REST_API (日本語)

これによると、チケット登録のAPIは
http://(redmineのURL)/issues.json
であることが分かります。(.json は応答のフォーマットを表します。)

このAPIをurlopen()を使って呼び出すジョブフローを作成します。

ここではパラメータ”redmine_url”は、RedmineサーバーのURLに”/issues.json”をつけます。
“access_key”はRedmineの管理画面からコピーしたAPIアクセスキーの文字列を指定します。
“project_id”は作成したプロジェクトのIDを指定します。
“ticket_title”は、これから作成するチケットの表題となる任意の文字列です。

プロジェクトのIDを確認するため、http://(redmine)/projects.xml にアクセスすると、プロジェクトの一覧が表示されます。
作成したプロジェクトに該当するidを確認してください。

上記の場合、”kompira-project”は1、”testproject”は2となります。

さて、このジョブフローを実行するとRedmineに新規チケットが作成されます。
チケット登録完了

Redmineの画面では次の様になります。
Redmineの新規チケット

このように新しいチケットが登録されているのが分かるかと思います。

Kompiraのコンソールには、次の様なJSON形式のAPIの応答が表示されます。(表示の都合で改行を入れていますが、実際には1行で表示されます。)

JSON形式のままでは読みにくいため、少し整形して表示する場合には、ジョブフロー最後の

print(‘チケット登録結果\n’, result[‘issue’] )

の部分を、例えば次の様にして必要な項目を抜粋して表示します。(ID, ステータス、優先度を表示)

 

上記で見てきた通り、Redmine側のREST APIをKompiraからurlopen()で呼び出す事により、新規のチケットを発行する事が出来ます。今回作成したチケットはタイトルを指定しただけの簡単なものですが、ジョブフロー中の”dat”で指定するJSON形式のリクエストの中身を追加する事により、priority_id(優先度)、description(説明)、category_id(カテゴリ)などを直接指定することも可能です。(詳しくは先に紹介したAPI仕様をご覧ください。)

またチケットの新規作成以外にも、チケットの更新・削除、一覧表示なども可能です。各APIごとに定められたURLと、HTTPメソッドの指定を適切に行うことで実行することができます。(こちらも詳細についてはAPI仕様をご覧ください。)

ここではRedmineへのチケット登録の例をみてきましたが、ジョブフローに組み込む事で、Kompiraを利用した作業結果や監視結果などによりチケット発行を自動で行う事ができます。

ディスクの容量をチェックする

今回はターゲットのサーバーにログインしてディスクの利用状況を調べ、利用率が一定の水準を超えて溢れそうであれば警告の表示を行うジョブフローを作成していきます。

先に、リモートサーバーに接続する設定を行います。詳細は「[事前準備] 接続先のサーバーを登録する」をご覧ください。「server1」という名前の「ノード情報」のオブジェクトが作成されているものとして進めます。

まずはリモートサーバーでコマンドを実行する書き方から確認していきましょう。「[事前準備] 接続先のサーバーを登録する」の接続確認のジョブフローです。

このスクリプトでは、リモートサーバーで”whoami”コマンドを実行して結果を表示します。
1行目: 制御変数 “__node__” (前後にアンダースコア “_” が2つ続いている事に注意)にノード情報のオブジェクトを代入します。
2行目: 実行したいコマンドを[” “] の中に記載します。
3行目: 直前処理の結果の標準出力が $RESULTに格納されるので、これを表示します。

さてディスク容量をチェックするためのコマンドを書いていくことにします。ここではdfコマンドを利用します。
実行例は次のようになります。

左から数えて5番目の使用率がしきい値を超えた場合に表示するようにしてみます。以下はディスク使用率が80%を超えた場合のみ文字列が表示される例です。

dfコマンドの出力をawkでフィルターしていますが、先頭行をカット、5番目の値が80を上回った行を表示しています。(awkコマンドの詳細はここでは解説しませんので、必要に応じてヘルプ等をご確認ください。)

このコマンドを使い、さらにif文で表示を出し分けてみましょう。どのファイルシステムも使用率が80以下なら”OK”を表示します。

しきい値が”80″に固定されていると変更しにくいので、これをパラメータ化してみます。

先のジョブフローは次の様になります。

Kompiraのジョブフローの画面が以下のように、パラメータの表示枠が増えています。実行の際には、この値を変更する事が可能です。(つまり、記載した”80″はデフォルト値の扱いになります。)
パラメータ枠

ここではチェック用のdfコマンドを実行して結果を表示してみましたが、これ以外のメンテナンス用のコマンドを実行することも可能です。また実行時に条件を変更する場合には、パラメータ化しておくと扱いが楽になります。

システム運用の実務においてサーバーの監視を行う場合は、nagiosやzabbixなどの監視ツールを使用することが多いかと思いますが、複数台あるサーバーのあるコマンドの実行結果をとりあえず見てみたいときや、何らかの事情で対象サーバーに監視ツールのエージェントをインストールできない場合に重宝します。

pingを使って簡単なサーバーの死活監視をする

ここでは指定のIPアドレスに対して、pingコマンドでICMPパケットを送り、サーバーが生きているか死んでいるかの確認を行うジョブフローを作ります。

まず指定のサーバーはパラメータ”target”で指定することにして、pingコマンドを実行するところまでは次のように書けます。

| | で挟んだ部分はパラメータで、実行時に動的に指定することが出来ます。= の右辺は初期値となります。ping には “-c1″オプションをつけています。これはpingコマンドの出力はCtrl+Cで中断するまで継続的に実行しつつけるため、繰り返し回数を明示的に指定する必要があります。
Kompiraは[ ] で囲った処理は、sshでログインして、コマンドを実行し、終了して戻り値が得られるまで実行完了を待ちます。繰り返し表示を続けるタイプのコマンドは明示的に回数を指定しないと、ジョブフローが「実行中」のまま完了しません。

続いて、pingの結果、正常の場合には”OK”、異常の場合には”NG”を表示するように条件文を書いてみましょう。
if文は次のような記述となります。

ジョブフローは次のようになります。

$STATUS変数は直前の処理の戻り値(終了ステータス)で、この場合にはpingコマンドの実行結果となります。if文の直前の矢印は “->”ではなくて、”=>”になることに注意してください。”->”では処理エラーが発生した場合にジョブフローが中断されますので、pingの応答がなかった場合にはif文が実行される前にジョブフローが異常終了します。

最後にpingの応答がなかった場合に、指定のメールアドレスに通知してみましょう。メールを送信するにはmailto()関数を利用します。ここでは簡単のために固定のアドレスに固定メッセージを送信します。

ここではtoのアドレスは通知先、fromは送信元のアドレスを記載します。

これをジョブフローに組み込むと次のようになります。

ここまで簡単ですがサーバー監視のジョブフローを作りました。Kompiraのスケジューラを利用してこのジョブフローを定期的に実行することで、サーバーがダウンした際に指定のアドレスに通知されるようになります。メールの送信先やメッセージの内容をジョブフローとは切り離して管理したい場合には、環境変数オブジェクトやメールテンプレートオブジェクトなどを利用することが出来ます。

スケジューラを使って定期的にジョブを実行する

定期的な監視や、日次のバックアップ取得など、システム運用業務において定期的に実行したい処理は多々あると思います。

今回の記事ではこのような定期処理を、Kompiraの「スケジューラ」の機能を使って設定をしていきます。

今回は別記事で作成したサンプルジョブフロー「WEB監視」を、毎日17:00amに実行する設定をしていきます。

 
1. 設定画面

スケジューラ

まずは画面右上の「スケジューラ」ボタンをクリックしますと、登録済の「スケジュール一覧」が表示されます。

ここで「スケジュールの無効化」チェックボックスが選択されていないものが「有効なスケジュール」に表示されます。

有効/無効を問わず、すべてのスケジュールは「全てのスケジュール」に表示されます。

 
2. 新規のスケジュール登録

新しいスケジュールを作成するには、一覧画面の「オブジェクトの新規作成」欄にスケジュールの名前を書いた後、その右側の「新規作成」ボタンをクリックします。

スケジューラー新規作成

ここでは名称を「定期WEB監視」としました。

次にスケジュールの内容を記載していきます。

スケジューラー編集

各フィールドの記載ルールは以下の通りです。

フィールド デフォルト値 説明
スケジュール名 なし スケジュールの名称
説明 なし スケジュールについての説明
ユーザー ジョブの実行ユーザー
ジョブ スケジューラにより実行されるジョブ(プルダウンよりジョブフローを選択)
* スケジュールを実行する年 (4桁の数字で指定)
* スケジュールを実行する月 (1-12を指定)
* スケジュールを実行する日 (1-31を指定)
ISO週番号 * スケジュールを実行する週 (1-53を指定)ISO8601で定められた週番号
曜日名もしくは曜日番号 * スケジュールを実行する曜日(0(月曜日)-6(日曜日)、または mon,tue,wed,thu,fri,sat,sunを指定)
* スケジュールを実行する時 (0-23を指定)
* スケジュールを実行する分 (0-59を指定)
スケジュールの無効化 false(チェックなし) trueの場合(チェックがつけられている場合)、ジョブを実行しない

「日付」の欄は空白になっている箇所は、可能なすべての値を取ります。例えば

となっている場合には、毎月1日に実行されます。

また時刻などで不正な値をいれた場合には、保存時にエラーメッセージが出ます。例えば、時刻に”25″を指定した場合には

とエラーが表示されます。

特定の曜日に実行させたい場合には、「曜日名もしくは曜日番号」に記載します。例えば、土・日に実行したい場合には

または

と記載します。

日付と曜日の2つを同時に指定した場合には、2つの条件を両方満たす日が実行日となります。
例えば上記のように「2016年毎月1日」かつ「sat,sun (土曜日,日曜日)」と指定した場合は5/1(日),10/1(土)にジョブが実行されます。

保存後、各スケジュールの画面の右側「スケジュール状態」で実行予定を確認することができます。

スケジューラー確認

 
3. 実行結果の確認

スケジュールで実行されたジョブの結果は「プロセス一覧」で確認できます。

スケジューラ-プロセス一覧

「プロセス一覧」ではログイン中のアカウントで管理しているすべてのプロセスを確認することができます。
また、各スケジュールの「プロセス一覧」タブでは、そのスケジュールによって実行されたプロセスのみを一覧で確認することができます。

ここではジョブのステータス、開始時刻、終了時刻、経過時間等が表示されます。また名称をクリックすることで、そのジョブのコンソール表示などを見ることが出来ます。

 
4. ジョブの無効化

障害復旧の最中や、登録したジョブを一時的に止めておきたい場合は、スケジュールの「スケジュールの無効化」オプションを使用します。
オプションにチェックを入れて保存することで、スケジュールの実行を行わない状態にすることができます。

スケジューラー無効化チェックボックス

以上がKompiraのスケジューラの使い方となります。定期的な作業をKompiraを用いて実行させる場合にご利用ください。

[事前準備] 接続先のサーバを登録する

Kompiraの基本的な機能の1つとして、リモートサーバーに対するssh(Windowsの場合はwinrs)で接続し、コマンドを実行するというものがあります。
「運用自動化コラム」の記事ではリモートサーバーへの接続を前提としたものが数多くありますが、そのためには作業の対象となるサーバーやネットワーク機器の接続先情報と接続の認証情報を登録する必要があります。
本記事では、コラム全体のための事前準備として接続情報の登録方法、使用方法を解説します。

 
制御変数を使う方法

Kompiraはリモートサーバーに接続する際にはssh (Windows機の場合にはwinrs)で接続します。
以下に示すのは、接続先のアドレスやID、パスワードをジョブフロー中に直接に記載する方法です。

ジョブフロー中で以下表の変数に文字列を与えると、それらを接続情報と解釈してリモートサーバー上でコマンド実行をします。

__host__ 実行ホスト名/IPアドレス
__user__ ログインユーザー名
__password__ ログインユーザーのパスワード

 

この方法は管理機器の対象やジョブフローが少ない場合やジョブフロー作成時のテスト等で気軽に使用することができますが、管理対象が増えてくるにつれて、認証情報の管理が大変になるという問題があります。
そのため、原則的に次の章でご紹介する「ノード情報」「アカウント情報」という形式で管理することを推奨しています。

 
ノード情報を利用する方法

1. アカウント情報の作成

まず接続先のアカウント情報を登録していきましょう。

次のオブジェクトを作成します。

名前 アカウント1
アカウント情報

アカウント情報

このオブジェクトの編集画面では、「ユーザー名」「パスワード」の指定をします。認証に鍵ファイルが必要な場合には、別途鍵ファイルのパスやパスフレーズを登録してください。

2. ノード情報の作成

次に接続先のサーバー(ノード)情報を作成します。

次のオブジェクトを作成します。

名前 server1
ノード情報

ノード情報

 

ここでは最低限、「IPアドレス」と「アカウント」を指定します。「アカウント」はプルダウンによる選択式になっていますので、先に作成した「アカウント1」を選びます。

3. 接続の確認

2.1, 2.2で設定した接続情報が正しく登録されたか確認してみましょう。

名前 接続確認
ジョブフロー

 

ソースコードは以下のようにしてください。(ここでは、ノード情報「server1」がジョブフローと同じディレクトリにある想定です。)

これで「アカウント1」で指定した「ユーザー名」が表示されれば問題なく接続できています。

この「運用自動化コラム」の記事では、特に指定がない場合には上記の「server1」を使って例示していきます。

簡単なWebサーバーの監視をする

今回はWebサーバーが公開するURLにリクエストを送り、死活監視を行うジョブフローを作成します。

処理の流れとしては以下のような想定です。
* 指定のURLにリクエストを送信し、応答がなければエラーを表示
* HTTPのステータスコードが200以外の場合にはエラーを表示
* 上記以外の場合には正常であると表示

まずWEBサーバーにリクエストを送信する方法ですが、Kompiraの組み込み関数urlopen()を使います。引数で指定した url に対して、HTTPリクエストを送信し、結果を取得します。

[ ] 内の引数は省略可能です。各引数の意味は以下の通りです。
(以下の仕様はkompira 1.4.8.post7のものです。使用しているkompiraのバージョンが異なる場合は、付属のドキュメントを参照してください。)

user, password Basic認証によるアクセスを行います。
data 送信データを辞書型の値として格納し、HTTPのPOSTリクエストを送信できます。
params 辞書を渡すと URL のクエリ文字列として展開されます。
例えばurlopen(url=’http://example.com‘, params={key1=’value1’,key2=’value2’}) とすると、
実際にアクセスする URL はhttp://example.com?key1=value1&key2=value2となります。
timeout timeout には、タイムアウトするまでの時間を秒単位で指定します。
encode エンコードタイプとして “json”を指定することができます。
data が指定され encode が “json” のとき、HTTP リクエストのContent-Type: ヘッダには自動的に application/json が設定されます。
encode引数を省略した場合、送信データはapplication/x-www-form-urlencoded形式でエンコードされます。
http_method HTTPリクエストのメソッドを’GET’, ‘POST’, ‘PUT’, ’DELETE’, ‘HEAD’のいずれかから指定します。
http_methodを省略した場合、dataが指定されていない場合はGETメソッド, 指定されている場合はPOSTメソッドとなります。
verify true を指定すると、指定した URL が https アクセスである時に SSL 証明書のチェックを行います。

不正な SSL 証明書を検出するとurlopen ジョブはエラーになります。verify のデフォルト値は false です。

quiet true を指定すると、verify オプションが true 時に、https アクセスした際に表示される警告メッセージを抑止します。
headers HTTPリクエストに設定するヘッダ情報を辞書型の値で渡すことができます。
cookies サーバに渡すクッキーを辞書型の値で渡します。
charset レスポンスとして期待する文字コードを指定することができます。
binary trueを指定すると、Content-Typeによらずコンテンツをバイナリとして扱います。
proxies HTTPリクエスト送信時のプロキシサーバ情報を辞書型の値で渡すことができます。
例: urlopen(‘http://www.kompira.jp’, proxies={‘http’: ‘http://10.10.1.10:3128’, ‘https’: ‘http://10.10.1.10:1080’})

 

urlopen()でアクセスに成功した場合の結果は、以下の要素を持つ辞書で返されます。codeには HTTP のステータスコードが、bodyにはレスポンスの内容が格納されています。

フィールド名 意味
url レスポンスのURL
code 結果ステータスコード
text レスポンスの内容(エンコード情報をもとにレスポンス本文をテキストにデコードしたもの。ただし、バイナリコンテンツの場合は空文字になります)
content レスポンスの内容(バイナリのままのレスポンスの本文)
body レスポンスの内容(コンテンツがバイナリであると判断したとき content と同じ値になり、テキストであると判断したときは text と同じ値になります)
encoding エンコード情報
headers レスポンスに含まれるヘッダ情報(辞書型)
cookies サーバから渡されたクッキー値(辞書型)
history リダイレクトがあった場合にその履歴情報(リスト型)
binary バイナリコンテンツであるかの真偽値

 

これを用いて、Webサーバーにリクエストを送信するのは以下のようなコードになります。

続いて結果を判断して表示の切り替えを行います。
条件分岐はifブロックを用いて行います。

urlopen()を実行した際、リクエストの送信に成功した場合には$STATUSが0に、失敗した場合は$STATUSが0以外になります。

よって、まずはurlopen()自体が成功したかどうかで分岐する処理をします。

具体的に失敗する場合は、urlopen()に指定したホスト名やIPアドレスが間違っていたり、ネットワークが接続できなかったということが原因であると考えられます。

さて、今回は「HTTPの応答コードが200以外の場合にはエラーを表示」としたいので、このコードだけでは十分ではありません。

ここにHTTPリクエストのステータスコードが200であるかどうかを確認する処理を追加してみましょう。

ifブロックで追加条件を指定する場合にはelif節を用います。

これを用いて、HTTPのステータスコードが200以外の場合は異常とします。urlopen()の結果は$RESULTに辞書型で格納されており、”code”というキーで参照できます。

HTTPリクエストに対する応答が正常でなかったときは、$RESULT.codeが200以外となります。

例えば、存在しないURLパスを指定してしまったり、Webサーバー側で何らかのトラブルが発生している場合等があります。

今回の例ではHTTP GETリクエストを送信するのにurlopen()を使用しました。
上記ではレスポンス中のステータスコードを確認するだけにとどまっていますが、サイトのコンテンツ内容の取得はもちろん、ファイルのダウンロードや、外部のREST API呼び出しなど、urlopen()は様々な場面で使用することができます。

ジョブフローから別のジョブフローを呼び出す

メールを送信する」では、指定のURLにリクエストを送り、その結果をメールで通知するジョブフローを作成しました。

ここではmailto()を何度も呼び出していますが、これを別のジョブフローに切り出して、共通部品化してみます。

以下のようなジョブフロー「メール送信」を作成します。

ここではmailto()の引数を、全てパラメータとして設定します。
このジョブフローを「メールでの通知」ジョブフローから呼び出すように、以下の様に書き換えられます。

呼び出すところを見てみますと、次のようになっています。

このように[ ]内にジョブフローを記載する事で、他のジョブフローを呼び出す事が出来ます。また[jobflow: パラメータ]として、呼ばれる側のパラメータを動的に指定する事が出来ます。パラメータが複数ある場合には上記のように”,(カンマ)”で区切って記載します。
呼ばれる側のジョブフロー(上記の場合は「メール送信」)でパラメータが定義されている順番で、呼ぶ側(上記の場合は「メールでの通知」)のパラメータを並べます。

では、呼ばれる側の差出人アドレス(“param_from”)はデフォルト値(“info@kompira.jp”)を使いたいような場合には、どのように呼び出したらいいでしょうか?
この場合には、呼ばれる側のパラメータ名を明示的に指定します。

パラメータ名を付加して呼び出す場合には、順番は前後しても構いません。

さて、ここで応答がなかった場合にWebサーバー関連のプロセス(httpd, mysqld)の起動状況を確認して、停止していた場合には再起動するジョブフロー「プロセス再起動」を作成して追加してみましょう。このジョブフローを呼び出す際には通知メールの送信先アドレス等を引数に取るものとします。

これを元の「メールでの通知」ジョブフローに追加すると、以下のようになります。

上記で見てきた通り、共通する機能や処理に関しては、独立したジョブフローを作成しておくことで、繰り返し処理であったり複数のジョブフローから呼び出す事が可能になります。また、呼び出す側は実行時の条件指定が出来るため、条件に応じた対応を行う事が可能となります。

今回の記事ではmailto()を同じ機能のジョブフローで置き換えるなど、極めて単純な例で説明をいたしましたが、もちろんまとまった大規模な処理を記述する事も可能です。

1つのジョブフローで処理をすべて書くことは可能ですが、可読性・保守性を高めるためには、適切にジョブフローを分割して管理することが重要です。

ジョブフローを実行するフォームを作成する

ジョブフローに権限設定をする」では、オペレーターにジョブフローの中身は見せずに実行だけを依頼したい場合、Kompiraのフォーム機能を使う事をご紹介しました。今回はフォーム機能について、もう少し詳しくご説明します。

まずは、以下のようなジョブフロー「サンプル」を用意します。指定されたサーバー、ユーザー名、パスワードで接続し、指定のコマンドを実行して結果を表示するというものです。

この場合のジョブフローの実行画面は次のようになります。

サンプルジョブフロー
一見してどのように入力したらよいか分かりにくいですね。
このジョブフローを呼び出すためのフォーム「サンプルフォーム」を作ってみます。
サンプルフォーム
この場合のフォームからの実行画面は次の様になります。
フォーム画面

フォームの編集画面には「フィールド名」「フィールド表示名」「フィールド種別」「フィールド修飾子」という入力欄が用意されています。

「フィールド名」には提出オブジェクトに対して渡す引数の名前を指定します。
今回呼び出す「サンプル」ジョブフローはsrv, usr, pwd, cmdという4つの引数を持っているので、それらを指定することになります。

「フィールド表示名」には、実際にジョブフローに渡される引数となる「フィールド名」とは別に、フォームを開いたときに表示させる文字列を自由に指定することができます。さらに、「フィールド種別」で値の種別を選択することができます。一部の種別では指定された様式以外のデータが入力された場合に、エラーとして再入力を促します。例えば”IPアドレス”の項目にはフィールド種別に”IPAddress”を指定しているため、異なる文字列を入力するとエラーとなります。

IPアドレスのチェック

同様に”パスワード”の欄はフィールド種別を”Password”にしたため、入力時には伏字で表示されるようになります。

「フィールド修飾子」には、その他の入力条件をJSON形式で設定することができます。

例えばパラメータ”srv”のフィールド修飾子を

とすると、デフォルト値を指定できます。この場合にはフォーム画面にあらかじめ”192.168.10.1″が記入された状態になります。

パラメータ”usr”のフィールド種別を”enum”、フィールド修飾子を

とすると、入力欄がプルダウンでの選択となります。
enum
この場合に注意するのは”usr”のフィールド種別を”enum”ではなく”string”のままにすると、変わらずに文字列入力のフォームのままになります。
パラメータ”cmd”のフィールド修飾子を

のようにすると、入力項目に説明を表示する事が出来ます。

help_text

オブジェクトを指定させる場合

上記の例ではIPアドレス、ユーザー名、パスワードを実行時に指定させていますが、代わりにノード型オブジェクトを選択させる事も出来ます。(それに合わせてジョブフローも”__node__”に代入するように書き換える必要があります。)仮にディレクトリ”./サーバー”中にノード型のオブジェクトを入れているとして、パラメータ”srv”のフィールド表示名を”サーバー名”、フィールド種別を”Object”、フィールド修飾子を

とすると、下図のように”./サーバ” ディレクトリ中のノード型オブジェクトの一覧を表示するようになります。

オブジェクト型の種別

フォームを利用すると、ジョブフローに直接アクセスさせずにジョブフローを実行する事ができるうえ、実行時にパラメータを指定させる場合に型チェックを行ったり、入力の選択肢を作る事が出来ます。ジョブフローの作成者以外にオペレータの人にジョブフローを実行してもらう場合など、専用のフォームを作ると入力ミスを軽減し、より安全にジョブフローを実行させることができます。

Redmineでのチケット作成をKompiraに通知する

Redmineへ新規チケットを登録する」でRedmineへ新規チケットを登録する方法をご紹介しましたが、本記事では逆にRedmineにチケットが登録されたら、それをトリガーとしてKompiraにチケットの内容を通知する方法をご紹介します。Kompira側では通知された内容に応じて、状況確認、リカバリー、担当者への通知などの処理を起動する事が出来ます。

ここで使う技術は大きく2つです。
(1) KompiraのREST API
(2) RedmineのWebhook

Kompiraを外部から操作するにはREST APIを利用します。RedmineからREST APIを呼び出すにはWebhookを利用します。

WebhookはWebコールバックなどと呼ばれる場合もありますが、あるアプリケーションから別のアプリケーションに対してリアルタイムに情報提供を行うための仕組みです。通常、Webhookは指定されたアプリケーションに対してHTTPリクエストを送信し、受信側(今回はKompira)はそのリクエストの内容を解釈して利用します。

※本記事の内容の動作確認にはRedmine3.2.4を使用しています。

 
Kompira REST APIの設定

Kompira REST APIを利用して、Kompiraのほぼ全ての機能をREST APIから呼び出す事が出来ます。APIを利用するためには認証のための”REST APIトークン”が必要になります。ここではrootユーザーで設定をしていきます。

[設定] -> [ユーザー管理] -> [root] -> [編集]

画面一番下の”REST API 有効化”チェックボックスをONにして[保存]をクリックします。

ユーザー設定

情報画面の画面一番下の”REST API トークン”の”トークンを表示する”をクリックし、トークンを表示します。トークンの文字列は後に利用しますので、メモ帳などにコピーしておいてください。

情報画面

REST APIのエンドポイントは以下のURLです。

HTTPリクエストに次のヘッダーを含めるか、もしくは、クエリ文字列に “format=json” を含める必要があります。

基本的には

でリクエストを行います。詳細はドキュメントを参照してください。

 
Webhookの設定

続いてRedmine側のWebhookの設定をします。まずはgithubよりRedmine webhookをインストールします。

Redmine画面から設定をします。
[プロジェクト] -> (プロジェクト名) -> [設定] -> [webhook]

webhook設定

この画面のURLにKompiraのREST APIのURLを指定します。

この例ではKompiraのAlertチャネルのオブジェクトを指定します。WebhookからAlertチャネルのsendメソッドを呼び出して、メッセージを送信します。

 
Kompira側でのメッセージの受信

Alertチャネルからの受信内容を表示するジョブフロー「Webhook受信テスト」を作成します。

このジョブフローを実行すると、ステータスは”待ち”となり、コンソールは待機中の状態になります。Kompiraの画面はこのままにしておきます。

続いて、Redmineから新しいチケットを登録します。
Redmineチケット登録

この登録処理でWebhookが起動し、Kompiraにリクエストを送信します。Kompira側では予めジョブフロー”Webhook受信テスト”を実行中のため、Webhookが送信したデータがコンソールに表示されます。
(注意:このジョブフローは受信を続けますので、確認が終わりましたら[中止]ボタンを押して強制的に停止させてください。Kompiraの画面を切り替えてもジョブフローは動作していますので、別のAlertでメッセージを受信する処理を実行した場合に影響が出ます。)

チャネルの受信

ここで受信したメッセージの形式はWebhookの配布元サイト”https://github.com/suer/redmine_webhook“を参照してください。

一部、抜粋します。

応答は辞書型のデータであるため、Kompiraのジョブフローでは”[メッセージ].payload.issue.author.icon_url”のようにメッセージ中の各要素を呼び出す事が出来ます。

JSON形式のままでは読みにくいため、ここでAlertの監視用ジョブフロー”Webhook受信テスト”を次のように変更して実行します。各項目が個別に表示されます。

実行した状態でRedmineで新規チケットを作成すると、Kompiraのコンソールでは次の様に表示されます。

Webhookからの受信

ここまで、RedmineからWebhookを利用してKompiraのチャネルオブジェクトに対してREST APIでメッセージを送信し、Kompira側では受信したメッセージの各要素へのアクセス方法を見てきました。このメッセージの内容によってKompiraでの必要なジョブフローを処理を呼び出す事が出来ます。
例えば先の例では[メッセージ].payload.actionが「opened」であれば「新規チケットが作成された」事を示しています。これによりインシデントの初期対応する処理を記述したジョブフローを呼び出すなどが可能です。
Redmineのカスタムフィールドを追加する機能を使うことで、Kompiraのジョブフローで読み込むための値を登録するフィールドとして使用することで様々な応用も考えられます。

テーブル内の情報を選択して処理を実行する

複数サーバーに対してコマンドを実行する」ではテーブルに登録した全ての機器に対する一括処理を行う方法をご紹介いたしましたが、特定機器に対して処理を行う場合は一体どうすれば良いでしょうか。

機器の数が限られている場合は「ジョブフローを実行するフォームを作成する」に記載の「オブジェクトを指定させる場合」の手順にてフォームからテーブル内の機器を選べるようにしても良いですが、数が増えるとセレクトボックスが長くなり、対象機器が見つかりにくくなってしまいます。

こういったケースにおいて有用な機能として、今回の記事ではテーブルの関連オブジェクト機能を活用し、選択した機器を対象にジョブフローを実行する方法をご紹介します。

動作確認環境

ソフトウェア バージョン
Kompira 1.5.0

テーブルの作成

まずは機器情報を格納するためのテーブル「サーバー一覧」を作成します。Kompira上で機器情報を取り扱うためのオブジェクトとしてノード情報型が用意されておりますので、テーブルのオブジェクト型には「ノード情報」を指定します。
テーブルを作成したら、処理対象となる機器情報を追加してください。

ノード情報の追加

上記の例では「サーバー一覧」テーブルに「server1 ~ server3」の3台のサーバーを登録しています。
以降の説明はこの3台のサーバーが登録された仮定にて行います。

ジョブフローの作成

本記事ではサンプルの題材として、機器情報に登録されたホスト名・IPアドレスを表示するジョブを作成します。
下記の内容で、新規ジョブフローを作成してみましょう。

ジョブフローが作成できたら、パラメータ「servers」に機器情報を配列で渡し、動作確認をしてみましょう。
機器情報の配列は、例えば [./サーバー一覧/server1, ./サーバー一覧/server2] のように記載します。

関連ジョブの呼び出し

上記の例では、実行結果は次の様になります。

実行結果

関連オブジェクトの追加

ここまでの手順でテーブル・ジョブフローの用意が出来ましたので、実際に関連オブジェクトの設定をしてみましょう。
設定するにはテーブルの編集画面を開き、「関連オブジェクト」の欄のプルダウンから先ほど作成したジョブフローを選択し、「保存」をクリックします。
(本記事ではジョブ名を「関連ジョブ」としております)

関連オブジェクトの指定

設定保存後、テーブル内の機器情報を選択し、「その他」→「ジョブフローの実行」 をクリックします。

オブジェクトの選択実行

実行対象オブジェクトの確認画面が開きますので、「実行」をクリックします。

確認ダイアログ

以上の手順によりジョブフローが実行され、ジョブフローの動作確認時と同様の内容が表示されます。

実行結果

応用例

本記事の内容を利用すると、機器に対するオペレーションをテーブル上から簡単に実行することが可能となります。
例えば、テーブル上で選択した機器に対してパッケージアップデートを実施できるようにするには、次のようなジョブフローを関連オブジェクトとして登録します。
(Red Hat系のOS向けの例となります)

ジョブフローに権限設定をする

ジョブフローを運用していると、例えば

  • オペレーターの人にジョブフローの実行はさせたいが、変更して欲しくない。
  • ジョブフローの中にシステムに関する情報があるので、中身を見せたくない。

などの、権限設定を行いたい場合が出てきます。今回の記事はこのようなジョブフローの権限設定にまつわる機能をご紹介します。

 
Kompiraのユーザー追加

まずは、Kompiraのユーザー作成の方法からご紹介します。管理者権限を持つアカウントでログイン後、画面上部の「設定>ユーザー管理」を選択すると、登録されている「ユーザー一覧」画面が表示されます。

ユーザー一覧

ここの一番下の行に、名称を追加し、一番右の「新規作成」ボタンをクリックします。

ユーザー新規追加

ここでユーザーに関する情報を登録して「保存」をクリックします。最低限、パスワードの指定は必要です。

新規ユーザー

これでユーザーが追加されました。詳細設定のために右の「操作>編集」をクリックしてください。

新規ユーザー設定

それぞれの項目は以下のような意味を持ちます。

フィールド 説明
ユーザー名 ログインの際に必要なID名称です。
姓・名 「ユーザー名」を実際に使う方の氏名を記入してください。
メールアドレス 「ユーザー名」を実際に使う方のアドレスを記入してください。
パスワード ログインの際のパスワード
グループ ユーザーの属するグループを任意で選択します。(「グループ」はユーザー同様、「設定>グループ管理」画面にて管理します。)
有効 このユーザーにKompiraの操作を許可するかを表すフラグです。このチェックをオフにするとログインを許可しません。
ホーム このユーザーのホームディレクトリを指定します。(通常は /home/ユーザー名)
環境変数 ジョブフロー実行時に、自動的に変数として読み込まれる環境変数オブジェクト
REST API 有効化 APIの利用可否を示すフラグです。利用する場合にはONにします。

必要に応じて、上記のパラメータを変更してください。

 
オブジェクトのプロパティ

オブジェクト名を右クリックすると以下の様なプルダウンが表示されます。この一番下の「プロパティ」をクリックします。

オブジェクト名の右クリック

次のようなプロパティ画面が表示されます。

プロパティ画面

Kompiraでは、Unix/Linuxと似た管理権限を持ちます。「ユーザーパーミッション」の「ユーザー」欄に権限付与/変更したいユーザーを指定し、右側のチェックボックスをON/OFFします。

読み取り 指定のユーザーにジョブフローの閲覧を許可します。許可のないジョブフローにアクセスすると「閲覧が許可されていないページです。」というエラーメッセージが表示されます。
書き込み このチェックを指定すると指定のユーザーは「編集」を選択できるようになり、ジョブフローを変更する事が出来ます。
実行 このチェックを指定すると指定のユーザーは「実行」を選択できるようになり、ジョブフローの実行が出来ます。

画面の「ユーザーパーミッション」の下に「グループパーミッション」の欄があります。こちらも同様に設定をしますが、対象がグループに属するユーザー全員に権限付与を行います。

 
「読み取り」させたくないが「実行」させたいジョブフローを指定する

上記の権限設定にて、「実行」をON、「読み取り」をOFFにすると目的を達成できそうですが、現実的にはジョブフローにアクセスしようとすると「許可されていないページです」エラーが発生するため扱いにくいという問題があります。

このような場合には「フォーム」画面を用意します。

まずは前準備として、/root/ユーザーパーミッション というジョブフローの「パラメータ>ユーザーパーミッション」を以下の様に、ユーザー= test に対して、実行権限だけを付与します。

ユーザーパーミッション

ここでユーザーtestがこのジョブフローにアクセスしようとすると、以下のようなエラーが表示されます。

読み取り不可

さて、以下のように /home/test の下に「テストフォーム」という名前のフォーム型オブジェクトを作成します。

フォーム画面

テストフォームの設定画面では、以下の様に「提出オブジェクト」のプルダウンから「サンプルジョブフロー」を指定して保存をクリックします。

フォームの画面

次のようなフォーム型オブジェクトが作成されます。

フォーム型

ここで「サンプルジョブフロー」のリンクをクリックすると上記のような「読み取り不可」エラーが表示されますが、「実行」ボタンはクリックすることができ、ジョブフローが起動されます。

このようにして、フォームを経由する事でジョブフローの中身は見せずに、実行だけを許可する仕組みを作る事が出来ます。また、このフォームのプロパティからの権限を設定する事でジョブフローを実行できる人を選択する事も出来ます。

ここでは深入りしませんが、パラメータ/引数を取るジョブフローに対しては、フォームからオペレータが値を入力してジョブフローに渡して実行させることも可能です。

さて、いかがでしたでしょうか?Kompiraの権限設定の考え方は先に述べたようにUnix/Linuxに似せて作成されているため、ジョブフローの他にもディレクトリなどにも設定する事が出来て、指定のディレクトリ以下のアクセスを許可/禁止する事も可能です。

権限設定をうまく利用して、セキュアな自動化環境を構築してください。

既存のスクリプトをKompiraで利用する

運用の現場では日々の作業を行うために、さまざまなスクリプトを利用されていると思います。Kompiraで利用する「ジョブフロー」もスクリプトの一種ですが、Kompira用の特別な記法で処理を記述する必要があります。

この記事では、いままで運用で利用しているスクリプトをKompiraに取り入れて実行する方法を紹介します。

スクリプトの例として、ファイルの退避を行うスクリプトを考えてみます。例えば、ログファイルは障害分析などに必要な直近の分はサーバー上に置いておきつつ、logrotateなどでアーカ イブされた古くなった分についてはディスク容量の逼迫を避けるため、ファイルサーバーなどに保存用に退避させておきたいなどの運用があります。

まずは以下のようなログファイルを退避させるシェルスクリプト”movelogfile.sh”を使っているとします。これは複数の指定のフォルダに作成される”*.log”という名前のファイルを、ファイルサーバーの指定のパスに移動する処理を行います。ここでは、ファイルの移動にscpコマンドを利用していますが、パスワードの登録を求められないように証明書認証ができるように設定しておく必要があります。

これを深夜2:00に定期的に自動実行する場合では、crontabに次の様に登録しているでしょう。

 

「スクリプトジョブ」オブジェクトの作成

さて、上記の処理をKompiraのスクリプトジョブの機能を使って実行する方法を説明していきます。ここではサーバー側でファイル移動のスクリプトを実行するため、「スクリプトジョブ」型のオブジェクトを作成します。以下の条件でオブジェクトを作成します。
名称: ファイルのバックアップ
型:スクリプトジョブ

ファイルのバックアップ

ここで「+」ボタンをクリックすると、次のようなソースを入力する編集画面が表示されます。

ファイルの移動

「スクリプト」欄にファイル移動のためのシェルスクリプトを記載します。ここでは上記の”movelogfile.sh”のソースをそのまま転記してください。

 

スクリプトの実行

スクリプトを実行するサーバーとそのアカウントを指定する必要があります。ここでは事前準備で作成した”server1″、”アカウント1″を指定して「実行」をクリックします。もしスクリプトが引数を取る場合には「コマンドライン引数」の欄に記載してください。

ファイルの移動

ここで実行ボタンをクリックすると

1. 「スクリプト」に記載したコードを一時ファイルにして、指定の「実行ノード」に転送
2. 転送したファイルに実行権限を付与
3. スクリプト実行
4. 作成した一時ファイルを削除

上記のような処理が順次実行されます。

ここではKompiraの「スクリプトジョブ」型のオブジェクトを利用して、サーバー側にシェルスクリプトの一時ファイルを転送して実行するようにしました。もちろん、サーバー側に事前に用意したスクリプトを [ “backup.sh” ] のようにして起動するジョブフローを作っても同様の事ができますが、ジョブフローをメンテナンスする際に、各サーバーに配置されたシェルスクリプトを置き換えるよりは、「スクリプトジョブ」型を利用する方が集中して管理できるメリットがあります。
また、このスクリプトをcrontabに登録するのと同じように定期的に実行したい場合は「スケジューラを使って定期的にジョブを実行する」で紹介したスケジューラ機能を使用することで、同様の定期的な実行をさせることができます。

スクリプトジョブの単体での実行だけでなく、Kompiraのジョブフローの中からスクリプトジョブを呼び出し、結果をさらにジョブフローで扱うということも可能です。
ジョブフローからのスクリプトジョブの実行例は、今後改めてコラムとしてご紹介する予定です。

複数サーバーに対してコマンドを実行する

運用業務において管理対象が1台のみという事は珍しく、通常は同じようなサーバーを複数台メンテナンスされていると思います。
ただ、1台ごとに個別のジョブフローを作成するのは現実的ではありませんので、本記事では同一のメンテナンスのコマンドをを複数のサーバーに渡って実施する場合の方法について説明します。

 
1. for文で繰り返し

ここでは例としてメンテナンス対象のサーバーが3台あるとします。各サーバーについて、ノード情報型のオブジェクト”server1″, “server2”, “server3″を用意します。
また、それぞれに合わせたアカウント情報型のオブジェクト”アカウント1″~ “アカウント3″を用意します。

接続先の指定は制御変数 “__node__” にノード情報型のオブジェクトを代入する事で行います。
ここまで準備できましたら、サーバーごとの繰り返し処理は、以下のような for文による繰り返し処理として記述できます。

for文のin の後に、配列型のデータとして”server1″ ~を指定します。変数”srv”には繰り返し処理毎にノード情報型のオブジェクト”server1″~が代入されて、コマンドが実行されます。

2行目の”srv.hostname”は、ノード情報型のフィールド”hostname”を参照しています。これはノード情報の画面上での「ホスト名」という値に対応しています。

 
2. テーブル型による繰り返しの記述

先の例では、繰り返し対象になるサーバーをfor文中に配列で指定しています。台数が少ないうちはこのような方法でも良いですが、台数が増えてきたりサーバーの追加や入れ替えが頻繁になるとジョブフローの管理が大変になります。
このため、管理対象のサーバーをテーブル型オブジェクトを利用して、ジョブフローとは別に管理します。

ここでは「メンテナンス対象」という名称のテーブル型のオブジェクトを作成します。テーブル作成時に”オブジェクト型”として”ノード情報”を指定しましょう。

テーブル型

上図の例では「サーバー1号機」のような各行はノード情報型のオブジェクトです。

さて、ノード情報型のテーブルが作成できたところで、先の繰り返し処理のジョブフローは次のように書き換える事が出来ます。

このようにfor文のinの後に、配列の代わりにテーブル型のオブジェクトを使用する事が出来ます。この場合、変数srvには”メンテナンス対象”テーブルに含まれるノード情報型の各要素が順に代入され、 “|” 以降の処理を繰り返し実行します。つまりサーバー構成に変更がある場合には”メンテナンス対象”オブジェクトが適切に修正されていれば、このジョブフローそのものを変更する必要が無くなるわけです。

実行するコマンドを実行時に任意に指定できるようのパラメータ”cmd”で指定するようにして、さらにコマンド実行時にエラーが発生した際には「エラーが発生しました」と表示されるように変更してみます。

1行目の”ls”コマンドはデフォルト値ですので、実行時に別のコマンドを指定することが出来ます。これでジョブフローを1度起動するだけで、”メンテナンス対象”テーブルに登録されているの全サーバーで指定したコマンドが実行できます。

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

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

事前準備

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

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

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

ジョブフローの作成

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

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

APIのエンドポイント

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

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

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

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

APIのユーザ認証

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

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

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

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

リクエストのURLは

となります。

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

process result detail

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

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

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

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

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

受信メールの例です。(Gmailの場合)
link on Gmail

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

Kompira REST APIを利用して外部からオブジェクト情報を取得する

Kompira REST APIを利用して外部からジョブフローを実行する」では、指定のジョブフローを外部から操作する方法を紹介しました。
今回はKompiraのREST APIの別の利用方法として、外部からKompiraのオブジェクト情報を取得してみましょう。
また、取得した情報の応用例として、Kompira上のテーブルのデータを取得し、CSV形式のデータを作成する方法についても合わせてご紹介します。


動作確認環境

ソフトウェア バージョン
Kompira 1.5.1
LinuxOS CentOS7.4-1708

以降では、kompiraサーバーのIPアドレスを <kompiraサーバー> と表記します。


事前準備

APIトークンの取得

APIの利用に必要な「REST APIトークン」を、「Kompira REST APIを利用して外部からジョブフローを実行する」に記載されている手順で取得してください。
取得したトークンを以降では <api_token> と表記します。

 

オブジェクトの作成

外部から取得するオブジェクトをKompira上に作成します。
ここでは、下図のようなテーブルオブジェクトにノード情報を登録します。


基本の取得方法

実際にAPIリクエストを使ってオブジェクトの情報を取得してみましょう。
オブジェクト取得時のリクエストURLは以下になります。

ここでは、ターミナルのcURLコマンドを実行します。

すると下記のようなJSON形式の辞書データが返却されます。

 

レスポンスデータの中身は以下の通りです。

キー名 説明
id オブジェクトID
abspath オブジェクトパス
owner オブジェクト所有者ユーザー名
fields フィールドデータ辞書(オブジェクト依存)
extra_properties オブジェクト拡張属性
user_permissions ユーザーパーミッション辞書
group_permissions グループパーミッション辞書
display_name 表示名
description 説明
created オブジェクト生成日時
updated オブジェクト最終更新日時
type_object 型オブジェクトのパス
parent_object 親オブジェクトのパス

オブジェクト一覧の取得

GETリクエストのエンドポイントにディレクトリもしくはテーブルオブジェクトを指定することで、配下に存在するオブジェクトを一括で取得することができます。

リクエストのURLは以下の2通りになります。

コマンドでの実行は以下のようになります。

このときのレスポンスデータは以下です。
“results”の中に、先ほどのレスポンスデータがリストとして格納されています。

 

一覧取得時のレスポンスデータの中身は以下の通りです。

キー名 説明
count オブジェクト総数
next 次ページのURL
previous 前ページのURL
results オブジェクトデータリスト

応用例1(フィルタ条件付きの一覧取得)

一覧取得のリクエスト時にクエリパラメータを指定することで、レスポンスに含まれるデータを絞り込むことができます。

例えば、以下の条件でのフィルタを行います。

1. “/root”の子孫にある
2. ノード情報オブジェクトの内、
3. 本日の00:00:00以降に更新されたオブジェクトを取得する。

このときに指定するクエリは下の表のようになります。

クエリパラメータ 説明
type_object 指定した型のオブジェクトのみを取得
updated__gte 指定した日付以降に更新されたオブジェクトを取得

 

コマンドでの実行は以下のようになります。

または、クエリをURLで直接指定する以下の方法もあります。

 

お知らせ

近日リリース予定のバージョン1.5.2では、より強力なフィルタ指定を行うことができます。乞うご期待。


応用例2(CSVファイルへの変換)

REST API経由で取得したデータを活用する方法について一例を説明します。
先述の「オブジェクト一覧」で取得したノードオブジェクトの情報について、CSV形式のファイルへ変換します。
ここでは整形用のコマンドとして、 jq コマンドを用いています。

 

変換後のデータは以下のようになります。

KompiraからSlackに通知する

障害発生や処理終了などの通知は、例えばmailto()関数を使うと電子メールで送る事が出来ますが、APIを持ったメッセージアプリケーションに送信することも可能です。今回はSlackに通知を行ってみましょう。

 
Slackの設定

お使いのSlackのアカウントにメッセージ受信用のチャネルを作成します。今回は#kompiraを作成します。
kompira_channel

次にSlackに外部からメッセージを送信できるように、”Incoming WebHooks”の設定をします。
channel settings > Add an app or integration > 検索窓に”incoming webhooks”
これでApp Directoryの”Incoming WebHooks”のページが表示されます。
Incoming Webhooks

左の”Add Configuration”ボタンをクリック

Post to channel

“Post to channel”画面で、チャネル名が”#kompira”になっている事を確認して、”Add Incoming Webhooks Integration”ボタンをクリック

“Setup Instructions”画面の”Webhook URL”を別途メモ帳などに記録しておいてください。(Kompiraのジョブフローに設定します。)
その他の項目は、続く”Integration Setting”も含めて、最低限はデフォルトでも良いですが、必要に応じて変更してください。
ここでは”Customize Name”を”Kompira2Slack”と変更してみます。

Customize Name

設定が完了したら”Save Setting”ボタンをクリックしてください。

 
Kompiraジョブフローの作成

続いてKompira側にジョブフロー「Slackへ通知」を次の様に作成します。

ここでパラメータ”url”には、Slackのセットアップ画面で表示された”Webhooks URL”を記載してください。

このジョブフローを実行すると、Slackに次のように投稿されます。
Entry on Slack

このようにKompiraからSlackのチャネルへの投稿は容易に可能です。
これを他のジョブフローから利用する場合には、例えば以下のように呼び出します。

単純なメッセージ送信以外にもリンクURLの送信やアイコン・色の変更なども行えます。リッチなメッセージ作成の詳細はSlack APIの”Message“をご参照ください。

公開鍵認証を使ってssh接続をする

Kompiraからリモートサーバーに接続してコマンドを投入する際には、sshで接続を行います。この際、パスワード認証以外に公開鍵認証を利用する事が出来ます。本記事ではKompiraから公開鍵認証を用いてssh接続を行うための設定方法をご紹介します。

本記事では接続対象のサーバーとしてCentOS 7.3およびUbuntu Linux 16.10で動作確認を行っております。

 
証明書の作成

まずはKompiraサーバーにて証明書ファイルを作成します。Kompiraが動いているサーバーにsshを使ってログインしてください。
次のように、ssh-keygen コマンドを使って作成します。

上記の例では以下の2つのファイルが作成されます。
kompira.key   (秘密鍵)
kompira.key.pub (公開鍵)

 
リモートサーバーでの証明書の登録

作成したファイルのうち、公開鍵は接続先のサーバーに、秘密鍵はKompiraを利用するPC等に、それぞれ転送します。
以下の例では接続用のアカウントのホームディレクトリの配下に “.ssh”ディレクトリがあり、その中にある “authorized_keys”ファイル中に公開鍵を転記します。
既存のディレクトリ/ファイルが存在している場合には、 mkdir, touchコマンドは省略してください。またディレクトリ/ファイルの権限については他のアカウントからアクセス出来ないようにしてください。(権限設定が弱いと通信を試みる途中で停止する場合があります。)

 
Kompiraのジョブフローでの利用

下図はKompiraの”アカウント情報”型のオブジェクトの作成例です。
・接続用のアカウントは”kompira”になっています。
・パスワード欄には鍵のパスフレーズを指定します。
・ssh鍵ファイル欄は、PC等に保管した秘密鍵を指定します。
・ssh鍵パスフレーズは、証明書を作成時に指定したパスフレーズを入力します。 (「パスワード」欄に記載がある場合は省略可)

sudoパスワードとssh鍵パスフレーズが異なる環境の場合は、パスワード欄にsudoパスワードを、ssh鍵フレーズ欄にパスフレーズを入力してください。

アカウント

ノード情報は従来同様に作成します。IPアドレスとアカウントの指定は最低限行ってください。

ノード情報

最後にジョブフローですが、例えば以下のように書くことができます。

ジョブフロー

ここでは”hostname”コマンドの実行結果を表示しています。
実行結果

このようにKompiraからはID/パスワード認証だけでなく、公開鍵を利用した接続を行う事が出来ます。

ジョブフロー画面の各種設定

ジョブフローの画面にはいくつかの表示タブやチェックボックスが用意されています。今回の記事では、それらの使い方についてご説明します。
今回は説明のために次の様なジョブフローを用意しました。適当な名前で作成してください。

 
ジョブフローの実行状況を確認する

さて、このジョブフローを実行すると次の様な画面になります。

ジョブフロー実行画面

ここで「ジョブフロー」タブをクリックすると、次のような画面になります。

ジョブフロー実行画面

この画面では、黄色の箇所がジョブフロー中の実行中の行を表示します。上図の場合ではsleep(30)で30秒停止中であることが分かります。(30秒経過後に一番最後のprint(“終了”)に移ります。)

次の「子プロセス一覧」タブをクリックすると、次のような画面になります。

子プロセスタブ

ここでは2つの子プロセスが完了している事がわかります。このジョブフローではfork文を使って、2つのprint()をそれぞれ別の子プロセスで実行しています。

どちらかのプロセス名称のリンクをクリックすると、print()の実行結果が見て取れます。

子プロセス画面

fork文の詳細については本項では扱いませんので、詳細はマニュアル等を参照してください。

 
ステップモード

続いて、ジョブフロー編集画面の設定タブについて見ていきましょう。

ジョブフローの設定

ジョブフローの編集画面に、「設定」というタブをクリックすると上図のようなチェックボックスが表示されます。このうち「ステップモード」のチェックボックスを有効化して実行すると、次のような画面になります。

ステップモードでの実行

“[SUBMIT COMMAND: uname -a]” で処理が停止します。

この時の「ジョブフロー」タブは次の様な表示になります。

ステップモードでのジョブフロータブ

ここで「続行」ボタンをクリックすると、処理1の”uname -a” が実行され、処理2の[“pwd”]に移って再度停止します。

ステップモードでの実行

 

ステップモードでのジョブフロータブ

このようにステップモードでの実行では、[” … “] のコマンドの実行前にジョブフローが一時停止し、実行コマンドの内容を確認できます。このモードはジョブフロー作成時のデバッグに利用することを想定しています。

 
チェックポイントモード

ジョブフローの実行状態を随時保存するモードです。ジョブフロー実行中にKompiraサーバが異常終了した場合、保存されたチェックポイントの状態から、ジョブフロープロセスを再開できるようになります。

通常モードで実行した際にKompiraのプロセスが障害で停止し、再起動した場合には「プロセス一覧」から実行中のプロセスが消えますが、チェックポイントモードで実行されているジョブはステータスが「待ち(停止中)」で残っています。

チェックポイントモードのプロセス

プロセスを選択して「続行」をクリックすることで、プロセス停止前の段階から再開する事が出来ます。

 
監視モード

ここでは3つの選択肢、「なにもしない」「プロセス終了時にメール送信」「プロセス異常終了時のみメール送信」から選びます。これはジョブフローが完了した際のメール通知を行うかを指定します。

メールの送信条件については、「設定>システム設定」画面で指定します。

システム設定

ここに送信先の管理者メールアドレス、ならびに使用するSMTPサーバーに関する設定を入れていきます。(特に指定のない場合にはKompiraサーバーからメールが配信されます。)

 
ジョブフローオプション

ジョブフローの編集画面を表示すると、ジョブフローを記載する「ソース」欄の下に、3つのチェックボックスがあります。

・ 多重度: 指定したジョブフローを同時に実行できる数を指定します。多重度の数を超えるジョブフローのプロセスが呼び出された場合には、他のジョブフローが完了するまで実行を待たされます。多重度を0以下にした場合には無制限と解釈されます。

・ デフォルトチェックポイントモード: 先にみてきました「チェックポイントモード」のデフォルト値を設定します。

・ デフォルト監視モード: 先にみてきました「監視モード」のデフォルト値を設定します。

「多重度」については、ファイル操作やDBアクセスなどでデータの整合をとる場合など、競合を防ぐために排他的に実行する必要があるジョブフローに対して設定します。

 

このようにKompiraにはジョブフローの編集時や実行時の動作確認を支援する機能や、実行時の動作モードを設定する機能などが用意されています。ぜひジョブフロー作成時や運用時にお役立てください。

Slackでの投稿をKompiraに通知する

KompiraからSlackに通知する」では、KompiraからSlackのチャネルにメッセージを投稿する方法をご紹介しました。
今回は逆にSlackのチャネルに投稿したメッセージをKompiraで受信してみましょう。
(※) 本記事の内容を動作させるためには、Kompiraがインターネットから接続できる場所に配置されている必要がある点にご注意ください。

環境

ソフトウェア バージョン
Kompira 1.4.10.post3

Slackの設定

KompiraからSlackに通知する」の例と同様に、お使いのSlackのアカウントに#kompiraチャネルを利用します。

次にSlackの#kompiraチャネルに投稿されたら、それを外部に送信できるように、「Outgoing WebHooks」の設定をします。
channel settings > Add an app or integration > 検索窓に「Outgoing webhooks」と入力をしてOugoing Webhooksの設定ページを表示しましょう。
Outgoing WebHooks

左の「Add Configuration」ボタンをクリックします。

Outgoing WebHooks

「Add Outgoing Webhooks integration」をクリックします。

次に表示される画面で外部にリクエストを送る際の設定を行います。

項目名
Channel #kompira
Trigger Word(s) echo,shell
URL(s) http://(kompiraサーバのIPアドレス)/system/channels/Alert.send?format=json&token=XXXXX (KompiraのREST API呼び出し時のセキュリティートークン)

その他の項目はデフォルトのままで結構です。
「Trigger Word(s)」の項には「echo,shell」を設定しました。「echo」または「shell」から始まる投稿のみKompira側に通知されるようになります。

ここまでの設定で、Slackの#Kompiraチャネルでの投稿がKompiraのAlertチャネルに送信されるようになりました。

KompiraでSlackの投稿を受信

次の様なジョブフローを実行して、チャネルに送信されたデータを見てみましょう。

ここで#kompiraチャネルに「echo hello」と入力すると、Kompira側のコンソールには、次のような表示が現れます。

投稿した文字列「echo hello」だけでなく、ユーザ名、チャンネル名、マッチングしたトリガー名などの情報が含まれています。
トリガーと以降の文字列を分離したいので、簡単なライブラリを作成し、ジョブフロー「Slack受信」を以下のように書き換えてみましょう。