Fournisseur Databricks Terraform CDK

attention

Databricks ne recommande pas l'utilisation du Cloud Development Kit for Terraform (CDKTF) pour la gestion des Ressources Databricks. HashiCorp a annoncé la fin du projet CDKTF, et le projet ne bénéficiera plus de développement actif ni de support.

Au lieu d'utiliser CDKTF, Databricks recommande d'utiliser le fournisseur Databricks Terraform directement pour gérer vos ressources Databricks. Le fournisseur Terraform est la solution d'infrastructure en tant que code (IaC) officiellement prise en charge pour Databricks. Voir le fournisseur Databricks Terraform.

remarque

Cet article couvre le Cloud Development Kit pour Terraform (CDKTF), qui est développé par un tiers. Pour contacter le fournisseur, consultez la Communauté Terraform.

Cet article vous montre comment utiliser Python avec le fournisseur Databricks Terraform CDK et le Cloud Development Kit pour Terraform (CDKTF). Le CDKTF est une plateforme tierce d'infrastructure en tant que code (IaC) qui vous permet de créer, de déployer et de gérer des ressources Databricks en utilisant des langages de programmation, des outils et des pratiques d'ingénierie familiers. Bien que cet article vous montre comment utiliser Python, le CDKTF prend en charge d'autres langages tels que TypeScript, Java, C# et Go.

Le fournisseur Databricks Terraform CDK est basé sur le fournisseur Databricks Terraform. Pour plus d'informations, consultez Terraform Cloud. Le CDKTF est basé sur le AWS Cloud Development Kit (AWS CDK).

Exigences

Vous devez disposer d'un Databricks Workspace, car cet article déploie des ressources dans un Workspace existant.

Sur votre machine de développement locale, vous devez avoir installé les éléments suivants :

Terraform, version 1.1 ou supérieure. Pour vérifier si vous avez installé Terraform et pour vérifier la version installée, exécutez la commande terraform -v depuis votre terminal ou avec PowerShell. Installez Terraform, si vous ne l'avez pas déjà installé.
Bash
```
terraform -v
```
Node.js, version 16.13 ou ultérieure, et npm. Pour vérifier si Node.js et npm sont installés, et pour vérifier les versions installées, exécutez les commandes node -v et npm -v. Les dernières versions de Node.js incluent déjà npm. Installez Node.js et npm en utilisant Node Version Manager (nvm), si vous n'avez pas déjà Node.js et npm installés.
Bash
```
node -v
npm -v
```
The CDKTF CLI. Pour vérifier si vous avez le CDKTF CLI installé, et pour vérifier la version installée, exécutez la commande cdktf --version. Installez le CDKTF CLI en utilisant npm, si vous ne l'avez pas déjà installé.
Bash
```
cdktf --version
```

astuce

Vous pouvez également installer le CDKTF CLI sur macOS avec Homebrew. Consultez Installer CDKTF.

Python version 3.7 ou supérieure et pipenv version 2021.5.29 ou supérieure. Pour vérifier si Python et pipenv sont installés, et pour vérifier les versions installées, exécutez les commandes python --version et pipenv --version. Installez Python et installez pipenv, s'ils ne sont pas déjà installés.
Bash
```
python --version
pipenv --version
```
Authentification Databricks configurée pour le type d’authentification pris en charge que vous souhaitez utiliser. Consultez Authentification dans la documentation du fournisseur Databricks Terraform.

Étape 1 : Créer un projet CDKTF

Dans cette étape, vous configurez sur votre machine de développement locale la structure de répertoire nécessaire pour un projet CDKTF. Vous créez ensuite votre projet CDKTF au sein de cette arborescence de répertoires.

Créez un répertoire vide pour votre projet CDKTF, puis basculez-y. Exécutez les commandes suivantes dans votre terminal ou avec PowerShell :

Unix, Linux, and macOS
Windows

Bash
mkdir cdktf-demo
cd cdktf-demo

