Terraform を使用した一般的な Lakebase プロジェクトのセットアップ

Important

LakebaseのTerraformサポートはベータ版です。

このページでは、最も一般的に使用される機能を備えた、運用対応の Lakebase 自動スケーリングプロジェクトの完全な Terraform 構成を示します。

保護された運用ブランチ
読み取り可能なセカンダリを使用した高可用性 (HA) 読み取り/書き込みエンドポイント
DATABRICKS_SUPERUSER を持つデータベース特権付きサービスプリンシパル
アプリ所有 Postgres データベース
Databricks SQL およびノートブックからの Lakehouse Federation クエリに使用するため、Unity Catalog に登録された Postgres データベース
Unity カタログから継続的に同期されたテーブルストリーミング
Lakebase プロジェクトに接続されている Databricks アプリ

Lakebase を使用した Terraform の詳細な概要については、「Lakebase 用 Terraform の概要」を参照してください。

前提条件

開始する前に、次の項目を用意する必要があります。

Terraform がインストールされている (バージョン 1.0 以降)。「Terraform のインストール」を参照してください。
Lakebase プロジェクトに対する CAN_MANAGE アクセス許可を持つ OAuth マシン間 (M2M) 認証用に構成されたサービスプリンシパル。 OAuth を使用した Azure Databricks へのサービスプリンシパルアクセスの承認とプロジェクトのアクセス許可の管理に関するページを参照してください。
同期ソースとして使用できるように変更データフィード (CDF) が有効になっている Unity カタログデルタテーブル。

完全な構成

プロジェクトを作成すると、Azure Databricksproductionブランチ、primary読み取り/書き込みエンドポイント、ID に関連付けられた所有者 Postgres ロール、およびdatabricks_postgres データベースが自動的に作成されます。これらの暗黙的に作成されたリソースを構成するには、 replace_existing = trueを使用して Terraform で宣言します。詳細については、 databricks_postgres_branch、 databricks_postgres_endpoint、 databricks_postgres_role、および databricks_postgres_databaseに関するページを参照してください。

警告

この構成では、is_protected = true ブランチにproductionを設定し、ブランチ仕様にワイヤードされたunprotect_for_destroy変数を含みます。 Terraform は保護されたブランチを含むプロジェクトを削除できません。また、 production ブランチはプロジェクトによって制御されるため、直接削除することはできません。リソースをクリーンに破棄するには、次の 2 段階の破棄を使用します。

# Step 1: unprotect the branch
terraform apply -var="unprotect_for_destroy=true"

# Step 2: destroy all resources
terraform destroy -var="unprotect_for_destroy=true"

terraform destroyの実行後、プロジェクトは論理的に削除され、完全に削除されるまで 7 日間保持されます。直ちに完全に削除するには、破棄を実行する前に、purge_on_delete = true リソースにdatabricks_postgres_projectを設定します。

variable "admin_sp_app_id" {
  description = "Application ID of the service principal to grant admin access"
  type        = string
}

variable "unprotect_for_destroy" {
  description = "Set to true before destroy to unprotect the production branch"
  type        = bool
  default     = false
}

# Project — top-level container for branches, endpoints, databases, and roles.
resource "databricks_postgres_project" "this" {
  project_id = "my-lakebase-project"
  # purge_on_delete = true  # Uncomment to permanently delete on destroy (default: soft delete, 7-day retention).
  spec = {
    pg_version   = 17
    display_name = "My Lakebase Project"
    default_endpoint_settings = {
      autoscaling_limit_min_cu = 0.5
      autoscaling_limit_max_cu = 4.0
      suspend_timeout_duration = "300s"
    }
  }
}

# Configure the implicitly created production branch as protected.
resource "databricks_postgres_branch" "production" {
  branch_id = "production"
  parent    = databricks_postgres_project.this.name
  spec = {
    no_expiry    = true
    is_protected = var.unprotect_for_destroy ? false : true
  }
  replace_existing = true
}

# Configure the implicitly created primary endpoint with HA.
# HA requires no_suspension = true. group.min = 2 adds a standby for automatic failover.
resource "databricks_postgres_endpoint" "primary" {
  endpoint_id = "primary"
  parent      = databricks_postgres_branch.production.name
  spec = {
    endpoint_type            = "ENDPOINT_TYPE_READ_WRITE"
    autoscaling_limit_min_cu = 0.5
    autoscaling_limit_max_cu = 4.0
    no_suspension            = true
    group = {
      min                         = 2
      max                         = 2
      enable_readable_secondaries = true
    }
  }
  replace_existing = true
}

# Grant workspace-level CAN_MANAGE on the project to the service principal.
# Use status.project_id (bare ID) not .name (full resource path) — the permissions
# API rejects the full path with a "resource type not found" error.
resource "databricks_permissions" "project" {
  database_project_name = databricks_postgres_project.this.status.project_id
  access_control {
    service_principal_name = var.admin_sp_app_id
    permission_level       = "CAN_MANAGE"
  }
}

