Pular para o conteúdo principal

Provedor do Terraform CDK Databricks

nota

Este artigo aborda o Cloud Development Kit for Terraform (CDKTF), que é desenvolvido por terceiros. Para entrar em contato com o provedor, consulte o site Terraform comunidade.

Este artigo mostra como usar o Python junto com o provedorTerraform CDK Databricks e o Cloud Development Kit for Terraform (CDKTF). O CDKTF é uma plataforma de infraestrutura como código (IaC) de terceiros que permite ao senhor criar, implantar e gerenciar Databricks recurso usando linguagens de programação, ferramentas e práticas de engenharia familiares. Embora este artigo mostre como usar o Python, o CDKTF oferece suporte a outras linguagens, como TypeScript, Java, C# e Go.

O provedor Terraform CDK Databricks é baseado no provedor Databricks Terraform. Para obter mais informações, consulte Terraform Cloud. O CDKTF é baseado no AWS Cloud Development Kit (AWS CDK).

Requisitos​

O senhor deve ter um Databricks workspace, pois este artigo implantou recurso em um workspace existente.

Em sua máquina de desenvolvimento local, você deve ter o seguinte instalado:

  • Terraform, versão 1.1 ou superior. Para verificar se o senhor tem o site Terraform instalado e para verificar a versão instalada, execute o comando terraform -v em seu terminal ou com PowerShell. Instale o Terraform, se o senhor ainda não o tiver instalado.

    Bash
    terraform -v

  • Node.js, versão 16.13 ou superior, e npm. Para verificar se o senhor tem Node.js e npm instalados e para verificar as versões instaladas, execute os comandos node -v e npm -v. As versões mais recentes do Node.js já incluem npm. Instale o Node.js e o npm usando o Node Version Manager (nvm), se o senhor não tiver o Node.js e o npm já instalados.

    Bash
    node -v
    npm -v

  • O CDKTF CLI. Para verificar se o senhor tem o CDKTF CLI instalado e para verificar a versão instalada, execute o comando cdktf --version. Instale o CDKTF CLI usando o npm, se o senhor ainda não o tiver instalado.

    Bash
    cdktf --version
dica

O senhor também pode instalar o CDKTF CLI no macOS com o Homebrew. Consulte Instalar o CDKTF.

  • Python versão 3.7 ou superior e pipenv versão 2021.5.29 ou superior. Para verificar se o senhor tem Python e pipenv instalados e para verificar as versões instaladas, execute os comandos python --version e pipenv --version. Instale o Python e o pipenv, se ainda não estiverem instalados.

    Bash
    python --version
    pipenv --version

  • Autenticação do Databricks configurada para o tipo de autenticação compatível que o senhor deseja usar. Consulte Autenticação na documentação do provedor Databricks Terraform.

Etapa 1: criar um projeto CDKTF​

Nesta passo, em sua máquina de desenvolvimento local, você configura a estrutura de diretórios necessária para um projeto CDKTF. Em seguida, você cria seu projeto CDKTF nessa estrutura de diretório.

  1. Crie um diretório vazio para seu projeto CDKTF e, em seguida, mude para ele. Execute o seguinte comando em seu terminal ou com PowerShell:
Bash
mkdir cdktf-demo
cd cdktf-demo

  1. Crie um projeto CDKTF executando o seguinte comando:

    Bash
    cdktf init --template=python --local

  2. Quando for solicitado um nome de projeto, aceite o nome de projeto default de cdktf-demo pressionando Enter .

  3. Quando for solicitada uma Descrição do projeto , aceite a descrição do projeto default pressionando Enter .

  4. Se for solicitado O senhor deseja começar a partir de um projeto Terraform existente , digite N e pressione Enter .

  5. Se solicitado Deseja enviar relatórios de falhas para a equipe do CDKTF, n digite e pressione Enter.

O CDKTF cria os seguintes arquivos e subdiretórios em seu diretório cdktf-demo:

  • .gitignoreque é uma lista de arquivos e diretórios que o Git ignora se o senhor quiser enviar esse projeto para um repositório Git remoto.
  • cdktf.json, que contém as configurações do seu projeto CDKTF. Consulte Arquivo de configuração para obter mais informações sobre as definições de configuração.
  • helpque contém informações sobre as próximas etapas que o senhor pode seguir para trabalhar com seu projeto CDKTF.
  • main-test.py, que contém testes unitários de suporte que você pode escrever para seu projeto CDKTF. Consulte Testes de unidade para obter mais informações sobre testes de unidade.
  • main.pyque contém o código Python que o senhor escreve para o seu projeto CDKTF.
  • Pipfile e Pipfile.lock, que gerenciam dependências de código para seu projeto CDKTF.

Etapa 2: Definir recurso​

