Provedor Terraform CDK Databricks

Artigo
08/29/2024

Nota

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 Python junto com o Terraform CDK Databricks Provider e o Cloud Development Kit for 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, ferramentas e práticas de engenharia familiares. Embora este artigo mostre como usar o Python, o CDKTF suporta linguagens adicionais, 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 espaço de trabalho do Azure Databricks, pois este artigo implanta recursos em um espaço de trabalho 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ê tem o Terraform instalado e verificar a versão instalada, execute o comando terraform -v a partir do seu terminal ou com o PowerShell. Instale o Terraform, se 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 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 você não tiver Node.js e npm já estiver instalado.
```
node -v
npm -v
```
A CLI CDKTF. Para verificar se você tem a CLI CDKTF instalada e para verificar a versão instalada, execute o comando cdktf --version. Instale a CLI CDKTF usando npm, se ainda não a tiver instalada.
```
cdktf --version
```
Gorjeta

Você também pode instalar a CLI do CDKTF no macOS com o 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 Python e pipenv instalado, e para verificar as versões instaladas, execute os comandos python --version e pipenv --version. Instale o Python e instale o pipenv, se ainda não estiverem instalados.
```
python --version
pipenv --version
```
Autenticação do Azure Databricks configurada para o tipo de autenticação suportado que pretende utilizar. Consulte Autenticação na documentação do provedor Databricks Terraform.

Etapa 1: Criar um projeto CDKTF

Nesta etapa, 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 dentro dessa estrutura de diretórios.

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:

Unix, Linux e macOS
```
mkdir cdktf-demo
cd cdktf-demo
```
Windows
```
md cdktf-demo
cd cdktf-demo
```
Crie um projeto CDKTF executando o seguinte comando:
```
cdktf init --template=python --local
```
Quando for solicitado um Nome do Projeto, aceite o nome do projeto padrão pressionando cdktf-demo Enter.
Quando for solicitada uma Descrição do Projeto, aceite a descrição padrão do projeto pressionando Enter.
Se lhe for pedido Pretende iniciar a partir de um projeto Terraform existente, introduza N e prima Enter.
Se lhe for pedido Pretende enviar relatórios de falhas para a equipa CDKTF, introduza n e prima Enter.

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

.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 definições de configuração.
help, que contém informações sobre algumas próximas etapas que você pode tomar 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.

Etapa 2: Definir recursos

Nesta etapa, você usa o provedor Terraform CDK Databricks para definir um bloco de anotações e um trabalho para executar esse bloco de anotações.

Instale as dependências do projeto: usando pipenv, instale em seu projeto CDKTF o Terraform CDK Databricks Provider para gerar recursos do Azure Databricks. Para fazer isso, execute o seguinte:
```
pipenv install cdktf-cdktf-provider-databricks
```

Substitua o main.py conteúdo do arquivo pelo código a seguir. Esse código autentica o CDKTF com seu espaço de trabalho do Azure Databricks e, em seguida, gera um bloco de anotações junto com um trabalho para executar o bloco de anotações. Para exibir a documentação de sintaxe desse código, consulte a referência de construção do provedor Terraform 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()

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 tempo de execução 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ê usa a CLI CDKTF para implantar, em seu espaço de trabalho existente do Azure Databricks, o bloco de anotações definido e o trabalho para executar esse bloco de anotações.

Gere o código Terraform equivalente para o seu projeto CDKTF. Para tal, execute o comando cdktf synth.
```
cdktf synth
```
Antes de fazer alterações, você pode revisar as alterações de recursos pendentes. Execute o seguinte:
```
cdktf diff
```
Implante o bloco de anotações e o trabalho executando o cdktf deploy comando.
```
cdktf deploy
```
Quando solicitado a Aprovar, pressione Enter. O Terraform cria e implanta o bloco de anotações e o trabalho em seu espaço de trabalho.

Passo 4: Interaja com os recursos

Nesta etapa, você executa o trabalho em seu espaço de trabalho do Azure Databricks, que executa o bloco de anotações especificado.

Para exibir o bloco de anotações que o trabalho executará em seu espaço de trabalho, copie o link URL do Bloco de Anotações que aparece na saída do comando e cole-o na barra de cdk deploy endereço do navegador da Web.
Para exibir o trabalho que executa o bloco de anotações em seu espaço de trabalho, copie o link URL do trabalho que aparece na saída do comando e cole-o na barra de cdk deploy endereço do navegador da Web.
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 bloco de anotações, reimplanta o bloco de anotações alterado e usa o trabalho para executar novamente o bloco de anotações alterado.

Se não quiser fazer alterações no bloco de notas, avance para o Passo 6: Limpar.

main.py No arquivo, altere a notebook declaração de variável 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 a 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")
)

Nota

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

Regenere o código Terraform equivalente para o seu projeto CDKTF. Para fazer isso, execute o seguinte:
```
cdktf synth
```
Antes de fazer alterações, você pode revisar as alterações de recursos pendentes. Execute o seguinte:
```
cdktf diff
```
Implante as alterações do bloco de anotações executando o cdktf deploy comando.
```
cdktf deploy
```
Quando solicitado a Aprovar, pressione Enter. Terraform altera o conteúdo do caderno.
Para exibir o bloco de anotações alterado que o trabalho executará em seu espaço de trabalho, atualize o bloco de anotações aberto anteriormente ou copie o link URL do Bloco de Anotações que aparece na saída do comando e cole-o na barra de endereço do navegador da cdk deploy Web.
Para exibir o trabalho que executa o bloco de anotações alterado em seu espaço de trabalho, atualize o trabalho aberto anteriormente ou copie o link URL do trabalho que aparece na saída do comando e cole-o na barra de endereço do navegador da cdk deploy Web.
Para executar o trabalho, clique no botão Executar agora na página do trabalho.

Passo 6: Limpar

Nesta etapa, você usa a CLI CDKTF para remover o bloco de anotações e o trabalho do seu espaço de trabalho do Azure Databricks.

Remova os recursos do espaço de trabalho executando o cdktf destroy comando:
```
cdktf destroy
```
Quando solicitado a Aprovar, pressione Enter. Terraform remove os recursos do seu espaço de trabalho.

Testar

Você pode testar seu projeto CDKTF antes de implantá-lo. Consulte 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 Python pytest junto com a cdktf classe do Testing pacote. O arquivo de exemplo a seguir chamado test_main.py testa o código CDKTF no arquivo anterior main.py deste artigo. O primeiro teste verifica se o bloco de anotações do projeto conterá a representação esperada codificada em Base64 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 pytest comando a partir do 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

Referência de construção do provedor Terraform CDK Databricks para TypeScript, Python, Java, C# e Go
Habilitar o registro em log para aplicativos CDKTF

Partilhar via