メインコンテンツまでスキップ
に最終更新

Lakebase 向け Terraform を使い始める

このガイドは、Databricks Terraform プロバイダーを使用して Lakebase リソースを管理するための Terraform の使用を開始するのに役立ちます。プロジェクトを作成し、開発ブランチとエンドポイントを追加し、完了したらそれらを削除します。これは、開発環境とテスト環境を管理するための一般的なワークフローです。

ヒント

このガイドでは、利用可能な Terraform コマンドのサブセットについて説明します。完全なリソース リファレンスと使用可能なすべての構成オプションについては、 Terraform Registry の Databricks プロバイダーのドキュメントを参照してください。

前提条件​

始める前に、次のものが必要です。

Lakebase AutoscalingTerraformセマンティクス​

Lakebase Autoscaling リソースは、宣言的な状態管理のために仕様/ステータス フィールドを持つTerraformセマンティクスを使用します。 specフィールドは希望する状態を定義し、 statusフィールドは現在の状態を表示します。

備考

重要: ドリフト検出と Terraform 外部の変更

Terraform の外部 (UI、CLI、または API を使用) で Lakebase リソースに加えられた変更は、Terraform の標準ドリフト検出では検出されません。

spec/status フィールドの動作、ドリフト検出の動作、および状態管理の要件の詳細については、 databricks_postgres_projectリソースのドキュメントを参照してください。

リソース階層​

Lakebaseのリソースは親子階層構造になっています。親リソースを作成してから子リソースを作成し、子リソースを削除してから親リソースを削除します。完全なリソース モデル (プロジェクト、ブランチ、コンピュート、データベースなど) については、 「プロジェクト」を参照してください。

このガイドの操作順序: プロジェクト → ブランチ → エンドポイント

クイックスタート: Terraform を使用して Lakebase プロジェクトを管理する​

次のステップに従って、開発ブランチとコンピュート エンドポイントを含む完全に動作するプロジェクトを作成します。

1.認証を設定する​

前提条件で構成したサービスプリンシパルを使用して認証するようにDatabricksプロバイダーを構成します。 Lakebase リソースにはOAuth認証が必要なので、サービスプリンシパルのOAuth資格情報の環境変数を設定します。

Bash
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_CLIENT_ID="your-service-principal-client-id"
export DATABRICKS_CLIENT_SECRET="your-service-principal-secret"

次に、次の環境変数を使用するようにプロバイダーを構成します。

Terraform
terraform {
  required_version = ">= 1.0"

  required_providers {
    databricks = {
      source  = "databricks/databricks"
      version = "~> 1.0"
    }
  }
}

provider "databricks" {
  # Automatically uses DATABRICKS_HOST, DATABRICKS_CLIENT_ID,
  # and DATABRICKS_CLIENT_SECRET from environment variables
}

認証オプションとOAuth構成の詳細については、 OAuthを使用したDatabricksへのサービス プリンシパル アクセスの承認」およびDatabricks Terraformプロバイダー」を参照してください。

2. プロジェクトを作成する​

プロジェクトは、ブランチ、エンドポイント、データベース、およびロールを含む最上位のリソースです。

注記

プロジェクトを作成すると、 Databricks 、 primaryという名前の読み取り/書き込みコンピュート エンドポイントを使用して、 productionという名前のブランチを自動的にプロビジョニングします。 いずれかのリソースを構成するには（たとえば、エンドポイントで高可用性を有効にするには）、 replace_existing = trueと一致するdatabricks_postgres_branchまたはdatabricks_postgres_endpointを宣言します。Terraformは、既知のIDを照合することで、既存のリソースの所有権を取得します。

基本的なプロジェクトを作成します。

Hcl
resource "databricks_postgres_project" "app" {
  project_id = "my-app"
  spec = {
    pg_version             = 17
    display_name           = "My Application"
    enable_pg_native_login = false
  }
}

次のコマンドを実行して構成をフォーマットし、プロジェクトを作成します。

Bash
terraform fmt
terraform apply

enable_pg_native_login = false 新しいプロジェクトのデフォルトです。ネイティブのPostgresロールが静的パスワードで接続できるようにするには、trueに設定してください。パスワード接続の管理を参照してください。

注意

デフォルトでは、構成から databricks_postgres_project を削除して terraform apply を実行すると、プロジェクトが論理的に削除されます。7日間保持されます。プロジェクトをすぐに完全に削除するには、削除する前に purge_on_delete = true をリソース ブロックに追加します。詳細については、「ステップ 9: プロジェクトを削除する」を参照してください。

