Provedor de Databricks do Terraform CDK

Observação

Este artigo aborda o cloud Development Kit for Terraform (CDKTF), que não é fornecido nem suportado pelo Databricks. Para entrar em contato com o provedor, consulte a comunidade Terraform.

Este artigo mostra como usar o site Python juntamente 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 que o senhor crie, implante e gerencie Databricks recursos usando linguagens de programação, ferramentas e práticas de engenharia familiares. Embora este artigo mostre como usar 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

Você deve ter um workspace do Databricks, pois este artigo aprimora recursos 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 você possui o Terraform instalado e verificar a versão instalada, execute o comando terraform -v do seu terminal ou com o PowerShell. Instale o Terraform, caso ainda não o tenha instalado.

    terraform -v

  • Node.js, versão 16.13 ou superior e npm. Para verificar se você 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 Node.js e npm usando o Node Version Manager (nvm), se você não tiver Node.js e npm já instalados.

    node -v
npm -v

  • A CLI do CDKTF. Para verificar se você possui o CDKTF CLI instalado e para verificar a versão instalada, execute o comando cdktf --version. Instale o CDKTF CLI usando npm, caso ainda não o tenha instalado.

    cdktf --version

    Dica

    Você 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.

    python --version
pipenv --version

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

Passo 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, alterne para ele. execute os seguintes comandos no seu terminal ou com o PowerShell:

    mkdir cdktf-demo
cd cdktf-demo

    md cdktf-demo
cd cdktf-demo

  2. Crie um projeto CDKTF executando o seguinte comando:

    cdktf init --template=python --local

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

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

  5. Se solicitado Do you want to start from an existente Terraform project, digite N e pressione Enter.

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

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

  • .gitignore, que é uma lista de arquivos e diretórios que o Git ignora se você quiser enviar este projeto para um repositório Git remoto.

  • cdktf.json, que contém definições de configuração para seu projeto CDKTF. Consulte Arquivo de configuração para obter mais informações sobre as definições de configuração.

  • help, que contém informações sobre alguns próximos passos que você pode seguir para trabalhar com seu projeto CDKTF.

  • main-test.py, que contém testes de unidade de suporte que você pode escrever para seu projeto CDKTF. Consulte Testes de unidade para obter mais informações sobre testes de unidade.

  • main.py, que contém o código Python que você escreve para seu projeto CDKTF.

  • Pipfile e Pipfile.lock, que gerenciam dependências de código para seu projeto CDKTF.

Passo 2: Definir recursos

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:

    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 executar o Notebook. Para acessar a documentação de sintaxe do view para esse código, consulte a referência de construção do provedorTerraform CDK Databricks para 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. Crie um arquivo chamado vars.py no mesmo diretório que main.py. Substitua os valores a seguir por seus próprios valores para especificar um prefixo de recurso e as configurações do site cluster, como o número de trabalhadores, as cadeias de caracteres da versão de tempo de execução do siteSpark e o tipo de nó.

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

Passo 3: aprimorar os recursos

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 Terraform equivalente para seu projeto CDKTF. Para fazer isso, execute o comando cdktf synth .

    cdktf synth

  2. Antes de fazer alterações, você pode revisar as alterações de recursos pendentes. execução o seguinte:

    cdktf diff

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

    cdktf deploy

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

Passo 4: Interagir com os recursos

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

  1. Para view o Notebook em que o Job será executado 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 Job 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 Job, clique no botão Execution Now na página Job .

(Opcional) Passo 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.

Caso não queira fazer nenhuma alteração no Notebook, pule para o passo 6: Limpar.

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

    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:

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

    Observação

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

  2. Gere novamente o código Terraform equivalente para seu projeto CDKTF. Para fazer isso, execute o seguinte:

    cdktf synth

  3. Antes de fazer alterações, você pode revisar as alterações de recursos pendentes. execução o seguinte:

    cdktf diff

  4. aprimore as alterações do Notebook executando o comando cdktf deploy.

    cdktf deploy

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

  6. Para view o Notebook alterado que o Job executará em seu workspace, refresh o Notebook que você 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.

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

  8. Para executar o Job, clique no botão Execution Now na página Job .

Passo 6: Limpar

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

  1. Remova os recursos de seu workspace executando o comando cdktf destroy:

    cdktf destroy

  2. Quando solicitado a Aprovar, pressione Enter. O Terraform remove os recursos do seu workspace.

Testes

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 junto com a classe Testing do pacote cdktf. 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 site Notebook do projeto conterá a representação codificada em Base64 esperada do conteúdo do site Notebook. O segundo teste verifica se o site Job do projeto conterá o nome Job esperado. Para executar esses testes, execute o comando pytest no diretório raiz do projeto.

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