Databricks-Terraform-Anbieter

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, Databricks-Arbeitsbereiche bereitzustellen und den Datenzugriff zu konfigurieren.

Erste Schritte

In diesem Abschnitt installieren und konfigurieren Sie Anforderungen für die Verwendung von Terraform und des Databricks Terraform-Anbieters. 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 auf dem Cluster bereitzustellen.

Anforderungen

Um Terraform zum Erstellen von Ressourcen auf Azure-Kontoebene und den Databricks Terraform-Anbieter zum Erstellen von Ressourcen auf Azure Databricks-Kontoebene zu verwenden, müssen Sie über Folgendes verfügen:

Um den Databricks Terraform-Anbieter auch zum Erstellen von Ressourcen auf Azure Databricks-Arbeitsbereichsebene zu verwenden, müssen Sie über Folgendes verfügen:

  • Einen Azure Databricks-Arbeitsbereich.
  • Auf Ihrem lokalen Entwicklungscomputer muss Folgendes installiert sein:
    • Die Terraform-Befehlszeilenschnittstelle. Ausführlichere Informationen finden Sie auf der Terraform-Website unter Herunterladen von Terraform.
    • Einer der folgenden:
      • Die Databricks-Befehlszeilenschnittstelle (Databricks CLI), konfiguriert mit Ihrer Azure Databricks Workspace-Instanz-URL und entweder Ihrem persönlichen Azure Databricks-Zugriffstoken durch Ausführen von databricks configure --token oder Ihrem Azure Active Directory (Azure AD)-Token durch Festlegen Ihrer DATABRICKS_AAD_TOKEN-Umgebungsvariablen und dann läuft databricks configure --aad-token. Siehe CLI einrichten und Authentifizierung einrichten.

        Hinweis

        Als bewährte Sicherheitsmethode empfiehlt Databricks, bei der Authentifizierung mit automatisierten Tools, Systemen, Skripts und Anwendungen entsprechende Zugriffstoken zu verwenden, die zu Dienstprinzipalen gehören und nicht zu Benutzern des Arbeitsbereichs. Weitere Informationen finden Sie unter Verwalten von Dienstprinzipalen.

      • Die Azure CLI, die sich über den az login Befehl angemeldet hat. Erfahren Sie , wie Sie die Azure CLI installieren und sich mit Azure CLI anmelden.

        Hinweis

        Als bewährte Sicherheitsmethode empfiehlt Databricks bei der Authentifizierung mit automatisierten Tools, Systemen, Skripts und Apps, dass Sie sich über den az login-Befehl mit einem Azure Active Directory (Azure AD)-Dienstprinzipal anmelden. Siehe Dienstprinzipale für die Azure Databricks-Automatisierung, Anmelden mit einem Dienstprinzipal und Authentifizierung mit Azure-Dienstprinzipal.

      • Exportieren Sie die folgenden beiden Umgebungsvariablen:

        Informationen zum Festlegen dieser Umgebungsvariablen finden Sie in der Dokumentation ihres Betriebssystems.

        Hinweis

        Als bewährte Sicherheitsmethode empfiehlt Databricks, bei der Authentifizierung mit automatisierten Tools, Systemen, Skripts und Anwendungen entsprechende Zugriffstoken zu verwenden, die zu Dienstprinzipalen gehören und nicht zu Benutzern des Arbeitsbereichs. Weitere Informationen finden Sie unter Verwalten von Dienstprinzipalen.

Konfigurieren der Terraform-Authentifizierung