3. プロジェクトを取得する​

データソースを使用して、作成したばかりのプロジェクトに関する情報を取得します。

Hcl
data "databricks_postgres_project" "this" {
  name = databricks_postgres_project.app.name
}

output "project_name" {
  value = data.databricks_postgres_project.this.name
}

output "project_pg_version" {
  value = try(data.databricks_postgres_project.this.status.pg_version, null)
}

output "project_display_name" {
  value = try(data.databricks_postgres_project.this.status.display_name, null)
}
ヒント

データソースは、 statusフィールドの値を返します。 すべてのプロバイダー バージョンで使用できない可能性があるフィールドに安全にアクセスするには、 try()を使用します。

構成を適用し、プロジェクトの詳細を表示するには、次のコマンドを実行します。

Bash
terraform apply
terraform output

4. ブランチを作成する​

ブランチは、プロジェクト内で分離されたデータベース環境を提供します。

注記

プロジェクトを作成すると、デフォルトのブランチproductionが自動的に作成され、 primaryという名前の暗黙的な読み書きエンドポイントが含まれます。以下の dev ブランチのように追加のブランチを作成すると、新しいブランチごとに暗黙のprimary読み書きエンドポイントも取得されます。ステップ 5 では、そのエンドポイントをTerraform管理下に置く方法を示します。

この例では、開発ブランチを作成します。

Hcl
resource "databricks_postgres_branch" "dev" {
  branch_id = "dev"
  parent    = databricks_postgres_project.app.name
  spec = {
    no_expiry = true
  }
}

output "dev_branch_name" {
  value = databricks_postgres_branch.dev.name
}

ブランチを作成し、その名前を表示するには、次のコマンドを実行します。

Bash
terraform apply
terraform output dev_branch_name

5.エンドポイントを作成する​

エンドポイントは、ブランチに対してクエリを実行するためのコンピュート リソースを提供します。

注記

作成するすべてのブランチには、 primaryという名前の暗黙的に作成された読み書きエンドポイントが含まれます。Terraform の管理下に置き、独自の構成を適用するには、 databricks_postgres_endpointリソースをendpoint_id = "primary"で宣言し、 replace_existing = trueを設定します。これは、Terraformに対し、新しいエンドポイントを作成しようとするのではなく、既存のエンドポイントの所有権を取得するように指示するものです。replace_existingがない場合、apply は競合操作エラーで失敗します。

開発ブランチのプライマリエンドポイントの所有権を取得し、そこに設定を適用します。

Hcl
resource "databricks_postgres_endpoint" "dev_primary" {
  endpoint_id = "primary"
  parent      = databricks_postgres_branch.dev.name
  spec = {
    endpoint_type = "ENDPOINT_TYPE_READ_WRITE"
  }
  replace_existing = true
}

output "dev_endpoint_name" {
  value = databricks_postgres_endpoint.dev_primary.name
}

設定を適用し、エンドポイント名を確認するには、以下のコマンドを実行してください。

Bash
terraform apply
terraform output dev_endpoint_name

読み取り専用レプリカやカスタム オートスケールなど、他のエンドポイント パターンについては、 databricks_postgres_endpointリファレンスを参照してください。

6. エンドポイントを一覧表示する​

開発ブランチ内のエンドポイントを一覧表示して、作成した読み取り/書き込みエンドポイントの詳細を表示します。

Hcl
data "databricks_postgres_endpoints" "dev" {
  parent = databricks_postgres_branch.dev.name
}

output "dev_endpoint_names" {
  value = [for e in data.databricks_postgres_endpoints.dev.endpoints : e.name]
}

output "dev_endpoint_types" {
  value = [
    for e in data.databricks_postgres_endpoints.dev.endpoints :
    try(e.status.endpoint_type, null)
  ]
}

構成を適用し、エンドポイントの詳細を表示するには、次のコマンドを実行します。

Bash
terraform apply
terraform output dev_endpoint_names
terraform output dev_endpoint_types
ヒント

terraform applyを実行し、出力のみが変更された場合（インフラストラクチャは変更されません）、Terraform は「出力の変更」を表示し、リソースを変更せずに状態を更新します。

7. ブランチを一覧表示する​

プロジェクト内のすべてのブランチを一覧表示します。これにより、プロジェクトで自動的に作成された本番運用ブランチと、前のステップで作成した開発ブランチの 2 つのブランチが返されます。

