Configuration de projet Lakebase classique avec des bundles Automation déclaratifs

Important

Le support des Declarative Automation Bundles pour Lakebase est en version Bêta.

Cette page présente un ensemble complet de Déclarative Automation Bundles pour un projet Lakebase prêt à la production avec les fonctionnalités les plus couramment utilisées :

  • Branche de production protégée
  • Point de terminaison de haute disponibilité en lecture-écriture avec des réplicas secondaires lisibles
  • Autorisation CAN_MANAGE au niveau de l’espace de travail définie en ligne pour un principal de service
  • Streaming continu de tables synchronisées à partir du catalogue Unity
  • Liaison Unity Catalog pour la base de données Lakebase
  • Databricks App connecté au projet Lakebase

Pour une introduction pas à pas à Declarative Automation Bundles avec Lakebase, consultez Gérer Lakebase avec Declarative Automation Bundles.

Prerequisites

Avant de commencer, vous avez besoin des éléments suivants :

Configuration complète de l’offre groupée

Le bundle utilise des variables pour toutes les valeurs spécifiques à l’espace de travail. Définissez-les dans un .databricks/bundle/<target>/variables.json fichier ou transmettez-les au moment du déploiement avec --var.

Lorsque vous créez un projet, Azure Databricks crée automatiquement une production branche, un point de terminaison en lecture-écriture, un primary rôle Postgres propriétaire lié à votre identité et une databricks_postgres base de données. Pour configurer ces ressources créées implicitement, déclarez-les avec 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

Chaque projet Lakebase crée automatiquement une databricks_postgres base de données appartenant à un rôle Postgres lié à votre identité. Ce bundle crée une base de données nommée distincte (${var.database_name}) détenue par un rôle d’application dédié pour isoler les données d’application à la place. Pour utiliser directement la base de données implicite et le rôle, supprimez les blocs de ressources postgres_roles et postgres_databases, définissez directement postgres_database: databricks_postgres sur postgres_synced_tables et postgres_catalogs, et mettez à jour la ressource de l’application en database: ${resources.postgres_branches.production.name}/databases/databricks-postgres.

Pour placer plutôt le rôle implicite de propriétaire et la base de données databricks_postgres sous la gestion du bundle, déclarez-les avec replace_existing: true à l’aide de leurs identifiants existants. L’ID de base de données est toujours databricks-postgres. L’ID de rôle est dérivé de votre identité Databricks plutôt que d’être un nom fixe. Recherchez-le en premier :

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

Déclarez ensuite les deux ressources, correspondant à chaque champ déjà défini sur le rôle. Omettre membership_roles supprime l’appartenance DATABRICKS_SUPERUSER du rôle lorsqu’il est adopté, alors déclarez-la explicitement :

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

Pour supprimer les ressources créées par ce bundle, exécutez databricks bundle destroy -t prod. Par défaut, le projet est supprimé de manière réversible et conservé pendant 7 jours avant la suppression définitive. Vous pouvez donc le récupérer pendant la période de rétention. Pour supprimer uniquement le projet immédiatement, utilisez la CLI Databricks avec --purge, ou décommentez purge_on_delete: true dans la ressource du projet ci-dessus pour le supprimer définitivement à chaque destruction :

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

Appliquer l’offre groupée

Valider et déployer :

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

Si databricks bundle deploy ne se termine pas lors de la première exécution, exécutez-le de nouveau.

Ce qui est déployé

Le bundle crée les ressources suivantes :

  • Un projet Lakebase avec les paramètres par défaut que vous avez spécifiés.
  • Une branche production protégée.
  • Un point de terminaison principal en lecture/écriture avec haute disponibilité et secondaires en lecture.
  • Pipeline de synchronisation continue qui diffuse une table Delta du catalogue Unity dans la base de données du projet.
  • Catalogue Unity soutenu par la base de données Lakebase, interrogeable en tant que données du catalogue Unity.
  • Une application Databricks connectée à la base de données du projet.
  • Autorisation d’espace de travail CAN_MANAGE pour le principal de service que vous avez spécifié.

Ressources supplémentaires

  • Last updated on