PowerShell
md cdktf-demo
cd cdktf-demo

Créez un projet CDKTF en exécutant la commande suivante :
Bash
```
cdktf init --template=python --local
```
Lorsque vous êtes invité à saisir un **Nom de projet**, acceptez le nom de projet default de cdktf-demo en appuyant sur **Entrée**.
Lorsque vous êtes invité à saisir une Description du projet , acceptez la description de projet default en appuyant sur Entrée .
Si l'invite **Voulez-vous start à partir d’un projet Terraform existant** s'affiche, saisissez N et appuyez sur **Entrée**.
Si vous êtes invité à la question Voulez-vous envoyer des rapports d'incident à l'équipe CDKTF , entrez n et appuyez sur Entrée .

Le CDKTF crée les fichiers et sous-répertoires suivants dans votre répertoire cdktf-demo :

.gitignore, qui est une liste de fichiers et de répertoires que Git ignore si vous souhaitez pousser ce projet vers un repository Git distant.
cdktf.json, qui contient les paramètres de configuration de votre projet CDKTF. Consultez le fichier de configuration pour plus d'informations sur les paramètres de configuration.
help, qui contient des informations sur les prochaines étapes que vous pouvez suivre pour travailler avec votre projet CDKTF.
main-test.py, qui contient des tests unitaires que vous pouvez rédiger pour votre projet CDKTF. Consultez Tests unitaires pour plus d'informations sur les tests unitaires.
main.py, qui contient le code Python que vous écrivez pour votre projet CDKTF.
Pipfile et Pipfile.lock, qui gèrent les dépendances de code pour votre projet CDKTF.

Étape 2 : Définir les ressources

Dans cette étape, vous utilisez le fournisseur Terraform CDK Databricks pour définir un Notebook et un job afin d'exécuter ce Notebook.

Installez les dépendances du projet : à l’aide de pipenv, installez le Terraform CDK Databricks Provider dans votre projet CDKTF pour générer des ressources Databricks. Pour ce faire, exécutez ce qui suit :
Bash
```
pipenv install cdktf-cdktf-provider-databricks
```
Remplacez le contenu du fichier main.py par le code suivant. Ce code authentifie le CDKTF avec votre Workspace Databricks, puis génère un Notebook ainsi qu'un Job pour exécuter le Notebook. Pour consulter la documentation syntaxique de ce code, consultez la référence de construction du fournisseur Terraform CDK Databricks pour Python.

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

Créez un fichier nommé vars.py dans le même répertoire que main.py. Remplacez les valeurs suivantes par les vôtres afin de spécifier un préfixe de ressource et des paramètres de cluster, tels que le nombre de Worker, la chaîne de version d'exécution Spark et le type de nœud.

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

Étape 3 : Déployez les Ressources

Dans cette étape, vous utilisez le CDKTF CLI pour déployer, dans votre Workspace Databricks existant, le Notebook défini et le Job pour exécuter ce Notebook.

Générer le code Terraform équivalent pour votre projet CDKTF. Pour ce faire, exécutez la commande cdktf synth.
Bash
```
cdktf synth
```
Avant d'apporter des modifications, vous pouvez examiner les modifications de ressources en attente. Exécutez ce qui suit :
Bash
```
cdktf diff
```
Déployez le Notebook et le Job en exécutant la commande cdktf deploy.
Bash
```
cdktf deploy
```
Lorsque vous êtes invité à « Approuver » , appuyez sur Entrée . Terraform crée et déploie le Notebook et le Job dans votre Workspace.

Étape 4 : Interagir avec les ressources.

Dans cette étape, vous exécutez le Job dans votre Workspace Databricks, qui exécute le Notebook spécifié.

