Databricks-Terraform-Anbieter

Artikel
05/04/2024

HashiCorp Terraform ist ein beliebtes Open-Source-Tool zum Erstellen von sicherer und vorhersagbarer Cloudinfrastruktur für mehrere Cloudanbieter. Sie können den Databricks-Terraform-Anbieter nutzen, um Ihre Azure Databricks-Arbeitsbereiche und die zugehörige Cloudinfrastruktur mit einem flexiblen und leistungsstarken Tool zu verwalten. Das Ziel des Databricks-Terraform-Anbieters ist die Unterstützung aller Databricks-REST-APIs, um die Automatisierung der kompliziertesten Aspekte in Bezug auf die Bereitstellung und Verwaltung Ihrer Datenplattformen zu unterstützen. Der Databricks-Terraform-Anbieter wird von Databricks-Kunden genutzt, um Cluster und Aufträge bereitzustellen und zu verwalten und den Datenzugriff zu konfigurieren. Sie verwenden den Azure-Anbieter, um Azure Databricks-Arbeitsbereiche bereitzustellen.

Erste Schritte

In diesem Abschnitt installieren und konfigurieren Sie Anforderungen für die Verwendung von Terraform und des Databricks Terraform-Anbieters auf Ihrem lokalen Computer. Anschließend konfigurieren Sie Terraform-Authentifizierung. Im Anschluss an diesen Abschnitt finden Sie in diesem Artikel eine Beispielkonfiguration, mit der Sie experimentieren können, um in einem vorhandenen Azure Databricks-Arbeitsbereich ein Azure Databricks-Notebook, einen Cluster und einen Auftrag zur Ausführung des Notebooks im Cluster bereitzustellen.

Anforderungen

Sie benötigen die Terraform CLI. Ausführlichere Informationen finden Sie auf der Terraform-Website unter Herunterladen von Terraform.
Sie benötigen ein Terraform-Projekt. Erstellen Sie in Ihrem Terminal ein leeres Verzeichnis, und wechseln Sie dann in dieses Verzeichnis. (Jeder separate Satz von Terraform-Konfigurationsdateien muss sich in einem eigenen Verzeichnis befinden, das als Terraform-Projekt bezeichnet wird.) Beispiel: mkdir terraform_demo && cd terraform_demo.
```
mkdir terraform_demo && cd terraform_demo
```
Sie fügen die Terraform-Konfigurationen für Ihr Projekt in mindestens eine Konfigurationsdatei in Ihrem Terraform-Projekt ein. Weitere Informationen zur Syntax von Konfigurationsdateien finden Sie in der Terraform-Sprachdokumentation auf der Terraform-Website.
Sie müssen Ihrem Terraform-Projekt eine Abhängigkeit für den Databricks Terraform-Anbieter hinzufügen. Fügen Sie einer der Konfigurationsdateien in Ihrem Terraform-Projekt Folgendes hinzu:
```
terraform {
  required_providers {
    databricks = {
      source = "databricks/databricks"
    }
  }
}
```
Sie müssen die Authentifizierung für Ihr Terraform-Projekt konfigurieren. Weitere Informationen finden Sie unter Authentifizierung in der Dokumentation zum Databricks Terraform-Anbieter.

Beispielkonfiguration

In diesem Abschnitt finden Sie eine Beispielkonfiguration, mit der Sie experimentieren können, um in einem vorhandenen Azure Databricks-Arbeitsbereich ein Azure Databricks-Notebook, einen Cluster und einen Auftrag zur Ausführung des Notebooks auf dem Cluster bereitzustellen. Es wird davon ausgegangen, dass Sie bereits die Anforderungen eingerichtet sowie ein Terraform-Projekt erstellt und das Projekt mit Terraform-Authentifizierung konfiguriert haben, wie im vorherigen Abschnitt beschrieben.

Erstellen Sie in Ihrem Terraform-Projekt eine Datei namens me.tf, und fügen Sie darin folgenden Code hinzu. Diese Datei ruft Informationen zum aktuellen Benutzer (Sie) ab:
```
# Retrieve information about the current user.
data "databricks_current_user" "me" {}
```

Erstellen Sie eine weitere Datei namens notebook.tf, und fügen Sie den folgenden Code hinzu. Diese Datei stellt das Notebook dar.

