REST API を使用した MySQL Router のステータス確認方法

2022年7月15日

この記事は最終更新から2年以上経過しています。内容が古くなっている可能性があります。

はじめに

MySQL Router では 8.0.17 以降、 REST API が利用できるようになっています。
この機能を利用することで、各ルーティング先の死活監視やコネクション数などを容易に確認することができるようになります。

今回は、MySQL Router で REST API を利用するまでの手順や、REST API で取得することができるステータスについて説明していきたいと思います。

構成

以下の MySQL 8.0.29 環境で MySQL InnoDB Cluster を構築して実施をおこないました。

マシン	IP	ホスト名
MySQL Server(PRIMARY)	192.168.174.148	mic01
MySQL Server(SECONDARY)	192.168.174.149	mic02
MySQL Server(SECONRARY)	192.168.174.150	mic03
MySQL Router	192.168.174.156	router

なお、環境の構築時には、以下の記事を参考にしていただければと思います。
MySQL 8.0.13 で MySQL InnoDB Cluster を構築する

利用するまでの手順

REST API の利用準備

実は MySQL 8.0.22 以降、MySQL Router の初期設定をおこなうと、REST API を利用するためのオプションがデフォルトで設定されるようになっています。
REST API の機能を利用したくない場合は、初期設定時に –disable-rest オプションを指定するようにしてください。

Changes in MySQL Router 8.0.22 (2020-10-19, General Availability)
The bootstrap process now configures REST API functionality into the generated mysqlrouter.conf configuration file. The new optional –https-port bootstrap argument defines port; which is defined as 8443 by default.

To disable the REST API configuration from being generated, pass in the new –disable-rest bootstrap option.

[root@router ~]# mysqlrouter --user=mysqlrouter --bootstrap icadmin@192.168.174.148:3306 --account test_router
[root@router ~]# cat /etc/mysqlrouter/mysqlrouter.conf
# File automatically generated during MySQL Router bootstrap
[DEFAULT]
(...)

[http_server]
port=8443
ssl=1
ssl_cert=/var/lib/mysqlrouter/router-cert.pem
ssl_key=/var/lib/mysqlrouter/router-key.pem

[http_auth_realm:default_auth_realm]
backend=default_auth_backend
method=basic
name=default_realm

[rest_router]
require_realm=default_auth_realm

[rest_api]

[http_auth_backend:default_auth_backend]
backend=metadata_cache

[rest_routing]
require_realm=default_auth_realm

[rest_metadata_cache]
require_realm=default_auth_realm

[root@router ~]# mysqlrouter --user=mysqlrouter --bootstrap icadmin@192.168.174.148:3306 --account test_router

[root@router ~]# cat /etc/mysqlrouter/mysqlrouter.conf

# File automatically generated during MySQL Router bootstrap

[DEFAULT]

(...)

[http_server]

port=8443

ssl=1

ssl_cert=/var/lib/mysqlrouter/router-cert.pem

ssl_key=/var/lib/mysqlrouter/router-key.pem

[http_auth_realm:default_auth_realm]

backend=default_auth_backend

method=basic

name=default_realm

[rest_router]

require_realm=default_auth_realm

[rest_api]

[http_auth_backend:default_auth_backend]

backend=metadata_cache

[rest_routing]

require_realm=default_auth_realm

[rest_metadata_cache]

require_realm=default_auth_realm

また、各セクションの意味は以下の通りです。なお、セクション名の後に : が追記されている場合、任意のセクションキー名として設定が分かれていることを示しています。

http_server : HTTP インターフェースを使用して HTTP リクエストをリッスンするための設定
- port : 使用するポート(デフォルト値:8443)
- ssl : SSL を有効にするか否か
- ssl_* : SSL 接続に使用するための各種証明書やキーファイル名
http_auth_realm : HTTP の認証レルム
- backend : 使用する認証バックエンドのセクションキー名
- method : HTTP 認証方式
- name : 認証ユーザーに提示されるレルム名
http_auth_backend : 認証バックエンド
- backend : 認証方法(file(デフォルト値) あるいは metadata_cache)
- filename : backend に file を指定した場合、認証情報を読み込むファイル名
rest_api : その他の REST API を利用するために必要となるプラグイン名
rest_* : ロードする各 REST API のプラグイン名
- require_realm : 使用する認証レルムのセクションキー名

ひとまず REST API 機能を有効にするだけであれば、以下のように HTTP インターフェースを有効にしておけば問題ありません。

