Terraform CDK Databricks-Anbieter

Hinweis

Dieser Artikel behandelt das Cloud Development Kit für Terraform (CDKTF), das von Databricks weder bereitgestellt noch unterstützt wird. Informationen zum Kontaktieren des Anbieters finden Sie in der Terraform-Community.

In diesem Artikel erfahren Sie, wie Sie Python zusammen mit dem Terraform CDK Databricks Provider und dem Cloud Development Kit for Terraform (CDKTF) verwenden. Das CDKTF ist eine IaC-Plattform (Infrastructure-as-Code) eines Drittanbieters, mit der Sie Azure Databricks-Ressourcen mithilfe von vertrauten Programmiersprachen, Tools und technischen Verfahren erstellen, bereitstellen und verwalten können. Obwohl dieser Artikel die Verwendung von Python zeigt, unterstützt das CDKTF zusätzliche Sprachen wie TypeScript, Java, C# und Go.

Der Terraform CDK Databricks-Anbieter basiert auf dem Databricks Terraform-Anbieter. Weitere Informationen finden Sie unter Terraform Cloud. Das CDKTF basiert auf dem AWS Cloud Development Kit (AWS CDK).

Anforderungen

Sie müssen über einen Azure Databricks-Arbeitsbereich verfügen, da in diesem Artikel Ressourcen in einen vorhandenen Arbeitsbereich bereitgestellt werden.

Auf Ihrem lokalen Entwicklungscomputer muss Folgendes installiert sein:

• Terraform, Version 1.1 oder höher. Um zu überprüfen, ob Terraform installiert ist, und um die installierte Version zu überprüfen, führen Sie den Befehl terraform -v über Ihr Terminal oder mit PowerShell aus. Installieren Sie Terraform, wenn Sie es nicht bereits installiert haben.

  terraform -v
  

• Node.js, Version 16.13 oder höher, und npm. Führen Sie die Befehle node -v und npm -v aus, um zu überprüfen, ob Sie Node.js und npm installiert haben, und um die installierten Versionen zu überprüfen. Die neuesten Versionen von Node.js enthalten bereits npm. Installieren Sie Node.js und npm mithilfe des Node Version Manager (nvm), wenn Sie Node.js und npm nicht bereits installiert haben.

  node -v
  npm -v
  

• Die CDKTF CLI. Führen Sie den Befehl cdktf --version aus, um zu überprüfen, ob Sie die CDKTF CLI installiert haben, und um die installierte Version zu überprüfen. Installieren Sie die CDKTF CLI mithilfe von npm, wenn Sie sie nicht bereits installiert haben.

  cdktf --version
  

  Tipp

  Sie können die CDKTF CLI auch unter macOS mit Homebrew installieren. Siehe Installieren von CDKTF.

• Python Version 3.7 oder höher und pipenv Version 2021.5.29 oder höher. Führen Sie die Befehle python --version und pipenv --version aus, um zu überprüfen, ob Sie Python und pipenv installiert haben, und um die installierten Versionen zu überprüfen. Installieren Sie Python, und installieren Sie pipenv, wenn sie noch nicht installiert sind.

  python --version
  pipenv --version
  

• Databricks-Authentifizierung, die für den unterstützten Authentifizierungstyp konfiguriert ist, den Sie verwenden möchten. Weitere Informationen finden Sie unter Authentifizierung in der Dokumentation zum Databricks Terraform-Anbieter.

Schritt 1: Erstellen eines CDKTF-Projekts

In diesem Schritt richten Sie auf Ihrem lokalen Entwicklungs-Computer die erforderliche Verzeichnisstruktur für ein CDKTF-Projekt ein. Innerhalb dieser Verzeichnisstruktur erstellen Sie dann Ihr CDKTF-Projekt.

1. Erstellen Sie ein leeres Verzeichnis für Ihr CDKTF-Projekt und wechseln Sie dann in dieses Verzeichnis. Führen Sie die folgenden Befehle in Ihrem Terminal oder mit PowerShell aus:

   Unix, Linux und macOS

   mkdir cdktf-demo
   cd cdktf-demo
   

   Windows

   md cdktf-demo
   cd cdktf-demo
   

2. Erstellen Sie ein CDKTF-Projekt, indem Sie den folgenden Befehl ausführen:

   cdktf init --template=python --local
   

