Japan

サイト内の現在位置を表示しています。

CLUSTERPRO XのRESTful APIを試してみました～APIサービスの有効化編～

CLUSTERPRO オフィシャルブログ ～クラブロ～
  • Share

 

はじめに

CLUSTERPRO X 4.2以降では従来のGUIやCUIに加えて、RESTful APIが用意されています。RESTful APIを用いることで、他のアプリケーションからCLUSTERPROのHAクラスターの状態取得や、起動・停止・グループ移動などの操作を容易に行うことが可能となります。

RESTful APIの利用方法の紹介として、本記事ではCLUSTERPRO XのRESTful APIを有効化する手順、および、簡単な確認方法について説明します。RESTful APIを利用した応用例としての、サンプルアプリケーションの取得および使用方法の説明については「popupサンプルアプリケーション編」を参照して下さい。

この記事の内容

1. RESTful APIについて

RESTful APIは、REST(Representational State Transfer)の原則に従って設計された、Webシステム用のアプリケーションプログラミングインタフェースです。RESTful APIはHTTPプロトコルによってアクセス可能であり、コマンドやNode.jsなど任意の言語からこれらの機能を利用できるメリットがあります。また、URIによって操作およびその対象を指定することが可能なため、コマンドまたはコードが簡潔になります。

CLUSTERPRO Xが提供するRESTful APIはバージョンによって利用可能な機能が異なり、CLUSTERPRO X 5.2のRESTful APIでは次の機能が用意されています。

■ 情報取得系
  • クラスター情報取得
  • サーバー情報取得
  • グループ情報取得
  • グループリソース情報取得
  • モニターリソース情報取得
  • メトリクス情報取得

■ 操作系
  • クラスター操作
  • サーバー操作
  • グループ操作
  • グループリソース操作
  • モニターリソース操作
  • スクリプト実行要求操作

利用可能なAPIの詳細については、以下を参考に利用するCLUSTERPRO Xのバージョンにあったドキュメントを参照ください。

【参考】
  • CLUSTERPRO X 5.2 > CLUSTERPRO X 5.2 for Windows > RESTful API リファレンスガイド
    → 3. APIリファレンス

  • CLUSTERPRO X 5.2 > CLUSTERPRO X 5.2 for Linux > RESTful API リファレンスガイド
    → 3. APIリファレンス

2. RESTful APIの有効化手順

CLUSTERPRO Xの既定の設定ではRESTful APIは無効化されています。そのため、利用にあたってはHAクラスターを構成する各サーバーにNode.jsをインストールし、その後にRESTful APIの有効化を行う必要があります。

2.1 Node.jsのインストール

利用しているOSに対応したNode.jsを以下からダウンロードします。

CLUSTERPRO Xで動作確認済みとなっているNode.jsのバージョンは、以下を参考に利用するCLUSTERPRO Xのバージョンにあったドキュメントを参照ください。
なお、動作確認済みのNode.jsと同一のメジャーバージョンであれば、より新しいバージョンのNode.jsでも動作するものと考えられますが、利用する際は予め動作確認した上でご利用ください。

【参考】
  • CLUSTERPRO X 5.2 > CLUSTERPRO X 5.2 for Windows > RESTful API リファレンスガイド
    → 2. REST APIについて
      → 2.2 動作環境

  • CLUSTERPRO X 5.2 > CLUSTERPRO X 5.2 for Linux > RESTful API リファレンスガイド
    → 2. REST APIについて
      → 2.2 動作環境

■ Windows
今回は「node-v20.10.0-x64.msi」を使用します。インストーラー実行後はインストールウィザードの案内に従って進めていきます。インストール先など途中の選択肢はデフォルト設定のままとします。
Node.jsのインストールが完了した後はOSを再起動します。

■ Linux
今回はNode v20.10.0を使用するために、Node.jsの過去バージョンページから「node-v20.10.0-linux-x64.tar.xz」をダウンロードし、任意の場所(本記事では/opt)に展開します。

# cd /opt
# tar xf /tmp/node-v20.10.0-linux-x64.tar.xz

tarパッケージやnvmなどを使用したNode.jsのインストール時は、以下のパスからnodeコマンドに通っていることも確認します。もしパスが通っていない場合はCLUSTERPROからのnodeコマンドの実行に失敗します。

  • /sbin
  • /bin
  • /usr/sbin
  • /usr/bin

