🔑
TiDB CloudのProject API Keyで安心安全にTerraformを使う

2025/08/19に公開
 この記事についてTiDB CloudではTerraformを使ってクラスタを管理することができますが、これまでは利用するAPI Keyの権限が強く、適用範囲も広かったため、利用には注意が必要でした。2025-08-12に導入されたProject API Keyでは、より安全に運用できるようになりました。この記事では、TiDB Cloudの新しいAPI Key管理について紹介し、Terraformでの利用について解説します。2025-08-12のリリース内容については以下のリンク先でご確認ください。
https://docs.pingcap.com/tidbcloud/tidb-cloud-release-notes/#august-12-2025

 新しいAPI Keyの管理について今回のリリースでAPI Keyの管理に主に以下の変更がありました。
v1beta1の導入
role-based access control (RBAC)の導入（v1beta1のみ）
Organization単位に加えて、Project単位のAPI Keyの導入
それぞれについて簡単に見ていきます。

 v1beta1の導入2025-08-12以前のAPIバージョンはv1betaでした（末尾に1が無い）。
基本的な使い方であればv1betaでもそれほど不自由は無いかと思いますが、運用を行うにあたり以下の点で不安がありました。
API KeyはOrganization単位であり、権限設定が無いため、１つのAPI Keyで全Projectに対して何でもできてしまっていた
クラスタのTier特有の機能の操作ができなかった
例えばServerless（現Starter）クラスタであればBranch操作、DedicatedクラスタであればPrivate endpointの操作など

v1beta1では上記の問題点が解消されました。Tier特有の操作を行うために、TiDB Cloud Dedicated APIとTiDB Cloud Starter and Essential APIの２つがリリースされました。詳細についてはそれぞれのAPIドキュメントを参照してください。
TiDB Cloud Dedicated API (v1beta1)
TiDB Cloud Starter and Essential API (v1beta1)
権限設定については後述します。

 RBACの導入これまでのAPI Keyの権限はOrganization Ownerのみで、その権限は非常に強力でした。今回のリリースではRBACが導入されて、その用途に応じて権限を適切に制御できるようになり、以前よりも安心して使えるようになっています。RBACはOrganizationとProjectの２つのレベルで設定されています。

API Keyに設定可能なOrganizationレベルで利用可能なロールは以下の５つで、これはユーザーに付与できるものと同じです。
Organization Owner
Organization Viewer
Organization Billing Manager
Organization Billing Viewer
Organization Console Audit Manager
各ロールに許可された権限については以下のドキュメントを参照してください。
https://docs.pingcap.com/tidbcloud/manage-user-access/#organization-roles
API Keyに設定できるロールは以下の２つです。
Project Owner
Project Viewer
詳細は以下のドキュメントを参照してください。
https://docs.pingcap.com/tidbcloud/manage-user-access/#project-roles
Project API KeyとRBACを組み合わせることで、TerraformなどのIaCツールを使った運用でも、誤操作や権限の過剰付与を防げるようになりました。

 Project API Keyの利用Project API Keyを発行する方法はこれまでのAPI Keyとほぼ同じです。TiDB Cloudにログイン後、Organization Settingsに移動して、左メニューからAPI Keyを選択します。
!画面キャプチャは2025年8月18日時点のものです。
その後、画面上部でBy Projectをクリックして、ドロップダウンリストから設定したいプロジェクトを選択します。それからCreate Project API KeyをクリックしてAPI Keyを作成します。

作成したAPI Keyの情報は作成後に一度だけ表示されるので忘れずにコピペして控えておきましょう。

 TerraformでProject API Keyを使うTiDB Cloudの多くのリソースはTerraformで管理できます。ここではTiDB Cloud Dedicatedクラスタを例にTerraformでの設定例を紹介します。
