Configuração típica de projetos Lakebase com Pacotes de Automação Declarativa

Importante

O suporte para Declarative Automation Bundles para Lakebase está em fase Beta.

Esta página mostra um pacote completo de Declarative Automation Bundles para um projeto Lakebase Autoscaling pronto para produção com as funcionalidades mais usadas:

  • Ramo de produção protegido
  • Endpoint de leitura-escrita de alta disponibilidade (HA) com secundários legíveis
  • Permissão ao nível CAN_MANAGE do espaço de trabalho inline para um principal de serviço
  • Fluxo contínuo de tabelas sincronizadas a partir do Unity Catalog
  • Ligação do Catálogo Unity para a base de dados Lakebase
  • Aplicação Databricks ligada ao projeto Lakebase

Para uma introdução passo a passo aos Pacotes de Automação Declarativa com Lakebase, consulte Gerir o Lakebase com Pacotes de Automação Declarativa.

Pré-requisitos

Antes de começar, você precisa:

  • Databricks CLI v1.0.0 ou posterior. Para verificar a sua versão, execute databricks --version. Para instalar ou atualizar, consulte Instalar ou atualizar a CLI do Databricks.
  • Um espaço de trabalho Azure Databricks com Lakebase ativado.
  • Uma entidade de serviço configurada para autenticação OAuth de máquina a máquina (M2M). O pacote atribui a este espaço de trabalho principal CAN_MANAGE permissão no projeto. Consulte Autorizar o acesso do principal de serviço ao Azure Databricks com OAuth e Gerenciar permissões de projeto.
  • Uma tabela Delta do Unity Catalog com o Change Data Feed (CDF) ativado para ser utilizada como fonte de sincronização. Remove os blocos postgres_synced_tables e postgres_catalogs se não precisares de sincronizar dados.

Configuração completa do pacote

O conjunto utiliza variáveis para todos os valores específicos do espaço de trabalho. Defina-os num .databricks/bundle/<target>/variables.json ficheiro, ou passe no momento de implementação com --var.

Quando cria um projeto, o Azure Databricks cria automaticamente um ramo production, um ponto final primary de leitura e escrita, uma função de proprietário do Postgres associada à sua identidade e uma base de dados databricks_postgres. Para configurar estes recursos implícitamente criados, declare-os com 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 projeto Lakebase cria automaticamente uma databricks_postgres base de dados detida por uma função do Postgres associada à sua identidade. Este pacote cria uma base de dados separada com nome (${var.database_name}) pertencente a um papel dedicado da aplicação para isolar os dados da aplicação em vez disso. Para utilizar diretamente a base de dados implícita e a função, remova os blocos de recursos postgres_roles e postgres_databases, defina postgres_database: databricks_postgres diretamente em postgres_synced_tables e postgres_catalogs, e atualize o recurso da aplicação para database: ${resources.postgres_branches.production.name}/databases/databricks-postgres.

Para passar a função implícita de proprietário e a base de dados databricks_postgres para a gestão do bundle, declare-os com replace_existing: true, utilizando os IDs existentes. O ID da base de dados é sempre databricks-postgres. O ID da função é derivado da tua identidade no Databricks, em vez de ser um nome fixo, por isso consulta-o primeiro:

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

Depois declara ambos os recursos, correspondendo a todos os campos já definidos na função. A omissão de membership_roles remove a associação de DATABRICKS_SUPERUSER da função quando esta é adotada, por isso, declare-a explicitamente:

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 destruir os recursos que este bundle cria, execute databricks bundle destroy -t prod. Por predefinição, o projeto é eliminado de forma recuperável e retido durante 7 dias antes da eliminação permanente, pelo que o pode recuperar durante o período de retenção. Para apagar apenas o projeto imediatamente, use a CLI do Databricks com --purge, ou descomente purge_on_delete: true no recurso do projeto acima para o eliminar permanentemente sempre que executar destroy:

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

Aplicar o pacote

Validar e implementar:

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

Se databricks bundle deploy não for concluído na primeira tentativa, execute-o novamente.

O que é implementado

O conjunto cria os seguintes recursos:

  • Um projeto de Autoscaling do Lakebase com os padrões de computação que especificaste.
  • Um ramo production protegido.
  • Um endpoint primário de leitura e escrita com HA e secundários acessíveis para leitura.
  • Uma canalização de sincronização contínua que transfere em fluxo contínuo uma tabela Delta do Unity Catalog para a base de dados do projeto.
  • Um catálogo do Unity Catalog suportado pela base de dados Lakebase, que pode ser consultado como dados do Unity Catalog.
  • Uma aplicação Databricks ligada à base de dados do projeto.
  • Permissão de espaço de trabalho CAN_MANAGE para o principal de serviço que especificaste.

Recursos adicionais

  • Last updated on