Nesta passo, você usará o provedor Terraform CDK Databricks para definir um Notebook e um Job para executar esse Notebook.

  1. Instale as dependências do projeto: usando pipenv, instale em seu projeto CDKTF o provedorTerraform CDK Databricks para gerar o recurso Databricks. Para fazer isso, execute o seguinte:

    Bash
    pipenv install cdktf-cdktf-provider-databricks

  2. Substitua o conteúdo do arquivo main.py pelo código a seguir. Esse código autentica o CDKTF com seu Databricks workspace e, em seguida, gera um Notebook juntamente com um Job para executá-lo. Para obter a documentação de sintaxe do view para esse código, consulte a referência de construção do provedorTerraform CDK Databricks para 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()

  1. Crie um arquivo chamado vars.py no mesmo diretório de main.py. Substitua os valores a seguir por seus próprios valores para especificar um prefixo de recurso e as configurações de clustering, como o número de trabalhadores, as strings de versão de tempo de execução doSpark e o tipo de nó.
Python
#!/usr/bin/env python
resource_prefix = "cdktf-demo"
num_workers     = 1
spark_version   = "14.3.x-scala2.12"
node_type_id    = "i3.xlarge"

Etapa 3: implantado o recurso​

Nesta passo, você usa a CLI do CDKTF para aprimorar, em seu workspace Databricks existente, o Notebook definido e o Job para execução desse Notebook.

  1. Gere o código equivalente do Terraform para seu projeto CDKTF. Para isso, execute o comando cdktf synth.

    Bash
    cdktf synth

  2. Antes de fazer alterações, o senhor pode revisar as alterações pendentes no recurso. execução o seguinte:

    Bash
    cdktf diff

  3. Implante o Notebook e o Job executando o comando cdktf deploy.

    Bash
    cdktf deploy

  4. Quando solicitado a Aprovar, pressione Enter. Terraform cria e implanta o Notebook e o Job em seu site workspace.

Etapa 4: Interagir com o recurso​

Nesta passo, você executa o Job em seu workspace do Databricks, que executa o Notebook especificado.

  1. Para view o Notebook que o Job executará em seu workspace, copie o link do URLNotebook que aparece na saída do comando cdk deploy e cole-o na barra de endereços do navegador da Web.
  2. Para view o trabalho que executa o Notebook em seu workspace, copie o link do URLJob que aparece na saída do comando cdk deploy e cole-o na barra de endereços do navegador da Web.
  3. Para executar o trabalho, clique no botão executar agora na página do trabalho.

(Opcional) Etapa 5: fazer alterações em um recurso​

Nesta passo opcional, você altera o código do Notebook, reimplementa o Notebook alterado e, em seguida, usa o Job para executar novamente o Notebook alterado.

Se o senhor não quiser fazer nenhuma alteração no Notebook, pule para a Etapa 6: Limpeza.

  1. No arquivo main.py, altere a declaração da variável notebook da seguinte:

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

    Para o seguinte:

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

Certifique-se de que as linhas de código entre aspas triplas (''') estejam alinhadas com a borda do seu editor de código, conforme mostrado. Caso contrário, o site Terraform inserirá espaços em branco adicionais no Notebook, o que pode fazer com que o novo código Python não seja executado.

  1. Gerar novamente o código equivalente do Terraform para seu projeto CDKTF. Para fazer isso, execute o seguinte:

    Bash
    cdktf synth

  2. Antes de fazer alterações, o senhor pode revisar as alterações pendentes no recurso. execução o seguinte:

    Bash
    cdktf diff

  3. Implante as alterações do Notebook executando o comando cdktf deploy.

    Bash
    cdktf deploy

  4. Quando solicitado a Aprovar, pressione Enter. Terraform altera o conteúdo do Notebook.

  5. Para view o Notebook alterado que o Job executará em seu workspace, refresh o Notebook que o senhor abriu anteriormente ou copie o link do URLNotebook que aparece na saída do comando cdk deploy e cole-o na barra de endereços do navegador da Web.

  6. Para view o Job que executa o Notebook alterado em seu workspace, refresh o Job que você abriu anteriormente ou copie o link do URLJob que aparece na saída do comando cdk deploy e cole-o na barra de endereços do navegador da Web.

  7. Para executar o trabalho, clique no botão executar agora na página do trabalho.

Etapa 6: Limpar​

Nesta passo, você usa a CLI do CDKTF para remover o Notebook e Job do workspace do Databricks.

  1. Remova o recurso do site workspace executando o comando cdktf destroy:

    Bash
    cdktf destroy

  2. Quando solicitado a Aprovar, pressione Enter. Terraform remove o recurso do site workspace.

Testando​

O senhor pode testar o projeto CDKTF antes de implantá-lo. Consulte Testes de unidade na documentação do CDKTF.

Para projetos CDKTF baseados em Python, o senhor pode escrever e executar testes usando a estrutura de teste Python pytest juntamente com a classe cdktf do pacote Testing. O arquivo de exemplo a seguir, denominado test_main.py, testa o código CDKTF no arquivo main.py anterior deste artigo. O primeiro teste verifica se o Notebook do projeto conterá a representação codificada em Base64 esperada do conteúdo do Notebook. O segundo teste verifica se o trabalho do projeto conterá o nome esperado do trabalho. Para executar esses testes, execute o comando pytest no diretório raiz do projeto.

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

Mais recurso​

Última atualização em