https://docs.pingcap.com/tidbcloud/terraform-tidbcloud-provider-overview/
この記事で用いているTerraformおよびtidbcloud providerのバージョンは以下のとおりです。基本的にはそれぞれ最新バージョンを使うとよいでしょう。Project API Keyを使うにはtidbcloud providerのバージョンはv0.4.0以上である必要があります。
$ terraform version         
Terraform v1.12.2
on darwin_arm64
+ provider registry.terraform.io/tidbcloud/tidbcloud v0.4.3
Terraformを利用するにはAPI Keyが必要ですが、クラスタを管理する目的であればProject API Keyを使うのが良いでしょう。Terraformでの設定例を以下に示します。
terraform {
  required_providers {
    tidbcloud = {
      source = "tidbcloud/tidbcloud"
      version = "~> 0.4.3"
    }
  }
  required_version = ">= 1.0.0"
}

# Ref: https://registry.terraform.io/providers/tidbcloud/tidbcloud/latest/docs/resources/dedicated_cluster
resource "tidbcloud_dedicated_cluster" "cluster" {
  display_name  = "<cluster-name>"
  region_id     = "<platform-region>"
  port          = 4000
  root_password = "<password>"
  tidb_node_setting = {
   node_spec_key = "8C16G"
   node_count    = 1
  }
  tikv_node_setting = {
   node_spec_key   = "8C32G"
   node_count      = 3
   storage_size_gi = 200
   storage_type    = "Standard"
  }
  paused = true
}
リソースの設定内容についてはtidbcloud providerのドキュメントを参照してください。
https://registry.terraform.io/providers/tidbcloud/tidbcloud/latest/docs
設定例の中にAPI Keyを含めていないため、実行時は以下のようにコマンドを実行します。
$ TIDBCLOUD_PUBLIC_KEY='xxx' TIDBCLOUD_PRIVATE_KEY='xxx' terraform apply
クラスタのスケーリングや削除なども可能です。詳細は以下のドキュメントを参照してください。
https://docs.pingcap.com/tidbcloud/terraform-use-dedicated-cluster-resource/#use-the-tidbcloud_dedicated_cluster-resource
以前からTerraformでクラスタを管理していた場合はお気づきになるかと思いますが、構成情報の中にプロジェクトIDが含まれていません。Project API Keyを使う場合、プロジェクトIDはAPI Keyから識別可能であるため、設定は必須ではなく任意となっています。ただし、OrganizationレベルのAPI Keyを使う場合は構成情報の中で明示的に設定してください。設定しないとdefault projectの中にクラスタが作成されます。
もし異なるProjectに属するProject API Keyでクラスタを操作しようとすると以下のエラーが出て適切に保護されます。
$ TIDBCLOUD_PUBLIC_KEY='xxx' TIDBCLOUD_PRIVATE_KEY='xxx' terraform plan
tidbcloud_dedicated_cluster.cluster: Refreshing state...

Planning failed. Terraform encountered an error while generating this plan.

╷
│ Error: Read Error
│ 
│   with tidbcloud_dedicated_cluster.cluster,
│   on cluster.tf line 2, in resource "tidbcloud_dedicated_cluster" "cluster":
│    2: resource "tidbcloud_dedicated_cluster" "cluster" {
│ 
│ Unable to call GetCluster, got error: [GET /v1beta1/clusters/10726458657455056786][403 Forbidden][20250818062555773c4d1175dd953b1f] {"code":403,"message":"Does not have permission to access the resources in belonged
│ project.","details":[{"@type":"type.tidbapi.com/tidb.rpc.RequestInfo","requestId":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","servingData":"bizErrorCode: 49900003"}]}

 補足: 構成情報に記載する設定値について大変便利なTerraformでのIaC管理ですが、少し困ることがあります。それはregion_idやnode_specなどの値は決められた値しか受け付けられないのですが、その値にどのようなものがあるのかわからないことです。