Hcl
data "databricks_postgres_branches" "all" {
  parent = databricks_postgres_project.app.name
}

output "branch_names" {
  value = [for b in data.databricks_postgres_branches.all.branches : b.name]
}

構成を適用し、ブランチ名を表示するには、次のコマンドを実行します。

Bash
terraform apply
terraform output branch_names

8. ブランチを削除する​

ここで、先ほど作成した開発ブランチを削除します。これは典型的なワークフローです。開発またはテスト用のブランチを作成し、終了したら削除します。

構成から宣言を削除し、terraform applyを実行することでリソースを削除します。Terraform は、宣言されなくなったリソースを破棄するように計画します。

構成ファイルから以下を削除してください:

  • databricks_postgres_branch.dev リソースとその出力。
  • databricks_postgres_endpoint.dev_primary リソースとその出力。
  • 削除されたブランチを参照するすべてのデータソース。例えば、ステップ6のdata "databricks_postgres_endpoints" "dev"ブロック（およびそのdev_endpoint_namesとdev_endpoint_types出力）は、ブランチがなくなるとparent = databricks_postgres_branch.dev.nameが失敗するためです。

次に変更を適用してください:

Bash
terraform apply

確認する前に、破棄計画を確認してください。

注記

Terraform は、自身のブランチより先にエンドポイントを破棄します。エンドポイントのparent = databricks_postgres_branch.dev.nameは依存関係を作成するため、Terraform は追加の構成なしで操作を正しく順序付けします。

9. プロジェクトを削除する。​

構成から databricks_postgres_project を削除して terraform apply を実行すると、Terraform はデフォルトでプロジェクトを論理的に削除します。プロジェクトは7日間保持され、その間は復元できます。その後、Lakebase が完全に削除します。

プロジェクトおよびすべての子リソースを削除するには、構成から削除して実行します。

Bash
terraform apply

Terraform は依存関係グラフを使用して、正しい順序でリソースを破棄します。確認する前に、破棄計画を確認してください。

プロジェクトを直ちに完全に削除するには、構成から削除する前にリソースで purge_on_delete = true を設定します。

Hcl
resource "databricks_postgres_project" "app" {
  project_id      = "my-app"
  purge_on_delete = true  # Permanently delete on apply. Omit to soft-delete (7-day retention).
  spec = {
    pg_version   = 17
    display_name = "My Application"
  }
}

terraform apply を実行してフラグを状態にプッシュし、その後、構成からリソースを削除して terraform apply を再度実行してください。

注記

7日間の保持期間中に論理削除されたプロジェクトと同じ project_id で新しいプロジェクトを作成すると、失敗します。同じプロジェクトIDを再利用するには、まず既存のプロジェクトを復元するか、purge_on_delete = trueで強制的に完全削除するか、保持期間が終了するまで待機します。

7日間の保持期間が終了する前に論理削除されたプロジェクトを復元するには、CLIまたはAPIを使用します。

ヒント

本番運用のプロジェクトが誤って削除されるのを防ぐには、lifecycle ブロックを追加します：

Hcl
resource "databricks_postgres_project" "app" {
  project_id = "my-app"
  spec       = { ... }

  lifecycle {
    prevent_destroy = true
  }
}

これにより、プロジェクトが削除される代わりに terraform apply がエラーで失敗します。意図的にリソースを破棄したい場合は、prevent_destroy = true を削除します。

兄弟リソースをシリアル化します depends_on​

Lakebaseは、単一のブランチ内で一度に1つのロール、データベース、またはエンドポイント操作のみを処理します。同じブランチでこのような兄弟リソースを 2 つ宣言し、Terraform がそれらの間に依存関係エッジ (たとえば、 spec.roleを介してロールを参照するデータベース) を既に持っていない場合、Terraform はそれらを並行して作成しようとしますが、どちらか一方が競合操作エラーで失敗します。

解決策は、明示的にdepends_on追加して、Terraform が apply をシリアル化するようにすることです。

Hcl
resource "databricks_postgres_role" "schema_owner" {
  role_id = "schemamigrator"
  parent  = databricks_postgres_branch.main.name
  spec = {
    postgres_role    = "schemamigrator"
    membership_roles = ["DATABRICKS_SUPERUSER"]
  }
}

resource "databricks_postgres_role" "application" {
  role_id = "application"
  parent  = databricks_postgres_branch.main.name
  spec = {
    postgres_role = "application"
  }

  depends_on = [databricks_postgres_role.schema_owner]
}

その他のリソース​

このページの見出し