Pour afficher le Notebook que le Job exécutera dans votre Workspace, copiez le URL du Notebook Link qui apparaît dans la sortie de la commande cdk deploy et collez-le dans la barre d'adresse de votre navigateur web.
Pour afficher le Job qui exécute le Notebook dans votre Workspace, copiez le Job URL Link qui apparaît dans la sortie de la commande cdk deploy et collez-le dans la barre d'adresse de votre navigateur web.
Pour exécuter le job, cliquez sur le bouton Exécuter maintenant sur la page du job.

(Facultatif) Étape 5 : apporter des modifications à une ressource

Dans cette étape facultative, vous modifiez le code du Notebook, redéployez le Notebook modifié, puis utilisez le Job pour réexécuter le Notebook modifié.

Si vous ne souhaitez pas apporter de modifications au Notebook, passez à l'Étape 6 : nettoyage.

Dans le fichier main.py, modifiez la déclaration de variable notebook de la manière suivante :

Python
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")
)

Aux éléments suivants :

Python
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")
)

remarque

Assurez-vous que les lignes de code entre les triples guillemets (''') sont alignées avec le bord de votre éditeur de code, comme indiqué. Autrement, Terraform insérera des espaces blancs supplémentaires dans le Notebook, ce qui pourrait empêcher l'exécution du nouveau code Python.

Régénérez le code Terraform équivalent pour votre projet CDKTF. Pour ce faire, exécutez ce qui suit :
Bash
```
cdktf synth
```
Avant d'apporter des modifications, vous pouvez examiner les modifications de ressources en attente. Exécutez ce qui suit :
Bash
```
cdktf diff
```
Déployez les modifications du notebook en exécutant la commande cdktf deploy.
Bash
```
cdktf deploy
```
Lorsque vous êtes invité à « Approuver » , appuyez sur Entrée . Terraform modifie le contenu du notebook.
Pour afficher le Notebook modifié que le Job exécutera dans votre Workspace, refresh le Notebook que vous avez ouvert précédemment, ou copiez le Link URL du Notebook qui apparaît dans la sortie de la commande cdk deploy et collez-le dans la barre d'adresse de votre navigateur web.
Pour afficher le job qui exécute le notebook modifié dans votre Workspace, refresh le job que vous avez ouvert précédemment, ou copiez le Link URL du job qui apparaît dans la sortie de la commande cdk deploy et collez-le dans la barre d’adresse de votre navigateur web.
Pour exécuter le job, cliquez sur le bouton Exécuter maintenant sur la page du job.

Étape 6 : Nettoyer

Au cours de cette étape, vous utilisez la CLI CDKTF pour supprimer le notebook et le job de votre workspace Databricks.

Supprimez les ressources de votre workspace en exécutant la commande cdktf destroy :
Bash
```
cdktf destroy
```
Lorsque vous êtes invité à « Approuver » , appuyez sur Entrée . Terraform supprime les Ressources de votre Workspace.

Test

Vous pouvez tester votre projet CDKTF avant de le déployer. Consultez les tests unitaires dans la documentation CDKTF.

Pour les projets CDKTF basés sur Python, vous pouvez écrire et exécuter des tests à l'aide du framework de test Python pytest ainsi que la classe Testing du package cdktf. Le fichier d'exemple suivant nommé test_main.py teste le code CDKTF dans le fichier main.py précédent de cet article. Le premier test vérifie si le notebook du projet contiendra la représentation encodée en Base64 attendue du contenu du notebook. Le deuxième test vérifie si le Job du projet contiendra le nom de Job attendu. Pour exécuter ces tests, exécutez la commande pytest à partir du répertoire racine du projet.

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

Ressources supplémentaires

Référence de construction du fournisseur Terraform CDK Databricks pour TypeScript, Python, Java, C# et Go
Activez la journalisation pour les applications CDKTF.

Exigences​

Étape 1 : Créer un projet CDKTF​

Étape 2 : Définir les ressources​

Étape 3 : Déployez les Ressources​

Étape 4 : Interagir avec les ressources.​

(Facultatif) Étape 5 : apporter des modifications à une ressource​

Étape 6 : Nettoyer​

Test​

Ressources supplémentaires​