(...)
[http_server]
port=8443
ssl=1
ssl_cert=/var/lib/mysqlrouter/router-cert.pem
ssl_key=/var/lib/mysqlrouter/router-key.pem

[http_auth_realm:default_auth_realm]
backend=default_auth_backend
method=basic
name=default_realm

#[rest_router]
#require_realm=default_auth_realm

[rest_api]

[http_auth_backend:default_auth_backend]
backend=metadata_cache

#[rest_routing]
#require_realm=default_auth_realm

#[rest_metadata_cache]
#require_realm=default_auth_realm

(...)

[http_server]

port=8443

ssl=1

ssl_cert=/var/lib/mysqlrouter/router-cert.pem

ssl_key=/var/lib/mysqlrouter/router-key.pem

[http_auth_realm:default_auth_realm]

backend=default_auth_backend

method=basic

name=default_realm

#[rest_router]

#require_realm=default_auth_realm

[rest_api]

[http_auth_backend:default_auth_backend]

backend=metadata_cache

#[rest_routing]

#require_realm=default_auth_realm

#[rest_metadata_cache]

#require_realm=default_auth_realm

REST API が有効になっているかどうかを確認する場合、 https://[hostname]:[port]/api/20190715/swagger.json から有効になっている情報を確認することが可能です。
ここで、 20190715 は API のバージョン名ですが、MySQL 8.0.29 時点で固定です。ただし、今後アップグレードやバージョンを確認するコマンドが実装される可能性があるため、事前にマニュアルなどを確認しておくことを推奨いたします。

上記の設定で確認した場合、以下のように何も取得できる情報がないことがわかります。

[root@router ~]# curl -Ssk https://192.168.174.156:8443/api/20190715/swagger.json | jq
{
  "swagger": "2.0",
  "info": {
    "title": "MySQL Router",
    "description": "API of MySQL Router",
    "version": "20190715"
  },
  "basePath": "/api/20190715",
  "tags": [],
  "paths": {},
  "definitions": {}
}

[root@router ~]# curl -Ssk https://192.168.174.156:8443/api/20190715/swagger.json | jq

