はじめに
TiDB CloudにはAPIが提供されており、クラスタの操作をはじめとして各種操作がAPI経由で行えるようになっています。
本記事ではAPIの紹介と簡単な利用方法について説明します。
TiDB Cloud API
TiDB Cloud API (OpenAPI) は OpenAPI 形式のAPIで、現在ProjectやClusterの操作を行う v1beta APIと、IAMや請求機能を提供する v1beta1 が提供されています。
どちらも利用にはAPIキーを発行する必要があります。まずは、curlを使った簡単な使い方を見ていきます。（環境はMacOSを使っていますが、bashとcurlが利用できるなら他の環境でも操作は同じです）
APIキーの発行
APIキーはTiDB Cloudコンソールから発行します。TiDB CloudのOrganization Settings > API Key から、APIキーを発行してください。
取得したAPIキーを環境変数に入れておきましょう。
export TIDB_PUB=<PUBLIC KEY>
export TIDB_PRIV=<PRIVATE KEY>
APIの呼び出し
APIドキュメントには、curl呼び出しのサンプルがあります。
ここではもっとも簡単な、プロジェクトの一覧を取得するサンプルを実行してみます。
これはGetメソッドで、引数も特に不要なため単に実行するだけです。
> curl --digest \
--user "$TIDB_PUB:$TIDB_PRIV" \
--request GET \
--url 'https://api.tidbcloud.com/api/v1beta/projects?page=1&page_size=10'
{"items":[{"id":"XXXXXXXX","orgId":"XXXXXX","name":"Group6","clusterCount":0,"userCount":1,"createTimestamp":"1723510314","awsCmekEnabled":false},{"id":"YYYYYYYY","orgId":"YYYYYYY","name":"Group5","clusterCount":0,"userCount":1,"createTimestamp":"17...
正しく実行されました。JSONオブジェクトが返ってきます。
クラスタの操作
このようにシンプルなAPIは良いのですが、クラスタの操作は若干複雑になっています。
クラスタを作成するためには
- ProjectIDの取得
- Serverless / Dedicatedの指定
- クラウドプロバイダの指定
- クラスタスペックの指定
が必要になります。クラスタで設定できるスペックはクラウドプロバイダやリージョンによって若干の差異があるためです。
最も簡単なサーバレスクラスタを立ち上げる例を見てみます。サーバレスはAWS固定、スペックも指定の必要がないため、ProjectIDを指定すれば可能です。ProjectIDは、先ほど実行したプロジェクトの一覧から確認することができます。
curl --digest \
--user "$TIDB_PUB:$TIDB_PRIV" \
--request POST \
--url https://api.tidbcloud.com/api/v1beta/projects/XXXXXXXX/clusters \
--header 'content-type: application/json' \
--data '{"name":"Cluster0","cluster_type":"DEVELOPER","cloud_provider":"AWS","region":"ap-northeast-1","config":{"root_password":"<password>"}}'
rootユーザーパスワードの設定が必要なことに注意します
Pythonから利用する
上記のような例では比較的簡単でしたが、もっと複雑な処理をさせたいときにcurlを連続で呼び出すシェルを書くのはしんどいです。
Pythonでは、TiDB Cloud APIをラップした tidbcloudyというライブラリが提供されています。これを使うと、Pythonから簡単にAPIを利用することができます。
tidbcloudyを使って、プロジェクト中のすべてのクラスタを削除する例を見てみます。
import os
import sys
import tidbcloudy
if len(sys.argv) != 2:
print("USAGE: python delete_cluster.py [project_name]")
exit()
# env variables
tidb_pub = os.environ.get('TIDB_PUB')
tidb_priv = os.environ.get('TIDB_PRIV')
project_name = sys.argv[1]
api = tidbcloudy.TiDBCloud(public_key=tidb_pub, private_key=tidb_priv)
project = next(filter(lambda p:p.name == project_name ,api.iter_projects()))
for c in project.iter_clusters():
print(c)
c.delete()
このようになります。iter_clusters() でプロジェクト中のクラスタのジェネレーターが使えるのがいいですね。
Python以外にも、go言語用のラッパーが作成されています。
おわりに
TiDB Cloudは他にも TiDB Cloud CLI や terraform などで自動化を行うことができますが、どちらも内部ではこのAPIを利用しています。APIを直接利用する方法を知っておくと自動化の幅が広がると思うので、ぜひ試してみてください。