Configuración típica del proyecto de Lakebase con agrupaciones de automatización declarativa

Importante

El soporte de Declarative Automation Bundles para Lakebase está en fase beta.

Esta página muestra un paquete completo de Declarative Automation Bundles para un proyecto Lakebase listo para producción con las características más comúnmente usadas:

  • Rama de producción protegida
  • Punto de conexión de lectura y escritura de alta disponibilidad (HA) con secundarias legibles
  • Permiso de nivel CAN_MANAGE de área de trabajo insertado para una entidad de servicio
  • Streaming continuo de tablas sincronizadas desde el catálogo de Unity
  • Vinculación de Unity Catalog para la base de datos Lakebase
  • Aplicación de Databricks conectada al proyecto lakebase

Para obtener una introducción paso a paso sobre paquetes de automatización declarativa con Lakebase, consulte Administración de Lakebase con agrupaciones de automatización declarativa.

Prerequisites

Antes de comenzar, necesita lo siguiente:

Configuración completa del paquete

La agrupación usa variables para todos los valores específicos del área de trabajo. Defínalos en un archivo .databricks/bundle/<target>/variables.json o páselos durante la implementación con --var.

Al crear un proyecto, Azure Databricks crea automáticamente una production rama, un primary punto de conexión de lectura y escritura, un rol de Postgres propietario vinculado a la identidad y una databricks_postgres base de datos. Para configurar estos recursos creados implícitamente, declárelos con 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

Cada proyecto de Lakebase crea automáticamente una databricks_postgres base de datos propiedad de un rol de Postgres vinculado a su identidad. Este paquete crea una base de datos independiente con nombre propio (${var.database_name}), propiedad de un rol de aplicación dedicado, para aislar así los datos de la aplicación. Para usar directamente la base de datos implícita y el rol, quite los postgres_roles bloques de recursos y postgres_databases , establezca postgres_database: databricks_postgres directamente en postgres_synced_tables y postgres_catalogsy actualice el recurso de aplicación a database: ${resources.postgres_branches.production.name}/databases/databricks-postgres.

Para poner en su lugar el rol implícito de propietario y la base de datos databricks_postgres bajo la administración del paquete, declárelos con replace_existing: true usando sus identificadores existentes. El identificador de la base de datos es siempre databricks-postgres. El identificador de rol se deriva de la identidad de Databricks en lugar de ser un nombre fijo, por lo que debe buscarlo primero:

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

A continuación, declare ambos recursos de modo que coincidan con todos los campos ya definidos del rol. Omitir membership_roles elimina la pertenencia de DATABRICKS_SUPERUSER al rol al adoptarlo, por lo que debe declararse explícitamente:

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

Para anular los recursos que crea esta agrupación, ejecute databricks bundle destroy -t prod. De forma predeterminada, el proyecto se elimina temporalmente y se conserva durante 7 días antes de la eliminación permanente, por lo que puede recuperarlo durante el período de retención. Para eliminar únicamente el proyecto de inmediato, use la CLI de Databricks con --purge, o quite la marca de comentario purge_on_delete: true en el recurso del proyecto anterior para eliminarlo de forma permanente en cada operación de destrucción:

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

Aplicar el paquete

Validar e implementar:

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

Si databricks bundle deploy no se completa en la primera ejecución, vuelva a ejecutarla.

¿Qué se implementa?

La agrupación crea los siguientes recursos:

  • Un proyecto Lakebase con los valores predeterminados de cómputo que has especificado.
  • Rama production protegida.
  • Un punto de conexión de lectura y escritura principal con alta disponibilidad y secundarias legibles.
  • Una canalización de sincronización continua que transmite una tabla Delta del catálogo de Unity a la base de datos del proyecto.
  • Un catálogo de Unity Catalog respaldado por la base de datos Lakebase, consultable como datos de Unity Catalog.
  • Una aplicación de Databricks conectada a la base de datos del proyecto.
  • Permiso de área de trabajo CAN_MANAGE para la entidad de servicio que especificó.

Recursos adicionales

  • Last updated on