Penyiapan proyek Lakebase umum dengan Bundel Otomatisasi Deklaratif

Important

Dukungan Lakebase untuk Declarative Automation Bundles berada dalam Beta.

Halaman ini menampilkan bundel lengkap Bundel Otomasi Deklaratif untuk proyek Lakebase siap produksi dengan fitur-fitur yang paling umum digunakan:

  • Cabang produksi yang dilindungi
  • Titik akhir baca-tulis ketersediaan tinggi (HA) dengan sekunder yang dapat dibaca
  • Izin sebaris tingkat ruang kerja untuk service principal CAN_MANAGE
  • Streaming tabel yang disinkronkan berkelanjutan dari Katalog Unity
  • Penautan Unity Catalog untuk basis data Lakebase
  • Aplikasi Databricks terhubung ke proyek Lakebase

Untuk pengenalan langkah demi langkah tentang Bundel Otomatisasi Deklaratif dengan Lakebase, lihat Mengelola Lakebase dengan Bundel Otomatisasi Deklaratif.

Prasyarat

Sebelum memulai, Anda memerlukan:

  • Databricks CLI v1.0.0 atau yang lebih baru. Untuk memeriksa versi Anda, jalankan databricks --version. Untuk menginstal atau meningkatkan, lihat Menginstal atau memperbarui Databricks CLI.
  • Ruang kerja Azure Databricks dengan Lakebase diaktifkan.
  • Prinsipal layanan yang dikonfigurasi untuk autentikasi OAuth machine-to-machine (M2M). Bundel memberikan izin ruang CAN_MANAGE kerja utama ini pada proyek. Lihat Mengotorisasi akses perwakilan layanan ke Azure Databricks dengan izin OAuth dan Kelola proyek.
  • Tabel Delta Unity Catalog dengan Change Data Feed (CDF) yang diaktifkan untuk digunakan sebagai sumber sinkronisasi. Hapus blok postgres_synced_tables dan postgres_catalogs jika Anda tidak memerlukan sinkronisasi data.

Konfigurasi bundel lengkap

Paket ini menggunakan variabel untuk semua nilai khusus untuk setiap ruang kerja. Tetapkan di file .databricks/bundle/<target>/variables.json, atau teruskan saat deployment dengan --var.

Saat Anda membuat proyek, Azure Databricks secara otomatis membuat cabang production, endpoint baca-tulis primary, peran pemilik di Postgres yang terkait dengan identitas Anda, dan database databricks_postgres. Untuk mengonfigurasi sumber daya yang dibuat secara implisit ini, deklarasikan dengan replace_existing: true.

bundle:
  name: lakebase-typical-project

variables:
  project_id:
    description: 'Lakebase project ID (lowercase, hyphen-delimited)'
    default: 'my-lakebase-project'
  display_name:
    description: 'Human-readable project name shown in the UI'
    default: 'My Lakebase project'
  pg_version:
    description: 'Postgres major version'
    default: 17
  min_cu:
    description: 'Minimum compute units on the default endpoint'
    default: 0.5
  max_cu:
    description: 'Maximum compute units on the default endpoint'
    default: 4.0
  suspend_timeout:
    description: 'Idle time before the default endpoint suspends. Ignored when no_suspension is true.'
    default: '300s'
  admin_sp_app_id:
    description: 'Application ID of the service principal to grant CAN_MANAGE on the project'
    default: '<your-sp-application-id>'
  source_table:
    description: 'Unity Catalog three-part name of the Delta table to sync (catalog.schema.table)'
    default: '<catalog>.<schema>.<table>'
  primary_key_column:
    description: 'Primary key column of the source Delta table'
    default: '<pk>'
  storage_catalog:
    description: 'Unity Catalog catalog where the sync pipeline stores its metadata'
    default: '<catalog>'
  storage_schema:
    description: 'Unity Catalog schema where the sync pipeline stores its metadata'
    default: '<schema>'
  app_name:
    description: 'Databricks App name (must be unique in the workspace)'
    default: 'my-lakebase-app'
  uc_catalog_id:
    description: 'Name to register the Lakebase database in Unity Catalog'
    default: 'my_lakebase_uc_catalog'
  database_name:
    description: 'Postgres-internal name for the app database'
    default: 'app_database'