{

"swagger": "2.0",

"info": {

"title": "MySQL Router",

"description": "API of MySQL Router",

"version": "20190715"

"basePath": "/api/20190715",

"tags": [],

"paths": {},

"definitions": {}

}

これ以外の情報を取得する場合は、設定ファイルにサポートされているプラグインを追加した後、指定したバックエンド認証用のユーザーを作成する必要があります。
バックエンド認証には file および metadata_cache の 2 つがあり、それぞれの作成方法は以下の通りです。

backend = file

backend に file を指定した場合は、filename に指定したファイルに認証用ユーザーの情報を登録します。

[http_auth_backend:default_auth_backend]
backend=file
filename=/etc/mysqlrouter/mysqlrouter.pwd

[http_auth_backend:default_auth_backend]

backend=file

filename=/etc/mysqlrouter/mysqlrouter.pwd

登録する際には mysqlrouter_passwd コマンドが用意されているため、以下のように認証用ユーザーを作成します。

[root@router ~]# mysqlrouter_passwd set /etc/mysqlrouter/mysqlrouter.pwd router_check
Please enter password: router_password

[root@router ~]# mysqlrouter_passwd verify /etc/mysqlrouter/mysqlrouter.pwd router_check
Please enter password:

[root@router ~]# mysqlrouter_passwd list /etc/mysqlrouter/mysqlrouter.pwd router_check
router_check:$5$THNa8l4e3NfsRYR/$U5PUsNyWFdflc4kTkRuhkSyREms1HDi7z4WWfBePNv2

[root@router ~]# mysqlrouter_passwd set /etc/mysqlrouter/mysqlrouter.pwd router_check

Please enter password: router_password

[root@router ~]# mysqlrouter_passwd verify /etc/mysqlrouter/mysqlrouter.pwd router_check

Please enter password:

[root@router ~]# mysqlrouter_passwd list /etc/mysqlrouter/mysqlrouter.pwd router_check

router_check:$5$THNa8l4e3NfsRYR/$U5PUsNyWFdflc4kTkRuhkSyREms1HDi7z4WWfBePNv2

パスワードが正しいことが確認できたら、ファイルの所有権を mysqlrouter に変更します。

[root@router ~]# chown mysqlrouter:mysqlrouter /etc/mysqlrouter/mysqlrouter.pwd

1	[root@router ~]# chown mysqlrouter:mysqlrouter /etc/mysqlrouter/mysqlrouter.pwd

backend = metadata_cache

backend に metadata_cache を指定した場合は、各 MySQL Server 側のメタデータテーブルである mysql_innodb_cluster_metadata.router_rest_accounts テーブルに認証用ユーザーを登録します。
なお、MySQL InnoDB Cluster や InnoDB ReplicaSet のように、mysql_innodb_cluster_metadata スキーマが存在しない環境では利用することができないので、その場合は file を指定するようにしてください。

mysql> DESC mysql_innodb_cluster_metadata.router_rest_accounts;
+-----------------------+--------------+------+-----+----------------------+-------+
| Field                 | Type         | Null | Key | Default              | Extra |
+-----------------------+--------------+------+-----+----------------------+-------+
| cluster_id            | char(36)     | NO   | PRI | NULL                 |       |
| user                  | varchar(256) | NO   | PRI | NULL                 |       |
| authentication_method | varchar(64)  | NO   |     | modular_crypt_format |       |
| authentication_string | text         | YES  |     | NULL                 |       |
| description           | varchar(255) | YES  |     | NULL                 |       |
| privileges            | json         | YES  |     | NULL                 |       |
| attributes            | json         | YES  |     | NULL                 |       |
+-----------------------+--------------+------+-----+----------------------+-------+
7 rows in set (0.00 sec)

mysql> DESC mysql_innodb_cluster_metadata.router_rest_accounts;

+-----------------------+--------------+------+-----+----------------------+-------+

+-----------------------+--------------+------+-----+----------------------+-------+

+-----------------------+--------------+------+-----+----------------------+-------+

7 rows in set (0.00 sec)

MySQL 8.0.29 時点では、以下のカラムに値を指定しておけば利用することができます。

cluster_id : MySQL InnoDB Cluster の ID(mysql_innodb_cluster_metadata.clusters テーブルから確認可能)
user : バックエンド認証用ユーザーの名前
authentication_method : 認証方法(デフォルト値:modular_crypt_format)
authentication_string : バックエンド認証用ユーザーのパスワード

登録するパスワードをハッシュ化する方法はいくつかありますが、たとえば MySQL Shell の Python モードでは crypt モジュールが実装されているので、今回はこの方法を利用してみます。

[root@router ~]# mysqlsh --py
(...)
 MySQL  Py > import crypt
 MySQL  Py > crypt.crypt("router_password",crypt.mksalt(method=crypt.METHOD_SHA256))
$5$8OMfGKvbl7hlPoOE$8Pp14fWUk6GWdDisF3Ou.eFTAGy2TTeWhalzLZ1O9D8

[root@router ~]# mysqlsh --py

(...)

MySQL Py > import crypt

MySQL Py > crypt.crypt("router_password",crypt.mksalt(method=crypt.METHOD_SHA256))

$5$8OMfGKvbl7hlPoOE$8Pp14fWUk6GWdDisF3Ou.eFTAGy2TTeWhalzLZ1O9D8

その後、MySQL InnoDB Cluster の PRIMARY インスタンスにログインして、認証用ユーザーを登録します。

[root@mic01 ~]# mysql
(...)
mysql> INSERT INTO mysql_innodb_cluster_metadata.router_rest_accounts
       VALUES ((SELECT cluster_id FROM mysql_innodb_cluster_metadata.clusters LIMIT 1),
       'router_check',
       'modular_crypt_format',
       '$5$8OMfGKvbl7hlPoOE$8Pp14fWUk6GWdDisF3Ou.eFTAGy2TTeWhalzLZ1O9D8',
       NULL,
       NULL,
       NULL);

mysql> SELECT * FROM mysql_innodb_cluster_metadata.router_rest_accounts\G
*************************** 1. row ***************************
           cluster_id: 721a9026-f962-11ec-86bc-000c2928cd6f
                 user: router_check
authentication_method: modular_crypt_format
authentication_string: $5$8OMfGKvbl7hlPoOE$8Pp14fWUk6GWdDisF3Ou.eFTAGy2TTeWhalzLZ1O9D8
          description: NULL
           privileges: NULL
           attributes: NULL

[root@mic01 ~]# mysql

(...)

mysql> INSERT INTO mysql_innodb_cluster_metadata.router_rest_accounts

VALUES ((SELECT cluster_id FROM mysql_innodb_cluster_metadata.clusters LIMIT 1),

'router_check',

'modular_crypt_format',

'$5$8OMfGKvbl7hlPoOE$8Pp14fWUk6GWdDisF3Ou.eFTAGy2TTeWhalzLZ1O9D8',

NULL,

NULL);

mysql> SELECT * FROM mysql_innodb_cluster_metadata.router_rest_accounts\G

*************************** 1. row ***************************

cluster_id: 721a9026-f962-11ec-86bc-000c2928cd6f

user: router_check

authentication_method: modular_crypt_format

authentication_string: $5$8OMfGKvbl7hlPoOE$8Pp14fWUk6GWdDisF3Ou.eFTAGy2TTeWhalzLZ1O9D8

description: NULL

privileges: NULL

attributes: NULL

REST API の有効化

バックエンド認証用ユーザーが登録できたら、mysqlrouter プロセスを起動します。
このとき、利用したい REST API については、設定ファイルに追記をおこなっておきます。

[root@router ~]# cat /etc/mysqlrouter/mysqlrouter.conf
(...)
[rest_router]
require_realm=default_auth_realm

[rest_api]

[http_auth_backend:default_auth_backend]
backend=metadata_cache

[rest_routing]
require_realm=default_auth_realm

[rest_metadata_cache]
require_realm=default_auth_realm

[rest_connection_pool]
require_realm=default_auth_realm

[root@router ~]# systemctl start mysqlrouter

[root@router ~]# cat /etc/mysqlrouter/mysqlrouter.conf

(...)

[rest_router]

require_realm=default_auth_realm

[rest_api]

[http_auth_backend:default_auth_backend]

backend=metadata_cache

[rest_routing]

require_realm=default_auth_realm

[rest_metadata_cache]

require_realm=default_auth_realm

[rest_connection_pool]

require_realm=default_auth_realm

[root@router ~]# systemctl start mysqlrouter

利用方法

有効にした情報を取得したい場合は、以下のようにユーザー認証をおこないながらエンドポイントを指定します。

[root@router ~]# curl -Ssk -u router_check:router_password https://192.168.174.156:8443/api/20190715/router/status | jq
{
  "processId": 24752,
  "productEdition": "MySQL Community - GPL",
  "timeStarted": "2022-07-13T12:18:03.768524Z",
  "version": "8.0.29",
  "hostname": "router"
}

[root@router ~]# curl -Ssk -u router_check:router_password https://192.168.174.156:8443/api/20190715/router/status | jq

{

"processId": 24752,

"productEdition": "MySQL Community - GPL",

"timeStarted": "2022-07-13T12:18:03.768524Z",

"version": "8.0.29",

"hostname": "router"

}

なお、MySQL Router で利用できる REST API の一覧については、以下のマニュアルに詳細が記載されているのでご確認ください。

6.2 MySQL Router REST API Reference

また、いくつかの値について以下に説明いたします。

https://192.168.174.156:8443/api/20190715/routes/{routeName}/health

[root@router ~]# curl -Ssk -u router_check:router_password https://192.168.174.156:8443/api/20190715/routes/bootstrap_ro/health | jq { "isAlive": true }

1
2
3
4

[root@router ~]# curl -Ssk -u router_check:router_password https://192.168.174.156:8443/api/20190715/routes/bootstrap_ro/health | jq
{
"isAlive": true
}

{routerName} は各ルーティング名称(routing セクションのセクションキー名)です。名称の一覧は /routes から確認することもできます。
ルーティング先に接続できるかどうかを確認します。

https://192.168.174.156:8443/api/20190715/routes/{routeName}/status

[root@router ~]# curl -Ssk -u router_check:router_password https://192.168.174.156:8443/api/20190715/routes/bootstrap_rw/status | jq
{
"activeConnections": 1,
"totalConnections": 2,
"blockedHosts": 0
}

[root@router ~]# curl -Ssk -u router_check:router_password https://192.168.174.156:8443/api/20190715/routes/bootstrap_rw/status | jq

{

"activeConnections": 1,

"totalConnections": 2,

"blockedHosts": 0

}

各ルーティングの接続数を確認することができます。 activeConnections が現在のルーティング先への同時接続数です。

まとめ

ここまで、REST API を利用するまでの手順や利用方法について確認してきました。
この機能を利用することで、各ルーティング先の死活監視や、定期的に値を取得することで負荷状況の推移を確認することが可能になります。
新しいステータスの追加やプラグインへの対応もおこなわれているようですので、今後のリリースでどのように機能が拡充していくかが楽しみです。

よかったらシェアしてね！

URLをコピーしました！

REST API を使用した MySQL Router のステータス確認方法

はじめに

構成

利用するまでの手順

REST API の利用準備

backend = file

backend = metadata_cache

REST API の有効化

利用方法

まとめ

スマートスタイルTECHブログについて

関連記事