パスが通っていない場合は手動で/usr/bin/配下にnodeコマンドへのシンボリックリンクを作成します。OSの再起動は不要です。

# ln -s /opt/node-v20.10.0-linux-x64/bin/node /usr/bin/node

上記のように特定バージョンのNode.jsをインストールするのではなく、ディストリビューションから配布されているNode.jsを利用する場合は、パッケージ管理コマンドを使用してインストールします。
例えばRed Hat Enterprise LinuxではdnfコマンドでNode.jsをインストールします。

# dnf install nodejs -y

2.2 RESTful APIの有効化設定

Cluster WebUIに接続後、設定モードから「クラスタのプロパティ」を開き、「API」タブをクリックします。

[APIサービスを有効にする]のチェックボックスをOnにします。
[通信方式]にはHTTP、HTTPSのどちらかを選択します。
本記事ではHTTPSを選択します。RESTful APIアクセス時はユーザー、パスワードによる認証を行うためHTTPSが推奨設定となります。
[通信方式]にHTTPSを選択した場合は、「暗号化」タブにて証明書ファイルや秘密鍵ファイルなどを指定する必要があります。「暗号化」タブでの設定については過去記事の「popupCluster WebUIにOpenSSL 3.0/3.1を利用してHTTPSで接続する方法(Windows/Linux)」を参照してください。

■ Windows

RESTful APIの有効化設定(Windows)zoom拡大表示

■ Linux

RESTful APIの有効化設定(Linux)zoom拡大表示

設定完了後、設定を反映します。

3 動作確認

RESTful APIへの接続確認をcurlコマンドを用いて行います。Windowsの場合はcurl.exeとPowerShell版curlコマンドの2種類がありますが、今回はLinuxのcurlコマンドと同じオプションを使用可能なcurl.exeコマンドを使用します。curl.exeコマンドを使用する場合は、コマンドプロンプトから実行する方法、明示的にcurl.exeと指定して実行する方法等があり、以降の例ではコマンドプロンプトから実行することでcurl.exeを使用しています。

3.1 サーバー状態の取得

例としてサーバー情報を取得するために次のAPIを使用します。

GET /api/v1/servers
- クエリパラメーター
    なし

このAPIに対応したcurl.exeコマンドの実行例は次の通りです。

curl -X GET -k -u "<user>:<password>" -w "\nStatus: %{http_code}\n" "https://<server>:<port>/api/v1/servers"

<user>と<password>には、OSのユーザー、パスワードを指定します。<server>にはAPIサービスを有効にしたCLUSTERPRO Xの動作しているサーバーのIPアドレスやホスト名を指定します。<port>にはAPIサービスが待ち受けるポート番号(既定値は29009)を指定します。「-w '\nStatus: %{http_code}\n'」は、HTTPリクエストに対するレスポンスのStatus Codeを標準出力に出力するオプションです(任意で指定可)。「-k」は証明書の署名検証をスキップするためのオプションです。正式な証明書の場合は不要です。
成功すると実行結果として次のようにレスポンス(JSON形式)および、末尾にレスポンスのStatus Codeである200が出力されます。また、レスポンスのcode(APIの実行結果)が0となり、serversにサーバー名とサーバーステータスが入ったものが返却されます。

{
    "result": {
        "code": 0,
        "message": ""
    },
    "servers": [
        {
            "name": "server1",
            "status": "Online"
        },
        {
            "name": "server2",
            "status": "Online"
        }
    ]
}
Status: 200

認証失敗やリクエストURL不正などのエラー時は、次のように末尾のStatus Codeが200以外となります。また、レスポンスのcodeも0以外となり、messageにエラーメッセージが入ります。

{
    "result": {
        "code": "1",
        "message": "Authentication failed."
    }
}
Status: 401

3.2 グループリソース情報の取得

ある特定のグループリソースに関する情報を取得してみます。APIは次の通りです。

GET /api/v1/resources/{resourcename}
- クエリパラメーター
    なし

このAPIに対応したcurl.exeコマンドの実行例は次の通りです。

curl -X GET -k -u "<user>:<password>" -w "\nStatus: %{http_code}\n" "https://<server>:<port>/api/v1/resources/<resource name>"

