선언적 자동화 번들을 사용한 일반적인 Lakebase 프로젝트 설정

Important

Lakebase에 대한 선언적 자동화 번들 지원은 현재 베타 단계입니다.

이 페이지에서는 가장 일반적으로 사용되는 기능이 포함된, 프로덕션 환경에 바로 사용할 수 있는 Lakebase 프로젝트용 전체 Declarative Automation Bundles 번들을 보여줍니다:

보호된 프로덕션 분기
읽을 수 있는 보조 복제본이 있는 고가용성(HA) 읽기/쓰기 엔드포인트
서비스 주체에 대한 인라인 작업 영역 수준의 CAN_MANAGE 권한
Unity 카탈로그에서 연속 동기화된 테이블 스트리밍
Lakebase 데이터베이스에 대한 Unity 카탈로그 바인딩
Lakebase 프로젝트에 연결된 Databricks 앱

Lakebase를 사용한 선언적 자동화 번들에 대한 단계별 소개는 선언적 자동화 번들을 사용하여 Lakebase 관리를 참조하세요.

사전 요구 사항

이 작업을 시작하려면 다음이 필요합니다.

Databricks CLI v1.0.0 이상. 버전을 확인하려면 databricks --version을(를) 실행합니다. 설치 또는 업그레이드하려면 Databricks CLI 설치 또는 업데이트를 참조하세요.
Lakebase를 사용하도록 설정된 Azure Databricks 작업 영역입니다.
OAuth M2M(컴퓨터 대 컴퓨터) 인증을 위해 구성된 서비스 주체입니다. 번들은 프로젝트에 대해 이 주 작업 영역 CAN_MANAGE 권한을 부여합니다. OAuth 및 프로젝트 관리 권한을 사용하여 Azure Databricks에 대한 서비스 주체 액세스 권한 부여를 참조하세요.
동기화 원본으로 사용할 수 있도록 CDF(변경 데이터 피드)가 설정된 Unity 카탈로그 델타 테이블입니다. 데이터 동기화가 필요하지 않으면 postgres_synced_tables 및 postgres_catalogs 블록을 제거하세요.

전체 번들 구성

번들은 모든 작업 영역마다 다른 값에 대해 변수를 사용합니다. .databricks/bundle/<target>/variables.json 파일에 설정하거나 배포 시 --var로 전달하세요.

프로젝트를 만들면 Azure Databricks는 자동으로 production 브랜치, primary 읽기-쓰기 엔드포인트, 사용자 ID에 연결된 소유자 Postgres 역할 및 databricks_postgres 데이터베이스를 생성합니다. 이러한 암시적으로 만든 리소스를 구성하려면 .을 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

모든 Lakebase 프로젝트는 사용자 신원에 연결된 Postgres 역할이 소유한 databricks_postgres 데이터베이스를 자동으로 생성합니다. 이 번들은 대신 앱 데이터를 격리하도록, 전용 애플리케이션 역할이 소유하는 별도의 이름이 지정된 데이터베이스(${var.database_name})를 생성합니다. 암시적 데이터베이스와 역할을 직접 사용하려면 postgres_roles 및 postgres_databases 리소스 블록을 제거하고, postgres_database: databricks_postgres를 postgres_synced_tables 및 postgres_catalogs에 직접 설정하고, 앱 리소스를 database: ${resources.postgres_branches.production.name}/databases/databricks-postgres로 업데이트합니다.

대신 암시적 소유자 역할 및 databricks_postgres 데이터베이스를 번들 관리로 가져오려면 기존 ID를 사용하여 선언 replace_existing: true 합니다. 데이터베이스 ID는 항상 databricks-postgres. 역할 ID는 고정 이름이 아닌 Databricks ID에서 파생되므로 먼저 조회합니다.

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

그런 다음 역할에 이미 설정된 모든 필드와 일치하는 두 리소스를 선언합니다. membership_roles를 생략하면 채택될 때 역할에서 DATABRICKS_SUPERUSER 멤버십이 제거되므로, 이를 명시적으로 선언하세요.

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

이 번들이 생성한 리소스를 삭제하려면 databricks bundle destroy -t prod를 실행하세요. 기본적으로 프로젝트는 일시 삭제되고 영구 삭제되기 전에 7일 동안 보존되므로 보존 기간 동안 복구할 수 있습니다. 프로젝트만 즉시 삭제하려면 Databricks CLI에서 --purge를 사용하거나, 위의 프로젝트 리소스에서 purge_on_delete: true의 주석을 해제하여 삭제할 때마다 해당 프로젝트가 완전 삭제되도록 하세요:

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

번들 적용

유효성 검사 및 배포:

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

첫 번째 실행에서 완료되지 않은 경우 databricks bundle deploy 다시 실행합니다.

배포되는 항목

번들은 다음 리소스를 만듭니다.

지정하신 컴퓨팅 기본값이 있는 Lakebase 프로젝트입니다.
보호된 production 브랜치입니다.
HA 및 읽기 가능한 보조 데이터베이스가 있는 기본 읽기-쓰기 엔드포인트입니다.
Unity 카탈로그 델타 테이블을 프로젝트 데이터베이스로 스트리밍하는 연속 동기화 파이프라인입니다.
Lakebase 데이터베이스에서 지원되는 Unity 카탈로그 카탈로그로, Unity 카탈로그 데이터로 쿼리할 수 있습니다.
프로젝트 데이터베이스에 연결된 Databricks 앱입니다.
지정한 서비스 주체에 대한 작업 영역 CAN_MANAGE 권한입니다.

추가 리소스

고가용성 에서는 HA 패턴과 프로덕션 환경에서 사용 시기를 다룹니다.
동기화된 테이블로 Lakehouse 데이터 제공에서는 예약 옵션 및 파이프라인 관리를 다룹니다.
프로젝트 권한 관리에서는 작업 영역 수준 및 데이터베이스 수준 액세스 제어를 다룹니다.
사용자 지정 Databricks 앱을 Lakebase에 연결 하면 Databricks 앱을 자동 크기 조정 프로젝트에 연결하는 방법을 보여 줍니다.
선언적 자동화 번들 리소스는 완전한 선언적 자동화 번들 리소스 참조를 제공합니다.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2026-08-29