ドキュメントなどに記載があれば良いのですが、見当たらないのでData resourceを参照するのが良いでしょう。node_specの設定可能値を確認するにはtidbcloud_cluster_specsを、region_idはtidbcloud_dedicated_regionsを確認するとよいでしょう。それぞれのData resourceを参照するtfファイルの例を記載します。
なお、TerraformでなくてもAPIに直接リクエストして内容を確認することも可能です。
region情報: https://docs.pingcap.com/tidbcloud/api/v1beta1/dedicated/#tag/Region/operation/RegionService_ListRegions
node_spec情報: https://docs.pingcap.com/tidbcloud/api/v1beta1/dedicated/#tag/Region/operation/RegionService_ListNodeSpecs
tidbcloud providerは https://docs.pingcap.com/tidbcloud/api/v1beta/#tag/Cluster/operation/ListProviderRegions を参照している模様（2025-08-20時点）


 region情報を確認するterraform {
  required_providers {
    tidbcloud = {
      source = "tidbcloud/tidbcloud"
      version = "~> 0.4.3"
    }
  }
  required_version = ">= 1.0.0"
}

data "tidbcloud_dedicated_regions" "region" {
}

output "output" {
  value = data.tidbcloud_dedicated_regions.region
}
以下のようなコマンドで実行します。
$ TIDBCLOUD_PUBLIC_KEY='xxx' TIDBCLOUD_PRIVATE_KEY='xxx' terraform apply -auto-approve
もし特定プロバイダーのリージョンに絞り込みたい場合は以下のようにするとよいでしょう。
# AWSのTokyoリージョンに絞り込む
$ TIDBCLOUD_PUBLIC_KEY='xxx' TIDBCLOUD_PRIVATE_KEY='xxx' terraform output -json \
    | jq '.output.value.regions[] | select(.cloud_provider=="aws" and (.display_name | test("ap-northeast-1")))'
{
  "cloud_provider": "aws",
  "display_name": "Tokyo (ap-northeast-1)",
  "region_id": "aws-ap-northeast-1"
}
このようにして得られた結果からregion_idの値を構成情報に設定してください。

 node_spec情報を確認する!2025-08-20時点では、node_spec情報はv1betaのAPIから取得しているため、Organizationレベルかつ"Organization Owner"のAPI Keyが必要です。
terraform {
  required_providers {
    tidbcloud = {
      source = "tidbcloud/tidbcloud"
      version = "~> 0.4.3"
    }
  }
  required_version = ">= 1.0.0"
}

data "tidbcloud_cluster_specs" "spec" {
}

output "output" {
  value = data.tidbcloud_cluster_specs.spec
}
こちらも先程と同じコマンドで結果を得ることができます。
$ TIDBCLOUD_PUBLIC_KEY='xxx' TIDBCLOUD_PRIVATE_KEY='xxx' terraform apply -auto-approve
こちらもそのまま出力すると目当てのものを見つけるのが難しいため、以下のようにフィルタリングすると良いでしょう。
$ TIDBCLOUD_PUBLIC_KEY='xxx' TIDBCLOUD_PRIVATE_KEY='xxx' terraform output -json \
   | jq '.output.value.items[] | select(.cloud_provider=="AWS" and .cluster_type=="DEDICATED" and .region=="ap-northeast-1") | .tidb[] | .node_size'
"2C8G"
"4C16G"
"8C16G"
"8C32G"
"16C32G"
"16C64G"
"32C64G"

$ TIDBCLOUD_PUBLIC_KEY='xxx' TIDBCLOUD_PRIVATE_KEY='xxx' terraform output -json \
    | jq '.output.value.items[] | select(.cloud_provider=="AWS" and .cluster_type=="DEDICATED" and .region=="ap-northeast-1") | .tikv[] | .node_size'
"2C8G"
"4C16G"
"8C32G"
"8C64G"
"16C64G"
"16C64G-IO2"
"32C128G"
"32C128G-IO2"

 まとめ本記事ではTiDB Cloudに導入された新しいAPI Keyの管理と、Project API Keyを使ってTerraformでTiDB CloudのDedicatedクラスタを運用する方法を紹介しました。Terraformに限らず、APIをリクエストする際にもProject API Keyは使えますので、今後はProject API Keyを積極的に使うと良いでしょう。
GitHubで編集を提案
この記事について

新しいAPI Keyの管理について

v1beta1の導入

RBACの導入

Project API Keyの利用

TerraformでProject API Keyを使う

補足: 構成情報に記載する設定値について

region情報を確認する

node_spec情報を確認する

まとめ

Discussion