3. Wenn Sie zur Eingabe eines Projektnamens aufgefordert werden, akzeptieren Sie den Standardprojektnamen cdktf-demo, indem Sie die Eingabetaste drücken.

4. Wenn Sie zur Eingabe einer Projektbeschreibung aufgefordert werden, akzeptieren Sie die Standardprojektbeschreibung, indem Sie die Eingabetaste drücken.

5. Wenn die Eingabeaufforderung Möchten Sie ausgehend von einem bestehenden Terraform-Projekt beginnen? angezeigt wird, geben Sie N ein und drücken Sie die Eingabetaste.

6. Wenn die Eingabeaufforderung Möchten Sie Absturzberichte an das CDKTF-Team senden? angezeigt wird, geben Sie n ein und drücken Sie die Eingabetaste.

Das CDKTF erstellt die folgenden Dateien und Unterverzeichnisse in Ihrem cdktf-demo-Verzeichnis:

• .gitignore, die eine Liste von Dateien und Verzeichnissen darstellt, die von Git ignoriert werden, wenn Sie dieses Projekt in ein Git-Remoterepository verschieben möchten.
• cdktf.json, das Konfigurationseinstellungen für Ihr CDKTF-Projekt enthält. Weitere Informationen zu Konfigurationseinstellungen finden Sie in der Konfigurationsdatei.
• help, das Informationen zu einigen der nächsten Schritte enthält , die Sie ausführen können, um mit Ihrem CDKTF-Projekt zu arbeiten.
• main-test.py, das unterstützende Komponententests enthält, die Sie für Ihr CDKTF-Projekt schreiben können. Weitere Informationen zu Komponententests finden Sie unter Komponententests.
• main.py, das den Python-Code enthält, den Sie für Ihr CDKTF-Projekt schreiben.
• Pipfile und Pipfile.lock, die Codeabhängigkeiten für Ihr CDKTF-Projekt verwalten.

Schritt 2: Definieren von Ressourcen

In diesem Schritt verwenden Sie den Terraform CDK Databricks-Anbieter, um ein Notebook und einen Auftrag zur Ausführung dieses Notebooks zu definieren.

1. Installieren Sie die Projektabhängigkeiten: mit pipenv, installieren Sie sie in den Terraform CDK Databricks-Anbieter in Ihrem CDKTF-Projekt, um Azure Databricks-Ressourcen zu generieren. Führen Sie zu diesem Zweck Folgendes aus:

   pipenv install cdktf-cdktf-provider-databricks
   

2. Ersetzen Sie den Inhalt der main.py-Datei durch den folgenden Code. Dieser Code authentifiziert das CDKTF mit Ihrem Azure Databricks-Arbeitsbereich und generiert dann ein Notebook zusammen mit einem Auftrag zum Ausführen des Notebooks. Informationen zum Anzeigen der Syntaxdokumentation für diesen Code finden Sie in der Terraform CDK Databricks-Anbieter-Konstruktreferenz für Python.

   #!/usr/bin/env python
   from constructs import Construct
   from cdktf import (
     App, TerraformStack, TerraformOutput
   )
   from cdktf_cdktf_provider_databricks import (
     data_databricks_current_user,
     job, notebook, provider
   )
   import vars
   from base64 import b64encode
   
   class MyStack(TerraformStack):
     def __init__(self, scope: Construct, ns: str):
       super().__init__(scope, ns)
   
       provider.DatabricksProvider(
         scope = self,
         id    = "databricksAuth"
       )
   
       current_user = data_databricks_current_user.DataDatabricksCurrentUser(
         scope     = self,
         id_       = "currentUser"
       )
   
       # Define the notebook.
       my_notebook = notebook.Notebook(
         scope          = self,
         id_            = "notebook",
         path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
         language       = "PYTHON",
         content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
       )
   
       # Define the job to run the notebook.
       my_job = job.Job(
         scope = self,
         id_ = "job",
         name = f"{vars.resource_prefix}-job",
         task = [ 
           job.JobTask(
             task_key = f"{vars.resource_prefix}-task",
             new_cluster = job.JobTaskNewCluster(
               num_workers   = vars.num_workers,
               spark_version = vars.spark_version,
               node_type_id  = vars.node_type_id
             ),
             notebook_task = job.JobTaskNotebookTask(
               notebook_path = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py"
             ),
             email_notifications = job.JobTaskEmailNotifications(
               on_success = [ current_user.user_name ],
               on_failure = [ current_user.user_name ]
             )
           )
         ]
       )
   
       # Output the notebook and job URLs.
       TerraformOutput(
         scope = self,
         id    = "Notebook URL",
         value = my_notebook.url
       )
   
       TerraformOutput(
         scope = self,
         id    = "Job URL",
         value = my_job.url
       )
   
   app = App()
   MyStack(app, "cdktf-demo")
   app.synth()
   