先ほどのサーバー情報取得と似ていますが、APIを呼ぶためのURLが少し異なっています。また、<resource name>に取得したいリソース名を指定します。
成功すると実行結果として次のようにレスポンス(JSON形式)および、末尾にレスポンスのStatus Codeである200が出力されます。また、レスポンスのcode(APIの実行結果)が0となり、resourcesにリソース名やリソースステータスなどの情報が入っています。typeがリソース種別、currentがリソースが起動しているサーバー、groupがリソースが属するグループとなります。

{
    "result": {
        "code": 0,
        "message": ""
    },
    "resources": [
        {
            "name": "awsvip1",
            "type": "awsvip",
            "status": "Online",
            "current": "server1",
            "group": "failover1"
        }
    ]
}
Status: 200

3.3 グループの移動

グループの移動を実行してみます。APIは次の通りです。

POST /api/v1/groups/{groupname}/move
- リクエストパラメーター
    target: 移動先サーバー

このAPIに対応したcurl.exeコマンドの実行例は次の通りです。

curl -X POST -k -u "<user>:<password>" -w "\nStatus: %{http_code}\n" "https://<server>:<port>/api/v1/groups/<group name>/move" -d "{ \"target\" : \"<target server>\" }"

情報取得時は-XオプションにGETを指定していましたが、グループ移動は操作となるためPOSTを指定します。APIを呼ぶためのURLもグループ移動用のものになっており、<group name>に移動したいグループ名を指定します。このAPIはリクエストパラメーターtargetの値<target server>に移動先サーバーを指定することで移動先を指定することが可能です。リクエストパラメーターは-dオプションにJSON形式で記述します。リクエストパラメーターtargetの指定を省略した場合は次フェールオーバーポリシーのサーバーに移動します。
成功するとグループの移動が開始し、実行結果として次のようにレスポンス(JSON形式)および、末尾にレスポンスのStatus Codeである200が出力されます。また、レスポンスのcode(APIの実行結果)が0となります。

{
    "result": {
        "code": 0,
        "message": ""
    }
}
Status: 200

グループの移動が正常に完了したかどうかを確認するために、グループ情報の取得を実行します。
APIは次の通りです。

GET /api/v1/groups/{groupname}
- クエリパラメーター
    なし

このAPIに対応したcurl.exeコマンドの実行例は次の通りです。

curl -X GET -k -u "<user>:<password>" -w "\nStatus: %{http_code}\n" "https://<server>:<port>/api/v1/groups/<group name>"

groupsのstatusが、"Offline Pending"や"Online Pending"などであれば移動中です。statusが"Online"になり、かつ、nameが移動先のサーバー名になっていればグループの移動が完了しています。

{
    "result": {
        "code": 0,
        "message": ""
    },
    "groups": [
        {
            "name": "failover1",
            "status": "Online",
            "current": "server2",
            "resources": [
                {
                    "name": "awsvip1"
                },
                {
                    "name": "md1"
                },
                {
                    "name": "script1"
                }
            ]
        }
    ]
}
Status: 200

3.4 クラスターの再起動

最後にクラスターの再起動を試してみます。APIは次の通りです。

POST /api/v1/cluster/reboot
- リクエストパラメーター
    なし

このAPIに対応したcurl.exeコマンドの実行例は次の通りです。

curl -X POST -k -u "<user>:<password>" -w "\nStatus: %{http_code}\n" "https://<server>:<port>/api/v1/cluster/reboot"

成功するとクラスターの再起動が開始することを確認します。実行結果として次のようにレスポンス(JSON形式)および、末尾にレスポンスのStatus Codeである200が出力されます。

{
    "result": {
        "code": 0,
        "message": ""
    }
}
Status: 200

まとめ

今回は、CLUSTERPRO XのRESTful APIを取り上げ、有効化手順について紹介しました。RESTful APIを利用することでCluster WebUIやCLUSTERPRO Xのコマンドとはまた違ったクラスターの状態監視や制御が可能となります。有用なケースがあればご活用ください。
後編の「popupサンプルアプリケーション編」では、RESTful APIを利用したサンプルアプリケーションについて紹介しております。

CLUSTERPRO XのホームページからCLUSTERPRO X 5.2のフル機能が使えるpopup試用版の利用申し込みができますので、是非お試しください。

お問い合わせ

本記事に関するお問い合わせは、popupお問い合わせ窓口までお問い合わせください。

  • Share