variable "notebook_subdirectory" {
  description = "A name for the subdirectory to store the notebook."
  type        = string
  default     = "Terraform"
}

variable "notebook_filename" {
  description = "The notebook's filename."
  type        = string
}

variable "notebook_language" {
  description = "The language of the notebook."
  type        = string
}

resource "databricks_notebook" "this" {
  path     = "${data.databricks_current_user.me.home}/${var.notebook_subdirectory}/${var.notebook_filename}"
  language = var.notebook_language
  source   = "./${var.notebook_filename}"
}

output "notebook_url" {
 value = databricks_notebook.this.url
}

Erstellen Sie eine weitere Datei namens notebook.auto.tfvars, und fügen Sie den folgenden Code hinzu. Diese Datei gibt die Eigenschaften des Notebooks an.
```
notebook_subdirectory = "Terraform"
notebook_filename     = "notebook-getting-started.py"
notebook_language     = "PYTHON"
```
Erstellen Sie eine weitere Datei namens notebook-getting-started.py, und fügen Sie den folgenden Code hinzu. Diese Datei stellt den Inhalt des Notebooks dar.
```
display(spark.range(10))
```

Erstellen Sie eine weitere Datei namens cluster.tf, und fügen Sie den folgenden Code hinzu. Diese Datei stellt den Cluster dar.

variable "cluster_name" {
  description = "A name for the cluster."
  type        = string
  default     = "My Cluster"
}

variable "cluster_autotermination_minutes" {
  description = "How many minutes before automatically terminating due to inactivity."
  type        = number
  default     = 60
}

variable "cluster_num_workers" {
  description = "The number of workers."
  type        = number
  default     = 1
}

# Create the cluster with the "smallest" amount
# of resources allowed.
data "databricks_node_type" "smallest" {
  local_disk = true
}

# Use the latest Databricks Runtime
# Long Term Support (LTS) version.
data "databricks_spark_version" "latest_lts" {
  long_term_support = true
}

resource "databricks_cluster" "this" {
  cluster_name            = var.cluster_name
  node_type_id            = data.databricks_node_type.smallest.id
  spark_version           = data.databricks_spark_version.latest_lts.id
  autotermination_minutes = var.cluster_autotermination_minutes
  num_workers             = var.cluster_num_workers
}

output "cluster_url" {
 value = databricks_cluster.this.url
}

Erstellen Sie eine weitere Datei namens cluster.auto.tfvars, und fügen Sie den folgenden Code hinzu. Diese Datei gibt die Eigenschaften des Clusters an.
```
cluster_name                    = "My Cluster"
cluster_autotermination_minutes = 60
cluster_num_workers             = 1
```

Erstellen Sie eine weitere Datei namens job.tf, und fügen Sie den folgenden Code hinzu. Diese Datei stellt den Auftrag dar, der das Notebook im Cluster ausführt.

variable "job_name" {
  description = "A name for the job."
  type        = string
  default     = "My Job"
}

variable "task_key" {
  description = "A name for the task."
  type        = string
  default     = "my_task"
}

resource "databricks_job" "this" {
  name = var.job_name
  task {
    task_key = var.task_key
    existing_cluster_id = databricks_cluster.this.cluster_id
    notebook_task {
      notebook_path = databricks_notebook.this.path
    }
  }
  email_notifications {
    on_success = [ data.databricks_current_user.me.user_name ]
    on_failure = [ data.databricks_current_user.me.user_name ]
  }
}

output "job_url" {
  value = databricks_job.this.url
}

Erstellen Sie eine weitere Datei namens job.auto.tfvars, und fügen Sie den folgenden Code hinzu. Diese Datei gibt die Eigenschaften des Auftrags an.
```
job_name = "My Job"
task_key = "my_task"
```
Führen Sie terraform planaus. Wenn Fehler auftreten, beheben Sie diese, und führen Sie den Befehl dann erneut aus.
Führen Sie terraform applyaus.
Überprüfen Sie, ob das Notebook,der Cluster und der Auftrag erstellt wurden: Suchen Sie in der Ausgabe des Befehls terraform apply nach den URLs für notebook_url, cluster_url und job_url, und rufen Sie diese auf.
Führen Sie den Auftrag aus: Klicken Sie auf der Seite Aufträge auf Jetzt ausführen. Überprüfen Sie nach Abschluss des Auftrags Ihren E-Mail-Posteingang.
Wenn Sie mit diesem Beispiel fertig sind, löschen Sie das Notebook, den Cluster und den Auftrag aus dem Azure Databricks-Arbeitsbereich, indem Sie terraform destroy ausführen.