In Ihrem Terraform-Projekt müssen Sie eine Konfiguration erstellen, um Terraform mit Ihrem Azure-Konto zu authentifizieren und den Databricks Terraform-Anbieter mit Ihrem Azure Databricks-Konto und Ihrem Azure Databricks-Arbeitsbereich wie folgt zu authentifizieren:

  1. 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
    
  2. Erstellen Sie in diesem leeren Verzeichnis eine Datei namens auth.tf. Fügen Sie je nach Authentifizierungsmethode dieser Datei den folgenden Inhalt hinzu, und speichern Sie die Datei.

    Tipp

    Wenn Sie Visual Studio Code verwenden, fügt die HashiCorp Terraform-Erweiterung für Visual Studio Code Bearbeitungsfeatures für Terraform-Dateien wie Syntaxmarkierung, IntelliSense, Codenavigation, Codeformatierung, einen Modul-Explorer und vieles mehr hinzu.

    Um die Azure CLI zum Authentifizieren auf Azure-Kontoebene und auf Azure Databricks-Kontoebene zu verwenden und ein Databricks CLI-Konfigurationsprofil für Authentifizierung auf Azure Databricks-Arbeitsbereichsebene zu verwenden, fügen Sie den folgenden Inhalt hinzu:

    variable "databricks_connection_profile" {}
    
    terraform {
      required_providers {
        azurerm = {
          source = "hashicorp/azurerm"
        }
        databricks = {
          source = "databricks/databricks"
        }
      }
    }
    
    provider "azurerm" {
      features {}
    }
    
    # Use Databricks CLI authentication.
    provider "databricks" {
      profile = var.databricks_connection_profile
    }
    

    Um die Azure CLI für Authentifizierung auf Azure-Kontoebene, Azure Databricks-Kontoebene und Azure Databricks-Arbeitsbereichsebene zu verwenden, fügen Sie stattdessen die folgenden Inhalte hinzu:

    variable "databricks_host" {}
    
    terraform {
      required_providers {
        azurerm = {
          source = "hashicorp/azurerm"
        }
        databricks = {
          source = "databricks/databricks"
        }
      }
    }
    
    provider "azurerm" {
      features {}
    }
    
    # Use Azure CLI authentication.
    provider "databricks" {
      host = var.databricks_host
    }
    

    Um die Azure CLI zum Authentifizieren auf Azure-Kontoebene sowie auf Azure Databricks-Kontoebene und Umgebungsvariablen für Authentifizierung auf Azure Databricks-Arbeitsbereichsebene zu verwenden, fügen Sie stattdessen den folgenden Inhalt hinzu:

    terraform {
      required_providers {
        azurerm = {
          source = "hashicorp/azurerm"
        }
        databricks = {
          source = "databricks/databricks"
        }
      }
    }
    
    provider "azurerm" {
      features {}
    }
    
    # Use environment variables for authentication.
    provider "databricks" {}
    

    Tipp

    Wenn Sie Ressourcen nur auf Databricks-Arbeitsbereichsebene erstellen möchten, können Sie den azurerm-Block aus einer der vorherigen required_providers-Deklarationen zusammen mit der provider "azurerm"-Deklaration entfernen.

  3. Wenn Sie ein Databricks CLI-Konfigurationsprofil oder die Azure CLI verwenden, um sich auf Azure Databricks-Arbeitsbereichsebene zu authentifizieren, erstellen Sie eine weitere Datei namens auth.auto.tfvars, fügen Sie der Datei den folgenden Inhalt hinzu, und ändern Sie den Wert bei Bedarf.

    Tipp

    *.auto.tfvars-Dateien ermöglichen es Ihnen, variablen Werte separat vom Code anzugeben. Dadurch werden Ihre .tf-Dateien modularer und in verschiedenen Nutzungsszenarien wiederverwendbar.

    Wenn Sie ein Databricks CLI-Konfigurationsprofil zum Authentifizieren auf Azure Databricks-Arbeitsbereichsebene verwenden, fügen Sie den folgenden Inhalt hinzu:

    databricks_connection_profile = "DEFAULT"
    

    Wenn Sie die Azure CLI zum Authentifizieren auf Azure Databricks-Arbeitsbereichsebene verwenden, fügen Sie stattdessen den folgenden Inhalt hinzu:

    databricks_host = "https://<workspace-instance-name>"
    
  4. Initialisieren Sie das Arbeitsverzeichnis, das die Datei auth.tf enthält, indem Sie den Befehl terraform init ausführen. Weitere Informationen finden Sie auf der Terraform-Website unter Befehl: init.

    terraform init
    

    Terraform lädt die angegebenen Anbieter herunter und installiert sie in einem ausgeblendeten Unterverzeichnis namens .terraform Ihres aktuellen Arbeitsverzeichnisses. Mit dem Befehl terraform init wird ausgegeben, welche Version des Anbieters installiert wurde. Terraform erstellt außerdem eine Sperrdatei mit dem Namen .terraform.lock.hcl, die die genauen verwendeten Anbieterversionen angibt, sodass Sie steuern können, wann Sie die für Ihr Projekt verwendeten Anbieter aktualisieren möchten.

  5. Überprüfen Sie, ob Ihr Projekt ordnungsgemäß konfiguriert wurde, indem Sie den Befehl terraform plan ausführen. Wenn Fehler gemeldet werden, beheben Sie diese, und führen Sie den Befehl dann erneut aus. Weitere Informationen finden Sie auf der Terraform-Website unter Befehl: plan.

    terraform plan
    
  6. Wenden Sie durch Ausführen des Befehls terraform apply die erforderlichen Änderungen an, um den gewünschten Zustand der Konfiguration zu erreichen. Weitere Informationen finden Sie auf der Terraform-Website unter Befehl: apply.

    terraform apply
    

    Da in der Datei auth.tf noch keine Ressourcen angegeben wurden, lautet die Ausgabe Apply complete! Resources: 0 added, 0 changed, 0 destroyed.. Darüber hinaus schreibt Terraform Daten in eine Datei mit dem Namen terraform.tfstate. Fahren Sie zum Erstellen von Ressourcen mit dem Abschnitt Beispielkonfiguration oder Nächste Schritte oder mit beiden Abschnitten fort, um die Ressourcen anzugeben, die erstellt werden sollen. Führen Sie anschließend erneut den Befehl terraform apply aus. Terraform speichert die IDs und Eigenschaften der verwalteten Ressourcen in dieser Datei terraform.tfstate, damit diese Ressourcen in Zukunft aktualisiert oder zerstört werden können.

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.

  1. Erstellen Sie eine weitere Datei mit dem Namen me.tf im selben Verzeichnis, das Sie im Schritt Konfigurieren der Terraform-Authentifizierung erstellt haben, und fügen Sie den folgenden Code hinzu. Diese Datei ruft Informationen zum aktuellen Benutzer (Sie) ab:

    # Retrieve information about the current user.
    data "databricks_current_user" "me" {}
    
  2. 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
    }
    
  3. 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"
    
  4. 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))
    
  5. 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
    }
    
  6. 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
    
  7. 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"
    }
    
    resource "databricks_job" "this" {
      name = var.job_name
      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
    }
    
  8. 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"
    
  9. Führen Sie terraform plan aus. Wenn Fehler auftreten, beheben Sie diese, und führen Sie den Befehl dann erneut aus.

  10. Führen Sie terraform apply aus.

  11. Ü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.

  12. 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.

  13. 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.

  14. Ü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.

Nächste Schritte

  1. Erstellen eines Azure Databricks-Arbeitsbereichs.
  2. 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:

  1. 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)"
    
  2. 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.

  3. Überprüfen Sie die Änderung, indem Sie den folgenden Terraform-Befehl ausführen:

    terraform init
    

Fehler: Fehler beim Abfragen verfügbarer Anbieterpakete

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 query available provider packages.

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

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

Weitere Beispiele

Zusätzliche Ressourcen