Aller au contenu principal
Dernière mise à jour le

Démarrer avec Terraform pour Lakebase

Ce guide vous aide à démarrer avec Terraform pour gérer les Ressources Lakebase à l'aide du fournisseur Databricks Terraform. Vous allez créer un projet, ajouter une Branch de développement et un Endpoint, puis les supprimer une fois terminé. Il s'agit d'un workflow typique pour la gestion des environnements de développement et de test.

astuce

Ce guide couvre un sous-ensemble des commandes Terraform disponibles. Pour la référence complète des ressources et toutes les options de configuration disponibles, consultez la documentation du fournisseur Databricks sur le Registre Terraform.

Prérequis​

Avant de commencer, vous avez besoin de :

Sémantique Terraform du dimensionnement automatique de Lakebase​

Les ressources d'autoscaling de Lakebase utilisent la sémantique Terraform avec des champs spec/status pour la gestion déclarative de l'état. Le champ spec définit l'état souhaité, tandis que le champ status indique l'état actuel.

info

Important : Détection de drift et modifications en dehors de Terraform

Les modifications apportées aux ressources Lakebase en dehors de Terraform (à l'aide de l'interface utilisateur, de la CLI ou de l'API) ne sont pas détectées par la détection standard de drift de Terraform.

Pour des détails complets sur le fonctionnement des champs spec/status, le comportement de détection de drift et les exigences de gestion de l'état, consultez la documentation de la ressource databricks_postgres_project.

Hiérarchie des ressources​

Les ressources Lakebase suivent une hiérarchie parent-enfant : vous créez les ressources parentes avant les enfants, et supprimez les enfants avant les parents. Pour le modèle de ressources complet (projets, branches, computes, bases de données, et plus), consultez les Projets.

Ordre des opérations pour ce guide : Projet → Branch → Endpoint

Démarrage rapide : Gérer un projet Lakebase avec Terraform​

Suivez ces étapes pour créer un projet complet et fonctionnel avec une branch de développement et un endpoint compute :

1. Configurer l'authentification​

Configurez le fournisseur Databricks pour authentifier l'utilisation du Service Principal que vous avez configuré dans les prérequis. Les ressources Lakebase nécessitent une authentification OAuth, vous définissez donc des variables d'environnement pour les informations d'identification OAuth de votre Service Principal :

Bash
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_CLIENT_ID="your-service-principal-client-id"
export DATABRICKS_CLIENT_SECRET="your-service-principal-secret"

Ensuite, configurez votre fournisseur pour utiliser ces variables d'environnement :

Terraform
terraform {
  required_version = ">= 1.0"

  required_providers {
    databricks = {
      source  = "databricks/databricks"
      version = "~> 1.0"
    }
  }
}

provider "databricks" {
  # Automatically uses DATABRICKS_HOST, DATABRICKS_CLIENT_ID,
  # and DATABRICKS_CLIENT_SECRET from environment variables
}

Pour plus d’options d’authentification et de détails sur la configuration OAuth, consultez Autoriser l’accès Service Principal à Databricks avec OAuth et fournisseur Databricks Terraform.

2. Créer un projet​

Un projet est la ressource de niveau supérieur qui contient des Branch, des Endpoint, des bases de données et des rôles.

remarque

Lorsque vous créez un projet, Databricks provisionne automatiquement une Branch par default nommée production avec un endpoint de compute en lecture-ecriture nommé primary. Pour configurer l'une ou l'autre Ressource (par exemple, pour activer la haute disponibilité sur l'endpoint), déclarez un databricks_postgres_branch ou databricks_postgres_endpoint correspondant avec replace_existing = true. Terraform prend possession de la Ressource existante en faisant correspondre ces ID connus.

Créer un projet de base :

Hcl
resource "databricks_postgres_project" "app" {
  project_id = "my-app"
  spec = {
    pg_version             = 17
    display_name           = "My Application"
    enable_pg_native_login = false
  }
}

Exécutez ces commandes pour mettre en forme votre configuration et créer le projet :

Bash
terraform fmt
terraform apply

enable_pg_native_login = false est le default pour les nouveaux projets. Pour autoriser les rôles Postgres natifs à se connecter avec des mots de passe statiques, définissez-le sur true. Consultez Gérer les connexions de mot de passe.

attention

By default, la suppression d’un databricks_postgres_project de votre configuration et l’exécution de terraform apply supprime logiquement le projet. Il est conservé pendant 7 jours. Pour supprimer définitivement le projet immédiatement, ajoutez purge_on_delete = true au bloc de ressources avant de le supprimer. Consultez Étape 9 : Supprimer un projet pour plus de détails.

3. Obtenir un projet​

Obtenez des informations sur le projet que vous venez de créer à partir d'une source de données :

Hcl
data "databricks_postgres_project" "this" {
  name = databricks_postgres_project.app.name
}

output "project_name" {
  value = data.databricks_postgres_project.this.name
}

output "project_pg_version" {
  value = try(data.databricks_postgres_project.this.status.pg_version, null)
}

output "project_display_name" {
  value = try(data.databricks_postgres_project.this.status.display_name, null)
}
astuce

Les sources de données renvoient des valeurs dans le champ status. Utilisez try() pour accéder en toute sécurité aux champs qui pourraient ne pas être disponibles dans toutes les versions du fournisseur.

Exécutez ces commandes pour appliquer la configuration et afficher les détails du projet :

Bash
terraform apply
terraform output

4. Créer une Branch​

Les branches offrent des environnements de base de données isolés au sein d'un projet.

remarque

Une branch production default est créée automatiquement lorsque vous créez un projet, et inclut un Endpoint implicite en lecture-écriture nommé primary. Lorsque vous créez des Branch supplémentaires comme la Branch de développement ci-dessous, chaque nouvelle Branch obtient également son propre Endpoint de lecture-écriture primary implicite. L’étape 5 montre comment soumettre cet Endpoint à la gestion Terraform.

Dans cet exemple, vous créez une Branch de développement :

Hcl
resource "databricks_postgres_branch" "dev" {
  branch_id = "dev"
  parent    = databricks_postgres_project.app.name
  spec = {
    no_expiry = true
  }
}

output "dev_branch_name" {
  value = databricks_postgres_branch.dev.name
}

Exécutez ces commandes pour créer la Branch et afficher son nom :

Bash
terraform apply
terraform output dev_branch_name

5e. Créer un Endpoint​

Les Endpoints fournissent des ressources de compute pour l'exécution des requêtes sur une Branch.

remarque

Chaque branch que vous créez inclut un endpoint en lecture-écriture créé implicitement et nommé primary. Pour le placer sous la gestion Terraform et lui appliquer votre propre configuration, déclarez une ressource databricks_postgres_endpoint avec endpoint_id = "primary" et définissez replace_existing = true. Cela indique à Terraform de prendre en charge l'endpoint existant au lieu d'essayer d'en créer un nouveau. Sans replace_existing, l'application échoue avec une erreur d'opérations conflictuelles.

Prenez possession de l'Endpoint principal de la Branch de développement et appliquez-y votre configuration :

Hcl
resource "databricks_postgres_endpoint" "dev_primary" {
  endpoint_id = "primary"
  parent      = databricks_postgres_branch.dev.name
  spec = {
    endpoint_type = "ENDPOINT_TYPE_READ_WRITE"
  }
  replace_existing = true
}

output "dev_endpoint_name" {
  value = databricks_postgres_endpoint.dev_primary.name
}

Exécutez ces commandes pour appliquer la configuration et afficher le nom de l’endpoint :

Bash
terraform apply
terraform output dev_endpoint_name

Pour les autres modèles d'endpoint, y compris les réplicas en lecture seule et l'autoscaling personnalisé, consultez la référence databricks_postgres_endpoint.

6. Lister les Endpoint​

Listez les Endpoint de votre Branch de développement pour afficher les détails de l'Endpoint en lecture-écriture que vous avez créé :

Hcl
data "databricks_postgres_endpoints" "dev" {
  parent = databricks_postgres_branch.dev.name
}

output "dev_endpoint_names" {
  value = [for e in data.databricks_postgres_endpoints.dev.endpoints : e.name]
}

output "dev_endpoint_types" {
  value = [
    for e in data.databricks_postgres_endpoints.dev.endpoints :
    try(e.status.endpoint_type, null)
  ]
}

Exécutez ces commandes pour appliquer la configuration et afficher les détails du endpoint :

Bash
terraform apply
terraform output dev_endpoint_names
terraform output dev_endpoint_types
astuce

Lorsque vous exécutez terraform apply et que seules les sorties changent (sans modification de l'infrastructure), Terraform affiche « Modifications des sorties » et met à jour l'état sans modifier les Ressources.

7. Lister les Branch​

Lister toutes les Branch de votre projet. Ceci renvoie deux Branch : la Branch de production qui a été créée automatiquement avec votre projet, et la Branch de développement que vous avez créée à l’étape précédente :

Hcl
data "databricks_postgres_branches" "all" {
  parent = databricks_postgres_project.app.name
}

output "branch_names" {
  value = [for b in data.databricks_postgres_branches.all.branches : b.name]
}

Exécutez ces commandes pour appliquer la configuration et afficher les noms de Branch :

Bash
terraform apply
terraform output branch_names

8. Supprimer une Branch​

Supprimez maintenant la Branch de développement que vous avez créée précédemment. Il s'agit d'un workflow typique : créer une Branch pour le développement ou les tests, et la supprimer lorsque vous avez terminé.

Vous supprimez les ressources en supprimant leurs déclarations de votre configuration et en exécutant terraform apply. Terraform prévoit de détruire les ressources qui ne sont plus déclarées.

Supprimer les éléments suivants de vos fichiers de configuration :

  • La ressource databricks_postgres_branch.dev et ses sorties.
  • La ressource databricks_postgres_endpoint.dev_primary et ses sorties.
  • Toute source de données qui référence la branch supprimée. Par exemple, le bloc data "databricks_postgres_endpoints" "dev" de l'étape 6 (et ses sorties dev_endpoint_names et dev_endpoint_types), car son parent = databricks_postgres_branch.dev.name échoue une fois que la Branch a disparu.

Appliquez ensuite la modification :

Bash
terraform apply

Examinez le plan de destruction avant de confirmer.

remarque

Terraform détruit l'Endpoint avant la Branch par lui-même. L'Endpoint de parent = databricks_postgres_branch.dev.name crée une dépendance, ce qui permet à Terraform d'organiser les Opérations correctement sans configuration supplémentaire.

9. Supprimer un projet​

Lorsque vous supprimez un databricks_postgres_project de votre configuration et exécutez terraform apply, Terraform supprime le projet par default. Le projet est conservé pendant 7 jours, période durant laquelle vous pouvez le récupérer, après quoi Lakebase le supprime définitivement.

Pour supprimer le projet et toutes les Ressources enfants, supprimez-les de votre configuration et exécutez :

Bash
terraform apply

Terraform utilise le graphe de dépendance pour détruire les ressources dans le bon ordre. Examinez le plan de destruction avant de confirmer.

Pour supprimer définitivement le projet immédiatement, définissez purge_on_delete = true sur la ressource avant de la supprimer de votre configuration :

Hcl
resource "databricks_postgres_project" "app" {
  project_id      = "my-app"
  purge_on_delete = true  # Permanently delete on apply. Omit to soft-delete (7-day retention).
  spec = {
    pg_version   = 17
    display_name = "My Application"
  }
}

Exécutez terraform apply pour passer le flag à l'état, puis supprimez la ressource de votre configuration et exécutez terraform apply à nouveau.

remarque

La création d'un nouveau projet avec le même project_id qu'un projet supprimé logiquement pendant la période de rétention de 7 jours échoue. Pour réutiliser le même ID de projet, récupérez d'abord le projet existant, forcez une suppression définitive avec purge_on_delete = true ou attendez l'expiration de la période de rétention.

Pour récupérer un projet supprimé de manière réversible avant l'expiration de la période de rétention de 7 jours, utilisez la CLI ou l'API.

astuce

Pour éviter la suppression accidentelle d'un projet de production, ajoutez un bloc lifecycle :

Hcl
resource "databricks_postgres_project" "app" {
  project_id = "my-app"
  spec       = { ... }

  lifecycle {
    prevent_destroy = true
  }
}

Cela provoque l'échec de terraform apply avec une erreur au lieu de supprimer le projet. Supprimez prevent_destroy = true si vous souhaitez intentionnellement détruire la ressource.

Sérialiser les ressources paires avec depends_on​

Lakebase ne traite qu'une seule opération de rôle, de base de données ou d'Endpoint à la fois au sein d'une seule Branch. Si vous déclarez deux ressources sœurs de ces types dans la même branch, et que Terraform n'a pas déjà un bord de dépendance entre elles (par exemple, une base de données référençant un rôle via spec.role), Terraform essaie de les créer en parallèle et l'une échoue avec une erreur d'opérations conflictuelles.

La correction consiste à ajouter un depends_on explicite afin que Terraform sérialise l'application :

Hcl
resource "databricks_postgres_role" "schema_owner" {
  role_id = "schemamigrator"
  parent  = databricks_postgres_branch.main.name
  spec = {
    postgres_role    = "schemamigrator"
    membership_roles = ["DATABRICKS_SUPERUSER"]
  }
}

resource "databricks_postgres_role" "application" {
  role_id = "application"
  parent  = databricks_postgres_branch.main.name
  spec = {
    postgres_role = "application"
  }

  depends_on = [databricks_postgres_role.schema_owner]
}

Ressources supplémentaires​

Sur cette page