Configuração típica do projeto lakebase com pacotes de automação declarativa

Importante

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

Esta página mostra um pacote completo de Pacotes de Automação Declarativa para um projeto de dimensionamento automático do Lakebase pronto para produção com os recursos mais usados:

  • Ramificação de produção protegida
  • Ponto de extremidade de leitura e gravação de alta disponibilidade (HA) com secundários legíveis
  • Permissão CAN_MANAGE embutida no nível do workspace para uma entidade de serviço
  • Transmissão contínua de tabela sincronizada do Unity Catalog
  • Vinculação do Unity Catalog para o banco de dados Lakebase
  • Aplicativo Databricks conectado ao projeto lakebase

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

Pré-requisitos

Antes de começar, você precisa de:

  • CLI do Databricks v1.0.0 ou superior. Para verificar sua versão, execute databricks --version. Para instalar ou atualizar, consulte Instalar ou atualizar a CLI do Databricks.
  • Um espaço de trabalho do Azure Databricks com o Lakebase habilitado.
  • Uma entidade de serviço configurada para autenticação do OAuth de máquina para máquina (M2M). O pacote concede a esse workspace principal a permissão CAN_MANAGE no projeto. Consulte Autorizar o acesso da entidade de serviço ao Azure Databricks com o OAuth e Gerenciar permissões do projeto.
  • Uma tabela Delta do Catálogo do Unity com o Feed de Dados de Alterações (CDF) habilitado para ser usada como fonte de sincronização. Remova os blocos postgres_synced_tables e postgres_catalogs se você não precisar de sincronização de dados.

Configuração completa do pacote

O pacote usa variáveis para todos os valores específicos do workspace. Defina-os em um .databricks/bundle/<target>/variables.json arquivo ou passe-os no momento da implantação com --var.

Quando você cria um projeto, o Azure Databricks cria automaticamente uma production ramificação, um primary endpoint de leitura e gravação, uma função de proprietário do Postgres vinculada à sua identidade e um databricks_postgres banco de dados. Para configurar esses recursos criados implicitamente, 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 do Lakebase cria automaticamente um databricks_postgres banco de dados de propriedade de uma função postgres vinculada à sua identidade. Esse pacote cria, em vez disso, um banco de dados separado com nome específico (${var.database_name}), pertencente a um perfil dedicado do aplicativo, para isolar os dados do aplicativo. Para usar o banco de dados implícito e o perfil diretamente, remova os blocos de recurso postgres_roles e postgres_databases, defina postgres_database: databricks_postgres diretamente em postgres_synced_tables e postgres_catalogs e atualize o recurso do aplicativo para database: ${resources.postgres_branches.production.name}/databases/databricks-postgres.

Para colocar a função de proprietário implícita e o banco de dados databricks_postgres sob gerenciamento de pacote, declare-os com replace_existing: true, usando seus IDs existentes. A ID do banco de dados é sempre databricks-postgres. A ID da função é derivada de sua identidade do Databricks em vez de ser um nome fixo, portanto, procure-a primeiro:

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

Em seguida, declare ambos os recursos, correspondendo a cada campo já definido na função. Omitir membership_roles remove a associação de DATABRICKS_SUPERUSER da função quando ela for adotada, portanto, 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 derrubar os recursos que esse pacote cria, execute databricks bundle destroy -t prod. Por padrão, o projeto é excluído de forma reversível e mantido por 7 dias antes da exclusão permanente, para que você possa recuperá-lo durante o período de retenção. Para excluir apenas o projeto imediatamente, use a CLI do Databricks com --purge ou remova o comentário purge_on_delete: true no recurso do projeto acima para excluí-lo permanentemente sempre que executar destroy:

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

Aplicar o pacote

Validar e implantar:

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

Se databricks bundle deploy não for concluída na primeira execução, execute-a novamente.

O que é implantado

O pacote cria os seguintes recursos:

  • Um projeto do Lakebase Autoscaling com as configurações padrão de computação que você especificou.
  • Uma ramificação protegida production.
  • Um ponto de extremidade primário de leitura e gravação com HA e secundários legíveis.
  • Um pipeline de sincronização contínua que envia em fluxo contínuo uma tabela Delta do Unity Catalog para o banco de dados do projeto.
  • Um catálogo do Unity Catalog com suporte do banco de dados Lakebase, consultável como dados do Unity Catalog.
  • Um aplicativo do Databricks conectado ao banco de dados do projeto.
  • Permissão CAN_MANAGE no workspace para a entidade de serviço que você especificou.

Recursos adicionais

  • Last updated on