3. Erstellen Sie im selben Verzeichnis wie main.py eine Datei namens vars.py. Ersetzen Sie die folgenden Werte durch eigene Werte, um ein Ressourcenpräfix und Clustereinstellungen wie die Anzahl der Worker, die Spark-Laufzeitversionszeichenfolge und den Knotentyp anzugeben.

   #!/usr/bin/env python
   resource_prefix = "cdktf-demo"
   num_workers     = 1
   spark_version   = "14.3.x-scala2.12"
   node_type_id    = "Standard_D3_v2"
   

Schritt 3: Bereitstellen der Ressourcen

In diesem Schritt verwenden Sie die CDKTF CLI, um das definierte Notebook und den Auftrag zum Ausführen dieses Notebooks in Ihrem vorhandenen Azure Databricks-Arbeitsbereich bereitzustellen.

1. Generieren Sie das Terraform-Codeäquivalent für Ihr CDKTF-Projekt. Führen Sie dazu den Befehl cdktf synth aus.

   cdktf synth
   

2. Bevor Sie Änderungen vornehmen, können Sie die ausstehenden Ressourcenänderungen überprüfen. Führen Sie Folgendes aus:

   cdktf diff
   

3. Stellen Sie das Notebook und den Auftrag bereit, indem Sie den Befehl cdktf deploy ausführen.

   cdktf deploy
   

4. Wenn Sie zum Genehmigen aufgefordert werden, drücken Sie die Eingabetaste. Terraform erstellt das Notebook und den Auftrag und stellt diese in Ihrem Arbeitsbereich bereit.

Schritt 4: Interagieren mit den Ressourcen

In diesem Schritt führen Sie den Auftrag in Ihrem Azure Databricks-Arbeitsbereich aus, der das angegebene Notebook ausführt.

1. Um das Notebook anzuzeigen, das der Auftrag in Ihrem Arbeitsbereich ausführen wird, kopieren Sie den in der Ausgabe des Befehls cdk deploy angezeigten Notebook URL-Link und fügen ihn in die Adressleiste Ihres Webbrowsers ein.
2. Um den Auftrag anzuzeigen, der das Notebook in Ihrem Arbeitsbereich ausführt, kopieren Sie den in der Ausgabe des Befehls cdk deploy angezeigten Job URL-Link und fügen ihn in die Adressleiste Ihres Webbrowsers ein.
3. Um den Auftrag auszuführen, klicken Sie auf der Auftragsseite auf die Schaltfläche Run now.

(Optional) Schritt 5: Ändern einer Ressource

In diesem optionalen Schritt ändern Sie den Code des Notebooks, stellen das geänderte Notebook erneut bereit und verwenden dann den Auftrag, um das geänderte Notebook erneut auszuführen.

Wenn Sie keine Änderungen am Notebook vornehmen möchten, fahren Sie mit Schritt 6: Bereinigen fort.

