Condividi tramite

Terraform CDK Databricks Provider

  • Articolo

Nota

Questo articolo illustra il Kit di sviluppo cloud per Terraform (CDKTF), che non è fornito né supportato da Databricks. Per contattare il provider, vedere Terraform Community.

Questo articolo illustra come usare Python insieme a Terraform CDK Databricks Provider e Cloud Development Kit per Terraform (CDKTF). CDKTF è una piattaforma IaC (Infrastructure as Code) di terze parti che consente di creare, distribuire e gestire risorse di Azure Databricks usando linguaggi di programmazione, strumenti e procedure di progettazione familiari. Anche se questo articolo illustra come usare Python, CDKTF supporta linguaggi aggiuntivi, ad esempio TypeScript, Java, C# e Go.

Il provider Terraform CDK Databricks si basa sul provider Databricks Terraform. Per altre informazioni, vedere Terraform Cloud. CDKTF si basa su AWS Cloud Development Kit (AWS CDK).

Requisiti

È necessario avere un'area di lavoro di Azure Databricks, perché questo articolo distribuisce le risorse in un'area di lavoro esistente.

Nel computer di sviluppo locale è necessario avere installato quanto segue:

  • Terraform, versione 1.1 o successiva. Per verificare se Terraform è installato e controllare la versione installata, eseguire il comando terraform -v dal terminale o con PowerShell. Installare Terraform, se non è già installato.

    terraform -v

  • Node.js, versione 16.13 o successiva e npm. Per verificare se sono stati Node.js e npm installati e per controllare le versioni installate, eseguire i comandi node -v e npm -v. Le versioni più recenti di Node.js includono npmgià . Installare Node.js e npm usando Node Version Manager (nvm), se non è già installato Node.js e npm già installato.

    node -v
npm -v

  • Interfaccia della riga di comando di CDKTF. Per verificare se è installata l'interfaccia della riga di comando di CDKTF e per controllare la versione installata, eseguire il comando cdktf --version. Installare l'interfaccia della riga di comando di CDKTF usando npm, se non è già installata.

    cdktf --version

    Suggerimento

    È anche possibile installare l'interfaccia della riga di comando di CDKTF in macOS con Homebrew. Vedere Installare CDKTF.

  • Python versione 3.7 o successiva e pipenv versione 2021.5.29 o successiva. Per verificare se Python è installato e pipenv controllare le versioni installate, eseguire i python --version comandi e pipenv --version. Installare Python e installare pipenv, se non sono già installati.

    python --version
pipenv --version

  • Autenticazione di Azure Databricks configurata per il tipo di autenticazione supportato che si vuole usare. Consultare Autenticazione nella documentazione del provider Databricks Terraform.

Passaggio 1: Creare un progetto CDKTF

In questo passaggio, nel computer di sviluppo locale si configura la struttura di directory necessaria per un progetto CDKTF. Creare quindi il progetto CDKTF all'interno di questa struttura di directory.

  1. Creare una directory vuota per il progetto CDKTF e quindi passare a essa. Eseguire i comandi seguenti nel terminale o con PowerShell:

    Unix, Linux e macOS

    mkdir cdktf-demo
cd cdktf-demo

    Finestre

    md cdktf-demo
cd cdktf-demo

  2. Creare un progetto CDKTF eseguendo il comando seguente:

    cdktf init --template=python --local

  3. Quando viene richiesto un nome di progetto, accettare il nome predefinito del cdktf-demo progetto premendo INVIO.

  4. Quando viene richiesta una descrizione progetto, accettare la descrizione predefinita del progetto premendo INVIO.

  5. Se viene richiesto Di iniziare da un progetto Terraform esistente, immettere N e premere INVIO.

  6. Se viene richiesto Inviare segnalazioni di arresto anomalo al team CDKTF, immettere n e premere INVIO.

CDKTF crea i file e le sottodirectory seguenti nella cdktf-demo directory:

  • .gitignore, che è un elenco di file e directory che Git ignora se si vuole eseguire il push di questo progetto in un repository Git remoto.
  • cdktf.json, che contiene le impostazioni di configurazione per il progetto CDKTF. Per altre informazioni sulle impostazioni di configurazione, vedere File di configurazione.
  • help, che contiene informazioni su alcuni passaggi successivi che è possibile eseguire per lavorare con il progetto CDKTF.
  • main-test.py, che contiene unit test di supporto che è possibile scrivere per il progetto CDKTF. Per altre informazioni sugli unit test, vedere Unit Test .
  • main.py, che contiene il codice Python scritto per il progetto CDKTF.
  • Pipfile e Pipfile.lock, che gestiscono le dipendenze del codice per il progetto CDKTF.

Passaggio 2: Definire le risorse