Hinweis

Weitere Informationen zu den Befehlen terraform plan, terraform apply und terraform destroy finden Sie in der Dokumentation zur Terraform CLI in der Terraform-Dokumentation.
Überprüfen Sie, ob das Notebook, der Cluster und der Auftrag gelöscht wurden: Aktualisieren Sie die Seiten für das Notebook, den Cluster und die Aufträge, um jeweils eine Meldung anzuzeigen, dass die Ressourcen nicht gefunden wurden.

Testen

Testen Sie Ihre Terraform-Konfigurationen vor oder nach der Bereitstellung. Sie können Tests analog zu Unittests ausführen, bevor Sie Ressourcen bereitstellen. Sie können Tests auch analog zu Integrationstests ausführen, nachdem Ressourcen bereitgestellt wurden. Siehe Tests in der Terraform-Dokumentation.

Führen Sie Tests analog zu Integrationstests anhand der Beispielkonfiguration in diesem Artikel folgendermaßen aus:

Erstellen Sie eine Datei namens cluster.tftest.hcl, und fügen Sie den folgenden Code hinzu. Diese Datei testet, ob der bereitgestellte Cluster den erwarteten Clusternamen aufweist.

# Filename: cluster.tftest.hcl

run "cluster_name_test" {
  command = apply

  assert {
    condition     = databricks_cluster.this.cluster_name == var.cluster_name
    error_message = "Cluster name did not match expected name"
  }
}

Erstellen Sie eine Datei namens job.tftest.hcl, und fügen Sie den folgenden Code hinzu. Diese Datei testet, ob der bereitgestellte Auftrag den erwarteten Auftragsnamen aufweist.

run "job_name_test" {
  command = apply

  assert {
    condition     = databricks_job.this.name == var.job_name
    error_message = "Job name did not match expected name"
  }
}

Erstellen Sie eine Datei namens notebook.tftest.hcl, und fügen Sie den folgenden Code hinzu. Diese Datei testet, ob das bereitgestellte Notebook den erwarteten Arbeitsbereichspfad aufweist.

run "notebook_path_test" {
  command = apply

  assert {
    condition     = databricks_notebook.this.path == "${data.databricks_current_user.me.home}/${var.notebook_subdirectory}/${var.notebook_filename}"
    error_message = "Notebook path did not match expected path"
  }
}

Führen Sie terraform test aus. Terraform stellt jede Ressource im Azure Databricks-Arbeitsbereich bereit, führt jeden zugehörigen Test aus, meldet die Testergebnisse und löscht dann die bereitgestellte Ressource.

Führen Sie Tests analog zu Unittests anhand der Beispielkonfiguration in diesem Artikel folgendermaßen aus:

Ändern Sie die Zeile command = apply in jedem der vorherigen Tests in command = plan, und führen Sie dann terraform test aus. Terraform führt jeden zugehörigen Test aus und meldet die Testergebnisse, stellt jedoch keine Ressourcen bereit.
Simulieren Sie den Databricks Terraform-Anbieter. Auf diese Weise können Sie terraform test ausführen, ohne Ressourcen bereitzustellen und ohne dass Anmeldeinformationen für die Authentifizierung erforderlich sind. Siehe Simulationen in der Terraform-Dokumentation. Sie können simulierte Tests ausführen, indem Sie Ihren Tests die Zeile mock_provider "databricks" {} hinzufügen und die Zeile command = apply oder command = plan entfernen. Zum Beispiel:

# Filename: cluster.tftest.hcl

mock_provider "databricks" {}

run "cluster_mock_name_test" {
  assert {
    condition     = databricks_cluster.this.cluster_name == var.cluster_name
    error_message = "Cluster name did not match expected name"
  }
}

# Filename: job.tftest.hcl

mock_provider "databricks" {}

run "job_mock_name_test" {
  assert {
    condition     = databricks_job.this.name == var.job_name
    error_message = "Job name did not match expected name"
  }
}

# Filename: notebook.tftest.hcl

mock_provider "databricks" {}

run "notebook_mock_path_test" {
  assert {
    condition     = databricks_notebook.this.path == "${data.databricks_current_user.me.home}/${var.notebook_subdirectory}/${var.notebook_filename}"
    error_message = "Notebook path did not match expected path"
  }
}