1. Ändern Sie in der main.py-Datei die notebook-Variablendeklaration wie folgt:

   my_notebook = notebook.Notebook(
     scope          = self,
     id_            = "notebook",
     path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
     language       = "PYTHON",
     content_base64 = b64encode(b"display(spark.range(10))").decode("UTF-8")
   )
   

   Wie folgt:

   my_notebook = notebook.Notebook(
     scope          = self,
     id_            = "notebook",
     path           = f"{current_user.home}/CDKTF/{vars.resource_prefix}-notebook.py",
     language       = "PYTHON",
     content_base64 = b64encode(b'''
   data = [
      { "Category": 'A', "ID": 1, "Value": 121.44 },
      { "Category": 'B', "ID": 2, "Value": 300.01 },
      { "Category": 'C', "ID": 3, "Value": 10.99 },
      { "Category": 'E', "ID": 4, "Value": 33.87}
   ]
   
   df = spark.createDataFrame(data)
   
   display(df)
   ''').decode("UTF-8")
   )
   

   Hinweis

   Stellen Sie sicher, dass die Codezeilen wie dargestellt zwischen dreifachen Anführungszeichen (''') am Rand des Code-Editors ausgerichtet sind. Andernfalls fügt Terraform zusätzliche Leerzeichen in das Notebook ein, die dazu führen können, dass der neue Python-Code nicht ausgeführt werden kann.

2. Generieren Sie erneut das Terraform-Codeäquivalent für Ihr CDKTF-Projekt. Führen Sie zu diesem Zweck Folgendes aus:

   cdktf synth
   

3. Bevor Sie Änderungen vornehmen, können Sie die ausstehenden Ressourcenänderungen überprüfen. Führen Sie Folgendes aus:

   cdktf diff
   

4. Stellen Sie das Notebook und die Änderungen bereit, indem Sie den Befehl cdktf deploy ausführen.

   cdktf deploy
   

5. Wenn Sie zum Genehmigen aufgefordert werden, drücken Sie die Eingabetaste. Terraform ändert den Inhalt des Notebooks.

6. Um das geänderte Notebook anzuzeigen, das der Auftrag in Ihrem Arbeitsbereich ausführen wird, aktualisieren Sie das zuvor von Ihnen geöffnete Notebook, kopieren Sie den in der Ausgabe des Befehls cdk deploy angezeigten Notebook URL-Link und fügen ihn in die Adressleiste Ihres Webbrowsers ein.

7. Um den Auftrag anzuzeigen, der das geänderte Notebook in Ihrem Arbeitsbereich ausführt, aktualisieren Sie den zuvor von Ihnen geöffneten Auftrag, kopieren Sie den in der Ausgabe des Befehls cdk deploy angezeigten Job-URL-Link und fügen ihn in die Adressleiste Ihres Webbrowsers ein.

8. Um den Auftrag auszuführen, klicken Sie auf der Auftragsseite auf die Schaltfläche Run now.

Schritt 6: Bereinigung

In diesem Schritt verwenden Sie die CDKTF CLI, um das Notebook und den Auftrag aus Ihrem Azure Databricks-Arbeitsbereich zu entfernen.

1. Entfernen Sie die Ressourcen aus Ihrem Arbeitsbereich, indem Sie den Befehl cdktf destroy ausführen:

   cdktf destroy
   

2. Wenn Sie zum Genehmigen aufgefordert werden, drücken Sie die Eingabetaste. Terraform entfernt die Ressourcen aus Ihrem Arbeitsbereich.

Testen

Sie können Ihr CDKTF-Projekt testen, bevor Sie es bereitstellen. Siehe Komponententests in der CDKTF-Dokumentation.

Für Python-basierte CDKTF-Projekte können Sie Tests mithilfe des Python-Testframeworks pytest zusammen mit der Testing-Klasse des cdktf-Pakets schreiben und ausführen. Die folgende Beispieldatei mit dem Namen test_main.py testet den CDKTF-Code in der vorherigen main.py-Datei dieses Artikels. Der erste Test überprüft, ob das Notebook des Projekts die erwartete Base64-codierte Darstellung des Notebookinhalts enthält. Der zweite Test überprüft, ob der Auftrag des Projekts den erwarteten Auftragsnamen enthält. Führen Sie zum Ausführen dieser Tests den pytest-Befehl aus dem Stammverzeichnis des Projekts aus.

from cdktf import App, Testing
from cdktf_cdktf_provider_databricks import job, notebook
from main import MyStack

class TestMain:
  app = App()
  stack = MyStack(app, "cdktf-demo")
  synthesized = Testing.synth(stack)

  def test_notebook_should_have_expected_base64_content(self):
    assert Testing.to_have_resource_with_properties(
      received = self.synthesized,
      resource_type = notebook.Notebook.TF_RESOURCE_TYPE,
      properties = {
        "content_base64": "ZGlzcGxheShzcGFyay5yYW5nZSgxMCkp"
      }
    )

  def test_job_should_have_expected_job_name(self):
    assert Testing.to_have_resource_with_properties(
      received = self.synthesized,
      resource_type = job.Job.TF_RESOURCE_TYPE,
      properties = {
        "name": "cdktf-demo-job"
      }
    )

Weitere Ressourcen

• Terraform CDK Databricks-Anbieter Konstruktreferenz für TypeScript, Python, Java, C#und Go
• Aktivieren der Protokollierung für CDKTF-Anwendungen