# Create a Postgres role backed by the service principal with full database privileges.
# depends_on serializes creation — Lakebase processes one branch operation at a time.
resource "databricks_postgres_role" "admin_sp" {
  role_id = "admin-sp"
  parent  = databricks_postgres_branch.production.name
  spec = {
    identity_type    = "SERVICE_PRINCIPAL"
    postgres_role    = var.admin_sp_app_id
    auth_method      = "LAKEBASE_OAUTH_V1"
    membership_roles = ["DATABRICKS_SUPERUSER"]
    attributes = {
      createdb   = true
      createrole = true
      bypassrls  = true
    }
  }
  depends_on = [databricks_postgres_endpoint.primary]
}

# Create a Postgres database owned by the admin SP role.
resource "databricks_postgres_database" "app" {
  database_id = "app"
  parent      = databricks_postgres_branch.production.name
  spec = {
    postgres_database = "app"
    role              = databricks_postgres_role.admin_sp.name
  }
}

# Register the Postgres database in Unity Catalog. This makes the database queryable
# from Databricks SQL and notebooks through Lakehouse Federation, and serves as the
# parent namespace for synced tables that live inside the Lakebase Catalog.
# create_database_if_missing is set explicitly because the database is managed by
# the databricks_postgres_database resource above.
resource "databricks_postgres_catalog" "app_catalog" {
  catalog_id = "app_catalog"
  spec = {
    postgres_database          = databricks_postgres_database.app.status.postgres_database
    branch                     = databricks_postgres_branch.production.name
    create_database_if_missing = false
  }
}

# Sync a Unity Catalog Delta table into the Lakebase database continuously.
# Prefixing synced_table_id with the Lakebase Catalog name places the synced table
# inside the catalog so it's discoverable alongside the rest of the catalog's contents.
# postgres_database references the catalog's status, which implicitly orders this
# resource after the catalog without an explicit depends_on.
resource "databricks_postgres_synced_table" "orders" {
  synced_table_id = "app_catalog.default.orders_synced"
  spec = {
    branch                             = databricks_postgres_branch.production.name
    postgres_database                  = databricks_postgres_catalog.app_catalog.status.postgres_database
    source_table_full_name             = "my_catalog.default.orders"
    primary_key_columns                = ["order_id"]
    scheduling_policy                  = "CONTINUOUS"
    create_database_objects_if_missing = true
    new_pipeline_spec = {
      storage_catalog = "my_catalog"
      storage_schema  = "default"
    }
  }
}

# Databricks App connected to the Lakebase project.
# database must be the full resource name (databricks_postgres_database.app.name),
# not the Postgres database name. permission must be "CAN_CONNECT_AND_CREATE".
resource "databricks_app" "this" {
  name        = "my-lakebase-app"
  description = "App backed by Lakebase autoscaling project"
  depends_on  = [databricks_postgres_database.app]
  resources = [{
    name = "lakebase-db"
    postgres = {
      branch     = databricks_postgres_branch.production.name
      database   = databricks_postgres_database.app.name
      permission = "CAN_CONNECT_AND_CREATE"
    }
  }]
}

Note

この構成では、暗黙的な所有者ロールとadmin_sp データベースを管理するのではなく、個別のロール (app) とデータベース (databricks_postgres) を作成します。代わりに、これらの暗黙的なリソースを Terraform 管理の下に置くには、既存の ID を使用して replace_existing = true で宣言します。データベース ID は常に databricks-postgres。ロール ID は、ブランチを作成した ID 情報に基づいて生成されます。ユーザーの場合はメールアドレスの @ より前の部分（英小文字に変換し、英数字以外の文字はハイフンに置き換えたもの）が使用され、サービスプリンシパルの場合は sp-<application-id> が使用されます。正確な数値がわからない場合は、手作業で導出するのではなく、LakebaseアプリやPostgres APIから読み取ってください。

spec.membership_roles では適用のたびに、マージするのではなく、ロールのメンバーシップを上書きします。一覧に DATABRICKS_SUPERUSER したままにします。そのままにすると、ロールのすべてのメンバーシップが削除されます。

resource "databricks_postgres_role" "owner" {
  role_id = "jane-doe" # normalized login of the creating identity
  parent  = databricks_postgres_branch.production.name
  spec = {
    postgres_role    = "jane.doe@databricks.com" # the raw login
    membership_roles = ["DATABRICKS_SUPERUSER"]
    attributes = {
      createdb   = true
      createrole = true
      bypassrls  = true
    }
  }
  replace_existing = true
}

resource "databricks_postgres_database" "databricks_postgres" {
  database_id = "databricks-postgres"
  parent      = databricks_postgres_branch.production.name
  spec = {
    postgres_database = "databricks_postgres"
    # spec.role is omitted, so the database keeps its existing owner.
  }
  replace_existing = true
}

その他のリソース

高可用性は、HA パターンと、運用環境で使用するタイミングについて説明します。
同期テーブルでは、スケジュールオプションとパイプライン管理について説明します。
プロジェクトのアクセス許可の管理には、ワークスペースレベルとデータベースレベルのアクセス制御が含まれます。
Databricks Apps と Lakebase では、アプリを自動スケールプロジェクトに接続する方法を示します。
Terraform Registry には、完全なリソース参照が用意されています。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-08-19