はじめに
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.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
[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 インターフェースを有効にしておけば問題ありません。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 |
(...) [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 時点で固定です。ただし、今後アップグレードやバージョンを確認するコマンドが実装される可能性があるため、事前にマニュアルなどを確認しておくことを推奨いたします。
上記の設定で確認した場合、以下のように何も取得できる情報がないことがわかります。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
[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 に指定したファイルに認証用ユーザーの情報を登録します。
|
1 2 3 |
[http_auth_backend:default_auth_backend] backend=file filename=/etc/mysqlrouter/mysqlrouter.pwd |
登録する際には mysqlrouter_passwd コマンドが用意されているため、以下のように認証用ユーザーを作成します。
|
1 2 3 4 5 6 7 8 |
[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 に変更します。
|
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 を指定するようにしてください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
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 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 モジュールが実装されているので、今回はこの方法を利用してみます。
|
1 2 3 4 5 |
[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 インスタンスにログインして、認証用ユーザーを登録します。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
[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 |
REST API の有効化
バックエンド認証用ユーザーが登録できたら、mysqlrouter プロセスを起動します。
このとき、利用したい REST API については、設定ファイルに追記をおこなっておきます。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
[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 |
利用方法
有効にした情報を取得したい場合は、以下のようにユーザー認証をおこないながらエンドポイントを指定します。
|
1 2 3 4 5 6 7 8 |
[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
1234[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
123456[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 を利用するまでの手順や利用方法について確認してきました。
この機能を利用することで、各ルーティング先の死活監視や、定期的に値を取得することで負荷状況の推移を確認することが可能になります。
新しいステータスの追加やプラグインへの対応もおこなわれているようですので、今後のリリースでどのように機能が拡充していくかが楽しみです。