In questo passaggio si usa il provider Terraform CDK Databricks per definire un notebook e un processo per eseguire tale notebook.

  1. Installare le dipendenze del progetto: usando pipenv, installare nel progetto CDKTF Terraform CDK Databricks Provider per generare le risorse di Azure Databricks. A tale scopo, eseguire le operazioni seguenti:

    pipenv install cdktf-cdktf-provider-databricks

  2. Sostituire il contenuto del main.py file con il codice seguente. Questo codice autentica CDKTF con l'area di lavoro di Azure Databricks, quindi genera un notebook insieme a un processo per eseguire il notebook. Per visualizzare la documentazione sulla sintassi per questo codice, vedere le informazioni di riferimento sul costrutto del provider Databricks di Terraform CDK per 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. Creare un file denominato vars.py nella stessa directory di main.py. Sostituire i valori seguenti con i propri valori per specificare un prefisso di risorsa e le impostazioni del cluster, ad esempio il numero di ruoli di lavoro, la stringa della versione del runtime Spark e il tipo di nodo. 

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

Passaggio 3: Distribuire le risorse

In questo passaggio si usa l'interfaccia della riga di comando di CDKTF per distribuire, nell'area di lavoro di Azure Databricks esistente, nel notebook definito e nel processo per eseguire il notebook.

  1. Generare l'equivalente del codice Terraform per il progetto CDKTF. A tale scopo, eseguire il comando cdktf synth.

    cdktf synth

  2. Prima di apportare modifiche, è possibile esaminare le modifiche delle risorse in sospeso. Esegui le operazioni seguenti:

    cdktf diff

  3. Distribuire il notebook e il processo eseguendo il cdktf deploy comando .

    cdktf deploy

  4. Quando viene richiesto di approvare, premere INVIO. Terraform crea e distribuisce il notebook e il processo nell'area di lavoro.

Passaggio 4: Interagire con le risorse

In questo passaggio si esegue il processo nell'area di lavoro di Azure Databricks, che esegue il notebook specificato.

  1. Per visualizzare il notebook che il processo verrà eseguito nell'area di lavoro, copiare il collegamento URL del notebook visualizzato nell'output del cdk deploy comando e incollarlo nella barra degli indirizzi del Web browser.
  2. Per visualizzare il processo che esegue il notebook nell'area di lavoro, copiare il collegamento URL processo visualizzato nell'output del cdk deploy comando e incollarlo nella barra degli indirizzi del Web browser.
  3. Per eseguire il processo, fare clic sul pulsante Esegui ora nella pagina del processo.

(Facoltativo) Passaggio 5: Apportare modifiche a una risorsa

In questo passaggio facoltativo si modifica il codice del notebook, si ridistribuisce il notebook modificato e quindi si usa il processo per eseguire nuovamente il notebook modificato.

Se non si desidera apportare modifiche al notebook, passare al passaggio 6: Pulire.

  1. main.py Nel file modificare la dichiarazione di notebook variabile da quanto segue:

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

    Con la seguente:

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

    Nota

    Assicurarsi che le righe di codice tra virgolette triple (''') siano allineate al bordo dell'editor di codice, come illustrato. In caso contrario, Terraform inserisce spazi vuoti aggiuntivi nel notebook che potrebbe causare l'esito negativo dell'esecuzione del nuovo codice Python.

  2. Rigenerare l'equivalente del codice Terraform per il progetto CDKTF. A tale scopo, eseguire le operazioni seguenti:

    cdktf synth

  3. Prima di apportare modifiche, è possibile esaminare le modifiche delle risorse in sospeso. Esegui le operazioni seguenti:

    cdktf diff

  4. Distribuire le modifiche del notebook eseguendo il cdktf deploy comando .

    cdktf deploy

  5. Quando viene richiesto di approvare, premere INVIO. Terraform modifica il contenuto del notebook.

  6. Per visualizzare il notebook modificato che verrà eseguito nell'area di lavoro, aggiornare il notebook aperto in precedenza o copiare il collegamento URL notebook visualizzato nell'output del cdk deploy comando e incollarlo nella barra degli indirizzi del Web browser.

  7. Per visualizzare il processo che esegue il notebook modificato nell'area di lavoro, aggiornare il processo aperto in precedenza o copiare il collegamento URL processo visualizzato nell'output del cdk deploy comando e incollarlo nella barra degli indirizzi del Web browser.

  8. Per eseguire il processo, fare clic sul pulsante Esegui ora nella pagina del processo.

Passaggio 6: Pulire

In questo passaggio si usa l'interfaccia della riga di comando di CDKTF per rimuovere il notebook e il processo dall'area di lavoro di Azure Databricks.

  1. Rimuovere le risorse dall'area di lavoro eseguendo il cdktf destroy comando :

    cdktf destroy

  2. Quando viene richiesto di approvare, premere INVIO. Terraform rimuove le risorse dall'area di lavoro.

Test

È possibile testare il progetto CDKTF prima di distribuirlo. Vedere Unit Test nella documentazione di CDKTF.

Per i progetti CDKTF basati su Python, è possibile scrivere ed eseguire test usando il framework di test Python pytest insieme alla cdktf classe del Testing pacchetto. Il file di esempio seguente denominato test_main.py testa il codice CDKTF nel file precedente main.py di questo articolo. Il primo test verifica se il notebook del progetto conterrà la rappresentazione prevista con codifica Base64 del contenuto del notebook. Il secondo test verifica se il processo del progetto conterrà il nome del processo previsto. Per eseguire questi test, eseguire il pytest comando dalla directory radice del progetto.

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

Altre risorse