targets:
  prod:
    default: true
    workspace:
      host: https://<your-workspace>.cloud.databricks.com

    resources:
      # Project — top-level container for branches, endpoints, and databases.
      # The permissions block grants workspace-level CAN_MANAGE to the service principal.
      postgres_projects:
        lakebase_project:
          project_id: ${var.project_id}
          # purge_on_delete: true  # Uncomment to permanently delete on destroy (default: soft delete, 7-day retention).
          pg_version: ${var.pg_version}
          display_name: ${var.display_name}
          default_endpoint_settings:
            autoscaling_limit_min_cu: ${var.min_cu}
            autoscaling_limit_max_cu: ${var.max_cu}
            suspend_timeout_duration: ${var.suspend_timeout}
          permissions:
            - service_principal_name: ${var.admin_sp_app_id}
              level: CAN_MANAGE

      # Configure the implicitly created production branch as protected.
      postgres_branches:
        production:
          branch_id: production
          parent: ${resources.postgres_projects.lakebase_project.name}
          no_expiry: true
          is_protected: 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.
      postgres_endpoints:
        primary:
          endpoint_id: primary
          parent: ${resources.postgres_branches.production.name}
          endpoint_type: ENDPOINT_TYPE_READ_WRITE
          autoscaling_limit_min_cu: ${var.min_cu}
          autoscaling_limit_max_cu: ${var.max_cu}
          no_suspension: true
          group:
            min: 2
            max: 2
            enable_readable_secondaries: true
          replace_existing: true

      # Postgres role that owns the app database.
      postgres_roles:
        app_role:
          role_id: app-role # Resource ID: lowercase letters, digits, and hyphens.
          parent: ${resources.postgres_branches.production.name}
          postgres_role: app_role # Postgres identifier: lowercase letters, digits, and underscores.

      # Named Postgres database for the app.
      postgres_databases:
        app_db:
          database_id: app-database
          parent: ${resources.postgres_branches.production.name}
          postgres_database: ${var.database_name}
          role: ${resources.postgres_roles.app_role.id}

      # Sync a Unity Catalog Delta table into the project continuously.
      postgres_synced_tables:
        orders_sync:
          synced_table_id: '${var.storage_catalog}.${var.storage_schema}.orders_synced'
          branch: ${resources.postgres_branches.production.name}
          postgres_database: ${var.database_name}
          source_table_full_name: ${var.source_table}
          primary_key_columns:
            - ${var.primary_key_column}
          scheduling_policy: CONTINUOUS
          create_database_objects_if_missing: true
          new_pipeline_spec:
            storage_catalog: ${var.storage_catalog}
            storage_schema: ${var.storage_schema}

      # Bind the Lakebase database into Unity Catalog so it is queryable as UC data.
      postgres_catalogs:
        lakebase_uc_catalog:
          catalog_id: ${var.uc_catalog_id}
          postgres_database: ${var.database_name}
          branch: ${resources.postgres_branches.production.name}
          create_database_if_missing: true

      # Databricks App connected to the project.
      # Update source_code_path to point to your app source directory.
      apps:
        lakebase_app:
          name: ${var.app_name}
          description: 'App backed by Lakebase autoscaling'
          source_code_path: ./app_src
          config:
            command:
              - flask
              - run
              - --host=0.0.0.0
              - --port=8000
          resources:
            - name: lakebase-db
              postgres:
                branch: ${resources.postgres_branches.production.name}
                database: ${resources.postgres_databases.app_db.name}
                permission: CAN_CONNECT_AND_CREATE

Note

Setiap proyek Lakebase secara otomatis membuat databricks_postgres database yang dimiliki oleh peran Postgres yang terkait dengan identitas Anda. Bundel ini membuat database bernama terpisah (${var.database_name}) yang dimiliki oleh peran aplikasi khusus untuk mengisolasi data aplikasi sebagai gantinya. Untuk menggunakan database dan peran implisit secara langsung, hapus postgres_roles blok sumber daya dan postgres_databases , atur postgres_database: databricks_postgres langsung pada postgres_synced_tables dan postgres_catalogs, dan perbarui sumber daya aplikasi ke database: ${resources.postgres_branches.production.name}/databases/databricks-postgres.

Untuk menempatkan peran pemilik implisit dan database databricks_postgres di bawah pengelolaan bundel, sebaliknya, deklarasikan keduanya dengan replace_existing: true menggunakan ID yang sudah ada. ID database selalu databricks-postgres. ID peran berasal dari identitas Databricks Anda daripada menjadi nama tetap, jadi cari terlebih dahulu:

databricks postgres list-roles projects/<project-id>/branches/production

Kemudian deklarasikan kedua resource, dengan mencocokkan setiap field yang sudah ditetapkan pada role. Menghilangkan membership_roles akan menghapus keanggotaan DATABRICKS_SUPERUSER dari peran saat peran tersebut diadopsi, jadi nyatakan secara eksplisit:

postgres_roles:
  owner:
    role_id: <role-id-from-list-roles>
    parent: ${resources.postgres_branches.production.name}
    postgres_role: user@databricks.com # Or the service principal application ID.
    identity_type: USER # Or SERVICE_PRINCIPAL.
    membership_roles:
      - DATABRICKS_SUPERUSER
    replace_existing: true

postgres_databases:
  databricks_postgres:
    database_id: databricks-postgres
    parent: ${resources.postgres_branches.production.name}
    postgres_database: databricks_postgres
    role: ${resources.postgres_roles.owner.id}
    replace_existing: true

Note

Untuk menghapus sumber daya yang dibuat oleh bundel ini, jalankan databricks bundle destroy -t prod. Secara default, proyek dihapus sementara dan dipertahankan selama 7 hari sebelum penghapusan permanen, sehingga Anda dapat memulihkannya selama periode retensi. Untuk langsung menghapus hanya proyek tersebut, gunakan Databricks CLI dengan --purge, atau hapus tanda komentar pada purge_on_delete: true di sumber daya proyek di atas untuk menghapusnya secara permanen setiap kali proses penghancuran dijalankan:

databricks postgres delete-project projects/<project-id> --purge

Terapkan bundel

Validasi dan sebarkan:

databricks bundle validate -t prod
databricks bundle deploy -t prod

Jika databricks bundle deploy tidak selesai pada eksekusi pertama, jalankan kembali.

Apa yang akan diterapkan

Bundel membuat sumber daya berikut:

  • Sebuah proyek Lakebase dengan default komputasi yang Anda tentukan.
  • Cabang production yang dilindungi.
  • Endpoint baca-tulis utama dengan HA dan replika sekunder yang dapat dibaca.
  • Alur sinkronisasi berkelanjutan yang mengalirkan tabel Delta Katalog Unity ke dalam database proyek.
  • Katalog Unity yang didukung oleh database Lakebase, dapat dikueri sebagai data Unity Catalog.
  • Aplikasi Databricks yang tersambung ke database proyek.
  • Izin ruang kerja CAN_MANAGE untuk prinsipal layanan yang Anda tentukan.

Sumber daya tambahan

  • Last updated on