Erste Schritte mit Terraform für Lakebase

Dieser Leitfaden hilft Ihnen bei den ersten Schritten mit Terraform, um Lakebase-Ressourcen mithilfe des Azure Databricks Terraform-Anbieters zu verwalten. Sie erstellen ein Projekt, fügen einen Entwicklungszweig und einen Endpunkt hinzu, und löschen sie dann, wenn sie fertig sind. Dies ist ein typischer Workflow für die Verwaltung von Entwicklungs- und Testumgebungen.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie Folgendes:

• Terraform installiert (Version 1.0 oder höher). Weitere Informationen finden Sie unter Installieren von Terraform.
• Ein Dienstprinzipal, der für die OAuth-Computer-zu-Computer-Authentifizierung (M2M) mit CAN MANAGE-Berechtigung für das Lakebase-Projekt konfiguriert ist. Dieses Handbuch erfordert CAN MANAGE (CAN USE ist nicht ausreichend, da das Erstellen oder Aktualisieren von Ressourcen nicht zulässig ist). Siehe Autorisieren des Dienstprinzipalzugriffs auf Azure Databricks mit OAuth und Verwalten von Projektberechtigungen.

Lakebase Autoscaling Terraform-Semantik

Lakebase Autoscaling-Ressourcen verwenden Terraform-Semantik mit Spezifikations-/Statusfeldern für die deklarative Zustandsverwaltung. Das spec Feld definiert den gewünschten Zustand, während das status Feld den aktuellen Zustand anzeigt.

Ressourcenhierarchie

Lakebase-Ressourcen folgen der Hierarchie übergeordneter und untergeordneter Ressourcen: Sie erstellen übergeordnete Ressourcen vor untergeordneten Ressourcen und löschen untergeordnete Ressourcen vor den übergeordneten. Das vollständige Ressourcenmodell (Projekte, Verzweigungen, Berechnungen, Datenbanken und vieles mehr) finden Sie unter " Organisieren von Projekten".

Reihenfolge der Vorgänge für diesen Leitfaden: Project → Branch → Endpoint

Schnellstart: Verwalten eines Lakebase-Projekts mit Terraform

Führen Sie die folgenden Schritte aus, um ein vollständiges Arbeitsprojekt mit einem Entwicklungszweig und einem Computeendpunkt zu erstellen:

1. Einrichten der Authentifizierung

Konfigurieren Sie den Azure Databricks-Anbieter für die Authentifizierung mithilfe des Dienstprinzipals, den Sie in den Voraussetzungen konfiguriert haben. Lakebase-Ressourcen erfordern die OAuth-Authentifizierung, sodass Sie Umgebungsvariablen für die OAuth-Anmeldeinformationen Ihres Dienstprinzipals festlegen:

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"

Konfigurieren Sie dann Ihren Anbieter für die Verwendung dieser Umgebungsvariablen:

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
}

Weitere Authentifizierungsoptionen und Details zur OAuth-Konfiguration finden Sie unter Autorisieren des Dienstprinzipalzugriffs auf Azure Databricks mit OAuth und Databricks Terraform-Anbieter.

2. Erstellen eines Projekts

Ein Projekt ist die Ressource auf oberster Ebene, die Verzweigungen, Endpunkte, Datenbanken und Rollen enthält.

Erstellen eines einfachen Projekts:

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

Führen Sie die folgenden Befehle aus, um Ihre Konfiguration zu formatieren und das Projekt zu erstellen:

terraform fmt
terraform apply

3. Abrufen eines Projekts

Rufen Sie Informationen zum soeben erstellten Projekt mithilfe einer Datenquelle ab:

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)
}

Führen Sie die folgenden Befehle aus, um die Konfiguration anzuwenden und die Projektdetails anzuzeigen:

terraform apply
terraform output

4. Einen Branch erstellen

Verzweigungen stellen isolierte Datenbankumgebungen innerhalb eines Projekts bereit.

In diesem Beispiel erstellen Sie einen Entwicklungszweig:

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
}

Führen Sie die folgenden Befehle aus, um den Branch zu erstellen und seinen Namen anzuzeigen:

terraform apply
terraform output dev_branch_name

