Compartilhar via

Provedor Terraform CDK Databricks

  • Artigo

Observação

Este artigo aborda o CDKTF (Kit de Desenvolvimento de Nuvem para o Terraform), que não é fornecido nem tem suporte do Databricks. Para entrar em contato com o provedor, confira a Comunidade do Terraform.

Este artigo mostra como usar o Python junto com o Provedor do Terraform CDK Databricks e o Kit de Desenvolvimento em Nuvem para Terraform (CDKTF). O CDKTF é uma plataforma de infraestrutura como código (IaC) de terceiros que permite criar, implantar e gerenciar recursos do Azure Databricks usando linguagens de programação familiares, ferramentas e práticas de engenharia. Embora este artigo mostre como usar o Python, o CDKTF dá suporte a idiomas adicionais, como TypeScript, Java, C# e Go.

O provedor Terraform CDK Databricks é baseado no provedor Databricks Terraform. Para obter mais informações, confira Terraform Cloud. O CDKTF baseia-se no AWS CDK (kit de desenvolvimento de nuvem da AWS).

Requisitos

Você deve ter um workspace do Azure Databricks, pois este artigo implanta recursos em um workspace existente.

No computador de desenvolvimento local, você deve ter o seguinte instalado:

  • Terraform, versão 1.1 ou superior. Para verificar se você tem o Terraform instalado e verificar a versão instalada, execute o comando terraform -v no terminal ou com o PowerShell. Instale o Terraform se você ainda não o tiver instalado.

    terraform -v

  • Node.js versão 16.13 ou superior e npm. Para verificar se você tem Node.js e npm instalado e verificar as versões instaladas, execute os comandos node -v e npm -v. Versões posteriores do Node.js já incluem npm. Instale Node.js e npm usando o Gerenciador de Versão do Nó (nvm), se você não tiver Node.js e npm já instalado.

    node -v
npm -v

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

    cdktf --version

    Dica

    Você também pode instalar a CLI da CDKTF no macOS com Homebrew. Consulte Instalar CDKTF.

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

    python --version
pipenv --version

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

Etapa 1: criar um projeto CDKTF

Nesta etapa, no seu computador de desenvolvimento local, você configura a estrutura de diretórios necessária para um projeto CDKTF. Em seguida, você cria o projeto do CDKTF dentro dessa estrutura de diretórios.

  1. Crie um diretório vazio para seu projeto CDKTF e alterne para ele. Execute os seguintes comandos no seu terminal ou com o PowerShell:

    Unix, Linux, e macOS

    mkdir cdktf-demo
cd cdktf-demo

    Windows

    md cdktf-demo
cd cdktf-demo

  2. Crie um projeto CDKTF executando o seguinte comando:

    cdktf init --template=python --local

  3. Quando solicitado um Nome de Projeto, aceite o nome de projeto padrão cdktf-demo pressionando Enter.

  4. Quando solicitado uma Descrição de Projeto, aceite a descrição de projeto padrão pressionando Enter.

  5. Se solicitado Você deseja iniciar a partir de um projeto Terraform existente, insira N e pressione Enter.

  6. Se solicitado Você deseja enviar relatórios de falha para a equipe CDKTF, insira 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ê quer efetuar push do projeto para um repositório Git remoto.
  • cdktf.json, que contém configurações para seu projeto CDKTF. Consulte o Arquivo de Configuração para obter mais informações sobre as configurações.
  • help, que contém informações sobre algumas próximas etapas que você pode executar 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 o teste de unidade.
  • main.py, que contém o código Python que você escreve para o projeto do CDKTF.
  • Pipfile e Pipfile.lock, que gerenciam dependências de código para seu projeto CDKTF.

Etapa 2: definir recursos

Nesta etapa, você usará o provedor Terraform CDK Databricks para definir um notebook e um trabalho para executar esse notebook.

  1. Instale as dependências do projeto: usando pipenv, instale em seu projeto do CDKTF o Provedor CDK do Databricks Terraform para gerar recursos do Azure Databricks. Para fazer isso, execute o seguinte comando:

    pipenv install cdktf-cdktf-provider-databricks

  2. Substitua o conteúdo do arquivo main.py pelo código a seguir. Este código autentica o CDKTF com o seu workspace do Azure Databricks e, em seguida, gera um notebook junto com um trabalho para executar o notebook. Para exibir a documentação de sintaxe desse código, confira a Referência de constructo do provedor do CDK Databricks do Terraform 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 nomeado 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 configurações de cluster, como o número de trabalhadores, a cadeia de caracteres de versão do runtime do Spark 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    = "Standard_D3_v2"

Etapa 3: Implantar os recursos

Nesta etapa, você usará a CLI da CDKTF para implantar, no workspace do Azure Databricks existente, o notebook definido e o trabalho para executar esse notebook.

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

    cdktf synth

  2. Antes de fazer alterações, você pode examinar as alterações de recursos pendentes. Execute o seguinte:

    cdktf diff

  3. Implante o notebook e o trabalho executando o comando cdktf deploy.

    cdktf deploy

  4. Quando solicitado a aprovar, pressione Enter. O Terraform cria e implanta o notebook e o trabalho em seu workspace.

Etapa 4: Interagir com os recursos

Nesta etapa, você executa o trabalho no workspace do Azure Databricks, que executa o notebook especificado.

  1. Para exibir o notebook que o trabalho executará em seu workspace, copie o link da URL do Notebook que aparece na saída do comando cdk deploy e cole-o na barra de endereços do navegador da web.
  2. Para visualizar o trabalho que executa o notebook em seu workspace, copie o link URL do trabalho que aparece na saída do comando cdk deploy e cole-o na barra de endereços do seu 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 etapa opcional, você altera o código do notebook, reimplanta o notebook alterado e usa o trabalho para executá-lo novamente.

Se não quiser fazer nenhuma alteração no notebook, pule para a Etapa 6: Limpar.

  1. No arquivo main.py, altere a declaração de variável notebook do 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"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ço em branco adicional no notebook que poderá fazer com que o novo código Python falhe na execução.

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

    cdktf synth

  3. Antes de fazer alterações, você pode examinar as alterações de recursos pendentes. Execute o seguinte:

    cdktf diff

  4. Implante 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 visualizar o notebook alterado que o trabalho executará em seu workspace, atualize o notebook que você abriu anteriormente ou copie o link de URL do notebook que aparece na saída do comandocdk deploy e cole-o na barra de endereços do navegador da web.

  7. Para visualizar o trabalho que executa o notebook alterado em seu workspace, atualize o trabalho que você abriu anteriormente ou copie o link URL do trabalho que aparece na saída do comandocdk deploy e cole-o na barra de endereços do navegador da web.

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

Etapa 6: Limpeza

Nesta etapa, você usará a CLI da CDKTF para remover o notebook e o trabalho do workspace do Azure Databricks.

  1. Remova os recursos do seu workspace executando o comandocdktf destroy:

    cdktf destroy

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

Testando

Você pode testar o seu projeto CDKTF antes de implantá-lo. Confira testes de unidade na documentação do CDKTF.

Para projetos CDKTF baseados em Python, você pode escrever e executar testes usando a estrutura de teste pytest do Python junto com a classe Testing do pacote cdktf. O arquivo de exemplo a seguir chamado 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 do trabalho 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"
      }
    )

Mais recursos