Nächste Schritte

Erstellen eines Azure Databricks-Arbeitsbereichs.
Verwalten von Arbeitsbereichsressourcen für einen Azure Databricks-Arbeitsbereich

Problembehandlung

Hinweis

Wenn Sie Terraform-spezifische Unterstützung benötigen, sehen Sie sich die aktuellen Terraform-Themen auf der HashiCorp Discuss-Website an. Informationen zu spezifischen Problemen mit dem Databricks-Terraform-Anbieter finden Sie im GitHub-Repository databrickslabs/terraform-provider-databricks unter Probleme.

Fehler: Fehler beim Installieren des Anbieters

Problem: Wenn Sie keine Datei vom Typ terraform.lock.hcl in Ihr Versionskontrollsystem eingecheckt haben und Sie den Befehl terraform init ausführen, wird die folgende Meldung angezeigt: Failed to install provider. Eine weitere Ausgabe kann eine Meldung wie die folgende enthalten:

Error while installing databrickslabs/databricks: v1.0.0: checksum list has no SHA-256 hash for "https://github.com/databricks/terraform-provider-databricks/releases/download/v1.0.0/terraform-provider-databricks_1.0.0_darwin_amd64.zip"

Ursache: Ihre Terraform-Konfigurationen verweisen auf veraltete Databricks-Terraform-Anbieter.

Lösung:

Ersetzen Sie databrickslabs/databricks durch databricks/databricks in allen Dateien vom Typ .tf.

Um diese Ersetzungen zu automatisieren, führen Sie den folgenden Python-Befehl im übergeordneten Ordner aus, der die zu aktualisierenden Dateien vom Typ .tf enthält:
```
python3 -c "$(curl -Ls https://dbricks.co/updtfns)"
```
Führen Sie den folgenden Terraform-Befehl aus, und genehmigen Sie dann die Änderungen, wenn Sie dazu aufgefordert werden:
```
terraform state replace-provider databrickslabs/databricks databricks/databricks
```
Informationen zu diesem Befehl finden Sie in der Terraform-Dokumentation unter Befehl: state replace-provider.
Überprüfen Sie die Änderung, indem Sie den folgenden Terraform-Befehl ausführen:
```
terraform init
```

Fehler: Fehler beim Abfragen verfügbarer Anbieterpakete

Ursache: Ihre Terraform-Konfigurationen verweisen auf veraltete Databricks-Terraform-Anbieter.

Lösung: Befolgen Sie die Lösungsanweisungen unter Fehler: Fehler beim Installieren des Anbieters.

Aktivieren der Protokollierung

Der Databricks Terraform-Anbieter gibt Protokolle aus, die Sie aktivieren können, indem Sie die TF_LOG Umgebungsvariable auf DEBUG oder eine andere Protokollebene festlegen, die Terraform unterstützt.

Standardmäßig werden Protokolle an stderr gesendet. Um Protokolle an eine Datei zu senden, legen Sie die TF_LOG_PATH Umgebungsvariable auf den Zieldateipfad fest.

Sie können z. B. den folgenden Befehl ausführen, um die Protokollierung auf Debugebene zu aktivieren und Protokolle im monochromen Format in eine Datei auszugeben, die relativ zum aktuellen Arbeitsverzeichnis als tf.log benannt ist, während der terraform apply Befehl ausgeführt wird:

TF_LOG=DEBUG TF_LOG_PATH=tf.log terraform apply -no-color

Weitere Informationen zur Terraform-Protokollierung finden Sie unter Debugging Terraform.

Weitere Beispiele

Zusätzliche Ressourcen

Dokumentation zum Databricks-Anbieter auf der Website für die Terraform-Registrierung
Terraform-Dokumentation auf der Terraform-Website
Das terraform-databricks-examples-Repository in GitHub

Databricks-Terraform-Anbieter

Erste Schritte

Anforderungen

Beispielkonfiguration

Testen

Nächste Schritte

Problembehandlung

Fehler: Fehler beim Installieren des Anbieters

Fehler: Fehler beim Abfragen verfügbarer Anbieterpakete

Aktivieren der Protokollierung

Weitere Beispiele

Zusätzliche Ressourcen

Feedback

Feedback

Zusätzliche Ressourcen