5. Erstellen eines Endpunkts

Endpunkte stellen Computerressourcen für die Ausführung von Abfragen auf einen Zweig bereit.

Übernehmen Sie den Besitz des primären Endpunkts der Dev Branch, und wenden Sie Ihre Konfiguration darauf an:

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
}

Führen Sie die folgenden Befehle aus, um die Konfiguration anzuwenden und den Endpunktnamen anzuzeigen:

terraform apply
terraform output dev_endpoint_name

Weitere Endpunktmuster, einschließlich schreibgeschützter Replikate und benutzerdefinierter Autoskalierung, finden Sie in den databricks_postgres_endpoint Referenzen.

6. Endpunkte auflisten

List die Endpunkte in Ihrem Entwicklungszweig auf, um Details zu dem von Ihnen erstellten Lese-/Schreib-Endpunkt anzuzeigen.

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)
  ]
}

Führen Sie diese Befehle aus, um die Konfiguration anzuwenden und die Endpunktdetails anzuzeigen:

terraform apply
terraform output dev_endpoint_names
terraform output dev_endpoint_types

7. Branches auflisten

Listet alle Verzweigungen in Ihrem Projekt auf. Dies gibt zwei Verzweigungen zurück: den Produktionszweig, der automatisch mit Ihrem Projekt erstellt wurde, und den Entwicklungszweig, den Sie in einem früheren Schritt erstellt haben.

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]
}

Führen Sie die folgenden Befehle aus, um die Konfiguration anzuwenden und die Verzweigungsnamen anzuzeigen:

terraform apply
terraform output branch_names

8. Löschen einer Verzweigung

Löschen Sie nun den Entwicklungszweig, den Sie zuvor erstellt haben. Dies ist ein typischer Workflow: Erstellen Sie eine Verzweigung für Entwicklung oder Tests, und löschen Sie ihn, wenn Sie fertig sind.

Wenn Sie eine Verzweigung löschen, zerstören Sie alle zugehörigen Endpunkte, und zerstören Sie dann die Verzweigung.

8.1 Zerstören des Endpunkts

Zerstören Sie den Endpunkt für den Entwicklungszweig:

terraform destroy -target=databricks_postgres_endpoint.dev_primary

8.2 Zerstört den Zweig

Zerstören Sie den Entwicklungszweig:

terraform destroy -target=databricks_postgres_branch.dev

8.3 Aus Konfiguration entfernen

Entfernen oder kommentieren Sie nach dem gezielten Zerstören die Ressourcenblöcke aus Ihren Konfigurationsdateien, um zu verhindern, dass Terraform sie neu erstellt:

• Entfernen Sie databricks_postgres_branch.dev und die entsprechenden Ausgaben
• Entfernen Sie databricks_postgres_endpoint.dev_primary und die entsprechenden Ausgaben
• Aktualisieren sie alle Datenquellen, die auf die gelöschte Verzweigung verweisen (z. B. list_endpoints.tf)

Gleichen Sie dann den Status ab:

terraform apply

Serialisieren von gleichgeordneten Ressourcen mit depends_on

Lakebase verarbeitet jeweils nur eine Rolle, Datenbank oder Endpunkt-Operation innerhalb einer einzelnen Zweigstelle. Wenn Sie zwei gleichrangige Ressourcen dieser Art in derselben Verzweigung deklarieren und Terraform noch keine Abhängigkeitskante dazwischen hat (z. B. eine Datenbank, die auf eine Rolle spec.role verweist), versucht Terraform, sie parallel zu erstellen, und es tritt ein Fehler aufgrund von Konflikten bei Vorgängen auf.

Der Fix besteht darin, eine explizite depends_on Hinzuzufügen, sodass Terraform die Anwendung serialisiert:

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]
}

Nächste Schritte

• databricks_postgres_project auf der Terraform Registry. Einstiegspunkt für Lakebase-Ressourcen. Die Registrierungs-Randleistenlinks von hier zu postgres_branch, , postgres_endpoint, postgres_roleund postgres_database.
• Azure Databricks Terraform-Anbieter
• Verwalten von Lakebase-Projekten
• Lernprogramm für zweigbasierte Entwicklung